npm package: @kubbi.ai/mcp
Description: MCP server for Kubbi — send, claim, and inspect ephemeral encrypted payloads from any AI agent
Author: Kubbi
Latest version: 0.1.0

# @kubbi.ai/mcp

MCP server for [Kubbi](https://kubbi.ai) — send, claim, and inspect ephemeral encrypted payloads from any AI agent. Built on the [@kubbi.ai/sdk](https://www.npmjs.com/package/@kubbi.ai/sdk) TypeScript SDK.

## What This Does

This MCP server gives AI agents (Claude, Cursor, VS Code Copilot, etc.) the ability to:

- **Claim** a kubbi — retrieve encrypted content using just a claim URL (zero configuration)
- **Inspect** a kubbi — check metadata without consuming it
- **Send** a kubbi — create an ephemeral payload and get a shareable claim URL
- **Get/Delete** kubbis you've created

The consumer tools (`kubbi_inspect`, `kubbi_claim`) need **zero auth** — any agent can receive and consume kubbis with no API key, no account, no setup. This is the killer feature for agent-to-agent handoffs.

## Quick Start

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

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

### Cursor

Add to `.cursor/mcp.json` in your project or global settings:

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

### VS Code

Add to `.vscode/mcp.json`:

```json
{
  "servers": {
    "kubbi": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@kubbi.ai/mcp"],
      "env": {
        "KUBBI_API_KEY": "kb_your_key_here"
      }
    }
  }
}
```

> **Consumers only?** Omit `KUBBI_API_KEY` entirely. The `kubbi_inspect` and `kubbi_claim` tools will work with no configuration at all.

## Environment Variables

| Variable | Required | Description |
|---|---|---|
| `KUBBI_API_KEY` | No* | API key for creating kubbis. Create one at [dashboard.kubbi.ai](https://dashboard.kubbi.ai). Only needed for producer tools. |
| `KUBBI_BASE_URL` | No | API base URL (default: `https://api.kubbi.ai`) |

*Producer tools (`kubbi_send`, `kubbi_send_files`, `kubbi_get`, `kubbi_delete`) require an API key. Consumer tools work without one.

## Tools

### kubbi_inspect (no auth)

Inspect a kubbi without consuming it. Returns metadata: status, content type, retrieval count, expiry. Does not count as a retrieval.

| Parameter | Type | Description |
|---|---|---|
| `claimUrl` | string | Full claim URL or bare claim token |

### kubbi_claim (no auth)

Claim a kubbi and retrieve its decrypted content. Counts as a retrieval — if `max_retrievals` is reached, the content is permanently destroyed.

| Parameter | Type | Description |
|---|---|---|
| `claimUrl` | string | Full claim URL or bare claim token |

### kubbi_send (requires API key)

Create an ephemeral encrypted kubbi. Returns a claim URL that any consumer can use.

| Parameter | Type | Default | Description |
|---|---|---|---|
| `content` | string or object | — | Payload to send (max 16KB) |
| `contentType` | string | `application/json` | `text/plain` or `application/json` |
| `ttlSeconds` | number | `3600` | Time-to-live in seconds (60–86400) |
| `maxRetrievals` | number | unlimited | Max claims before auto-burn. `1` = burn-after-read |
| `metadata` | object | — | Arbitrary metadata (max 1KB) |

### kubbi_send_files (requires API key)

Create a multi-file kubbi package — up to 5 files (5 MB total) encrypted together with a single claim URL. For binary files, base64-encode the content and set `encoding` to `"base64"`.

| Parameter | Type | Default | Description |
|---|---|---|---|
| `files` | array | — | Array of file objects (1–5, max 5 MB total) |
| `files[].name` | string | — | Filename (e.g. `"config.json"`) |
| `files[].content` | string | — | File content (text or base64-encoded binary) |
| `files[].contentType` | string | `text/plain` | MIME type (e.g. `application/json`, `image/png`) |
| `files[].role` | string | — | Semantic role: `instructions`, `data`, `context`, `config`, or `attachment` |
| `files[].encoding` | string | — | Set to `base64` if content is base64-encoded |
| `ttlSeconds` | number | `3600` | Time-to-live in seconds (60–86400) |
| `maxRetrievals` | number | unlimited | Max claims before auto-burn |
| `metadata` | object | — | Arbitrary metadata (max 1KB) |

### kubbi_get (requires API key)

Get detailed metadata for a kubbi you created.

| Parameter | Type | Description |
|---|---|---|
| `id` | string | Kubbi ID (UUID) |

### kubbi_delete (requires API key)

Delete a kubbi, immediately wiping the encrypted payload.

| Parameter | Type | Description |
|---|---|---|
| `id` | string | Kubbi ID (UUID) |

## Example: Agent-to-Agent Handoff

**Agent A** (has API key) creates a kubbi and passes the claim URL in its response:

> "I've stored the analysis results in a secure kubbi. Here's the claim URL: `https://api.kubbi.ai/r/x7k9m2...`"

**Agent B** (no API key, no setup) claims it:

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

The content is retrieved and automatically destroyed (if `maxRetrievals: 1`).

## Development

```bash
git clone https://github.com/kubbi/kubbi-mcp.git
cd kubbi-mcp
npm install
npm run build

# Test locally with MCP Inspector
npx @modelcontextprotocol/inspector node dist/index.js
```

## License

MIT