MCP Integration

kubbi runs a hosted MCP server at mcp.kubbi.ai. Point any MCP-compatible client at the URL with your API key and every agent in your stack can create, claim, inspect, and delete temporary encrypted handoffs, including multi-file packages, with no SDK wiring required.

What is MCP?

The Model Context Protocol (MCP) is an open standard that lets AI agents discover and call tools at runtime. Instead of hard-coding integrations, agents connect to MCP servers and use whatever tools they expose. kubbi's MCP server exposes six tools that any MCP-compatible agent can use immediately.

Why pair MCP with kubbi

MCP routes tool calls between agents. It carries control. It is awkward for payloads: tool results sit in agent context, get logged across hops, and can balloon prompts.

kubbi takes the payload off the MCP channel. The producer's kubbi_send returns a claim URL. The MCP tool result carries only the URL. Another vendor's agent calls kubbi_claim when ready. Neither side exposes a bucket. See the side-channel pattern for the general framing, and cross-vendor MCP handoff for concrete examples.

Installation

Two ways to connect, depending on what your MCP client supports. Both expose the same six tools.

Hosted (recommended)

If your MCP client speaks the Streamable HTTP transport, point it at the hosted endpoint with your API key in the Authorization header. Nothing to install; the latest tools are always available.

Hosted MCP config· json

{
  "mcpServers": {
    "kubbi": {
      "url": "https://mcp.kubbi.ai/mcp",
      "headers": {
        "Authorization": "Bearer kb_..."
      }
    }
  }
}

The hosted server is stateless and the API key is read from the request header, so the same endpoint can serve agents from different organizations — each authenticates with its own key, and rate limits and quotas apply to that creator.

Stdio (local)

For clients that only support the stdio transport, run the published npm binary instead. The API key is set once in the process environment.

Stdio MCP config· json

{
  "mcpServers": {
    "kubbi": {
      "command": "npx",
      "args": ["-y", "@kubbi.ai/mcp"],
      "env": {
        "KUBBI_API_KEY": "kb_..."
      }
    }
  }
}

Add either config to the file your MCP client reads from:

Claude Desktop: claude_desktop_config.json
Cursor: .cursor/mcp.json

Get your API key from the dashboard.

Available tools

kubbi_send

Create a kubbi, an ephemeral, encrypted payload with a unique claim URL. Share the claim URL with any consumer (agent, service, human) who can retrieve the content with no API key.

Parameters

contentcontentTypettlSecondsmaxRetrievalsmetadata

Returns: claim URL, kubbi ID, status, content type, max retrievals, expires-at, and metadata if set

kubbi_send_files

Create a multi-file kubbi package: multiple files encrypted together with a single claim URL. For text files, pass content as a string. For binary files, base64-encode the content and set encoding to ‘base64’.

Note: the MCP tool currently accepts 1 to 5 files with a 5 MB total cap, regardless of plan tier. To send up to 10 files or 25 MB on the Enterprise tier, use the REST API or SDK directly.

Parameters

filesttlSecondsmaxRetrievalsmetadata

Returns: claim URL + kubbi ID + file count

kubbi_claim

Claim a kubbi and retrieve its decrypted content. This counts as a retrieval. If max retrievals is reached, the content is permanently destroyed afterward. Works for both single-content and multi-file kubbis.

Parameters

claimUrl

Returns: decrypted content (or all files for packages)

kubbi_inspect

Inspect a kubbi without consuming it. Returns metadata (status, content type, retrieval count, expiry). For multi-file kubbis, also shows the file manifest. Does not count as a retrieval, so it is safe to call repeatedly.

Parameters

claimUrl

Returns: metadata (status, content type, retrieval count, expiry, file manifest for packages)

kubbi_get

Get detailed metadata for a kubbi you created (by ID). Shows status, retrieval count, timestamps, and whether it has been claimed.

Parameters

id

Returns: id, status, content type or file count, max retrievals, retrieval count, first/last retrieved timestamps, created/expires, metadata

kubbi_delete

Delete (burn) a kubbi you created. Immediately wipes the encrypted payload. Any subsequent claim attempts will receive 410 Gone.

Parameters

id

Returns: confirmation

Example flow

Once kubbi is connected, the agent discovers the tools automatically. Describe what you need in plain language:

Agent sends a single-content kubbi· text

Tool call:  kubbi_send({
  content: "analysis result...",
  contentType: "application/json",
  ttlSeconds: 600,
  maxRetrievals: 1
})

Tool result: {
  "claimUrl": "https://api.kubbi.ai/r/abc123xyz",
  "id": "d290f1ee-6c54-4b01-90e6-d701748f0851"
}

Agent sends a multi-file package· text

Tool call:  kubbi_send_files({
  files: [
    { name: "report.json", content: "{...}", contentType: "application/json", role: "data" },
    { name: "summary.md", content: "# Summary...", contentType: "text/markdown", role: "instructions" }
  ],
  ttlSeconds: 3600
})

Tool result: {
  "claimUrl": "https://api.kubbi.ai/r/pkg456xyz",
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "fileCount": 2
}

Next agent claims the payload· text

Tool call:  kubbi_claim({
  claimUrl: "https://api.kubbi.ai/r/abc123xyz"
})

Tool result: {
  "content": "analysis result...",
  "contentType": "application/json"
}

Example prompts

1
“Create a kubbi with this analysis result and send me the claim URL.”
2
“Claim the payload at this URL and summarize what’s inside.”
3
“Store this API response as a kubbi with max_retrievals: 1 and a 1-hour TTL.”
4
“Bundle these three files into a package kubbi and give me the claim link.”
5
“Inspect the kubbi at this claim URL before I claim it.”
6
“Delete the kubbi I just created. I changed my mind.”