kubbiai

MCP Integration

kubbi ships an MCP-compatible tool server. Install it once 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

The server runs via npx. No global install needed. Add the config to your MCP client and replace the API key with your own.

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

Add this 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: full kubbi detail JSON

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.”