{
  "markdown": "# Tillpad MCP\r\n\r\n**Bounded storage and search for agent jobs.**\r\n\r\n[![Remote MCP](https://img.shields.io/badge/MCP-remote-555?style=flat-square)](https://tillpad.cnrcode.com/mcp)\r\n[![Transport](https://img.shields.io/badge/transport-streamable--http-0ea5e9?style=flat-square)](https://modelcontextprotocol.io)\r\n[![Auth](https://img.shields.io/badge/auth-Bearer%20tp__-111?style=flat-square)](https://tillpad.cnrcode.com)\r\n[![License: MIT](https://img.shields.io/badge/license-MIT-green?style=flat-square)](./LICENSE)\r\n\r\nTillpad gives agents namespaced key-value storage, file upload + semantic search, receive-only email inboxes, budget-aware metering, and run keys that wipe with a signed receipt when the job is done.\r\n\r\n**Live endpoint:** [`https://tillpad.cnrcode.com/mcp`](https://tillpad.cnrcode.com/mcp)\r\n\r\n> This repository is the **public catalog and schema stub** for directory crawlers. It is not the hosted server. Point MCP clients at the live URL above with a Tillpad API key. Running the TypeScript in this repo does not store or search anything.\r\n\r\n**Agent guide:** see [AGENTS.md](./AGENTS.md) for discovery URLs, auth, and MCP connect snippets.\r\n\r\n## Get an API key\r\n\r\n### Zero-human (agents)\r\n\r\n1. `POST https://tillpad.cnrcode.com/api/agents/bootstrap` with `{ \"email\": \"agent@example.com\" }` → `bootstrapToken` (no outbound mail).\r\n2. `POST https://tillpad.cnrcode.com/api/billing/machine-pay` with `Authorization: Bearer <bootstrapToken>` and optional `{ \"sku\": \"pro_prepaid_30d\" }`.\r\n3. Settle Stripe MPP ($9.00 / 30 days) → response includes `secret` (`tp_…`) and `planPeriodEnd`.\r\n\r\nSee [scratchpad.txt](https://tillpad.cnrcode.com/scratchpad.txt) and [llms-full.txt](https://tillpad.cnrcode.com/llms-full.txt). Legal: [Terms](https://tillpad.cnrcode.com/terms).\r\n\r\n### Human path\r\n\r\n1. Open [tillpad.cnrcode.com](https://tillpad.cnrcode.com) and create an account.\r\n2. Subscribe to Tillpad Pro on [Pricing](https://tillpad.cnrcode.com/pricing), then mint an API key in the dashboard. Secrets start with `tp_`.\r\n3. Use an **account** key for ongoing access, or a **run** key when the job should expire and wipe.\r\n\r\nNever commit a real key. Use the `tp_…` placeholder in configs.\r\n\r\n## Connect a client\r\n\r\nTransport is **Streamable HTTP**. Send `Authorization: Bearer tp_…` on every request.\r\n\r\n### Cursor\r\n\r\n#### Install via Cursor Marketplace (plugin)\r\n\r\nThis repo includes a [Cursor plugin manifest](.cursor-plugin/plugin.json) and root [`mcp.json`](mcp.json) for one-click install from the [Cursor Marketplace](https://cursor.com/marketplace/publish).\r\n\r\nTillpad MCP tools cover namespaced KVP, RAG search, **receive-only email inboxes** (temporary/permanent addresses, webhooks, blocklist, raw MIME read), budget metering, and run-key wipe receipts.\r\n\r\n1. Install the **Tillpad** plugin from the marketplace (or test locally — see below).\r\n2. Open **Cursor Settings → Customize → Tillpad** and set **Tillpad API key** (`tp_…` from bootstrap + machine-pay or the dashboard).\r\n3. Reload the window. MCP tools should appear under the Tillpad server.\r\n\r\nThe plugin points at `https://tillpad.cnrcode.com/mcp` with `Authorization: Bearer ${TILLPAD_API_KEY}`. Never commit a real key.\r\n\r\n**Local plugin test** (before marketplace submission):\r\n\r\n```powershell\r\n# Copy catalog repo into Cursor local plugins folder\r\n$dest = \"$env:USERPROFILE\\.cursor\\plugins\\local\\tillpad\"\r\nNew-Item -ItemType Directory -Force -Path $dest | Out-Null\r\nCopy-Item -Recurse -Force \"C:\\dev\\tillpad\\tillpad-mcp\\*\" $dest\r\n# Then: Cursor Customize → Tillpad → set TILLPAD_API_KEY → Developer: Reload Window\r\n```\r\n\r\nSubmit the public repo at [cursor.com/marketplace/publish](https://cursor.com/marketplace/publish) when ready.\r\n\r\n#### Manual MCP config\r\n\r\nUser or project MCP config:\r\n\r\n```json\r\n{\r\n  \"mcpServers\": {\r\n    \"tillpad\": {\r\n      \"url\": \"https://tillpad.cnrcode.com/mcp\",\r\n      \"headers\": {\r\n        \"Authorization\": \"Bearer tp_…\"\r\n      }\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n### Claude Desktop / Claude Code\r\n\r\n```json\r\n{\r\n  \"mcpServers\": {\r\n    \"tillpad\": {\r\n      \"command\": \"npx\",\r\n      \"args\": [\"mcp-remote\", \"https://tillpad.cnrcode.com/mcp\", \"--header\", \"Authorization: Bearer tp_…\"]\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n### Generic remote MCP\r\n\r\n```json\r\n{\r\n  \"url\": \"https://tillpad.cnrcode.com/mcp\",\r\n  \"headers\": {\r\n    \"Authorization\": \"Bearer tp_…\"\r\n  }\r\n}\r\n```\r\n\r\nDiscovery manifests on the product host:\r\n\r\n- [/.well-known/mcp.json](https://tillpad.cnrcode.com/.well-known/mcp.json)\r\n- [/.well-known/mcp/server.json](https://tillpad.cnrcode.com/.well-known/mcp/server.json)\r\n- [/llms.txt](https://tillpad.cnrcode.com/llms.txt)\r\n\r\n## Tools\r\n\r\nSchemas in [`src/server.ts`](src/server.ts) match the hosted server.\r\n\r\n| Tool | What it does |\r\n|------|----------------|\r\n| `usage_get` | Current period usage and quotas |\r\n| `budget_get` | Remaining quotas, soft thresholds, and a checkout URL |\r\n| `budget_estimate` | Preflight 402/429 before spending (`textLength` / `byteLength` for `rag_index`) |\r\n| `billing_machine_pay` | How agents unlock prepaid Pro or buy SKUs via Stripe MPP (`sku` optional) |\r\n| `billing_portal` | Stripe Customer Portal URL for subscription management and invoices |\r\n| `billing_purchases_list` | Local payment history; optional `includeStripe` for backfill |\r\n| `agent_bootstrap` | Zero-human onboarding: bootstrap token from email (no outbound mail) |\r\n| `keys_create` | Mint a run/sub key from an account `tp_` key |\r\n| `kvp_put` | Store a string under a namespace/key (response includes `budget`) |\r\n| `kvp_get` | Read a namespaced value |\r\n| `kvp_delete` | Delete a KVP key |\r\n| `kvp_list` | List keys in a namespace |\r\n| `file_upload` | Upload UTF-8 text for RAG indexing (prefLights `rag_index`) |\r\n| `files_list` | List uploaded files |\r\n| `files_types` | Supported upload extensions and MIME types |\r\n| `rag_search` | Semantic search over indexed documents |\r\n| `inspect_storage` | Namespace inventory (scoped to the key when applicable) |\r\n| `run_finish` | Wipe namespaces bound to this **run** key; returns a signed wipe receipt |\r\n| `support_contact` | Contact Tillpad support from a **Pro** account; replies go to the account email |\r\n| `inbox_create` | Create a receive-only email inbox (temporary or permanent) |\r\n| `inbox_list` | List active receive-only inboxes |\r\n| `inbox_get` | Get one inbox by id |\r\n| `inbox_delete` | Delete an inbox and purge stored messages |\r\n| `inbox_messages_list` | List message metadata for an inbox |\r\n| `inbox_message_get` | Get message metadata and attachment list |\r\n| `inbox_message_raw` | Download raw MIME (meters 1 kvp_op) |\r\n| `inbox_attachment_get` | Download an attachment as base64 (meters 1 kvp_op) |\r\n| `inbox_webhook_create` | Register HTTPS webhook for `email.received` (metadata only) |\r\n| `inbox_webhook_list` | List registered email webhooks |\r\n| `inbox_webhook_delete` | Disable an email webhook |\r\n| `inbox_webhook_deliveries_list` | Webhook delivery log; use `status=failed` for failures |\r\n| `inbox_audit_list` | Inbox audit log for the account |\r\n| `inbox_blocklist_list` | List blocked sender addresses and domains |\r\n| `inbox_blocklist_add` | Block a sender address or entire domain |\r\n| `inbox_blocklist_delete` | Remove a blocklist entry |\r\n\r\n## Typical agent loop\r\n\r\n1. Mint a **run** key in the dashboard (dedicated namespace, TTL, optional op budget).\r\n2. Store working state with `kvp_put` and/or `file_upload`.\r\n3. Retrieve with `kvp_get` / `kvp_list` and `rag_search`.\r\n4. Call `run_finish` to wipe run namespaces and keep the signed receipt.\r\n\r\nUse `budget_estimate` before large index jobs. `budget_get` / `usage_get` show what is left in the period.\r\n\r\n## Auth and errors\r\n\r\n- **401** — missing or invalid `Authorization: Bearer tp_…`\r\n- **402 / 429** — plan or quota. JSON includes `code`, `status`, `actions`, and `budget`\r\n  - `actions[].type: \"checkout\"` — hosted Stripe Checkout URL for a **recurring** human subscription\r\n  - `actions[].type: \"machine_pay\"` — agent prepaid Pro (30/90 days) or top-up SKUs via Stripe MPP; default sku `pro_prepaid_30d` at $9.00\r\n\r\nThis is Stripe Machine Payments Protocol, not ChatGPT Instant Checkout / ACP.\r\n\r\n## Product docs\r\n\r\n- App: [tillpad.cnrcode.com](https://tillpad.cnrcode.com)\r\n- Docs: [tillpad.cnrcode.com/docs](https://tillpad.cnrcode.com/docs)\r\n- Scratchpad: [tillpad.cnrcode.com/docs/scratchpad](https://tillpad.cnrcode.com/docs/scratchpad)\r\n- OpenAPI: [tillpad.cnrcode.com/openapi.json](https://tillpad.cnrcode.com/openapi.json)\r\n\r\nThe Tillpad product (Worker, billing, storage) is closed source. This catalog is MIT-licensed so directories can list tools and install snippets.\r\n\r\n## Directory listing\r\n\r\nRegistry name: **`com.cnrcode/tillpad`** (domain namespace via [cnrcode.com](https://cnrcode.com/.well-known/mcp-registry-auth)).\r\n\r\n1. Ensure `https://cnrcode.com/.well-known/mcp-registry-auth` is deployed (`cnrcode-site` repo).\r\n2. Set GitHub repo secret **`MCP_PRIVATE_KEY`** (hex; see `cnrcode-site` key generation script).\r\n3. Push a version tag so [GitHub Actions](.github/workflows/publish-mcp.yml) publishes `server.json` to the [official MCP Registry](https://registry.modelcontextprotocol.io):\r\n\r\n   ```bash\r\n   git tag v0.1.1\r\n   git push origin v0.1.1\r\n   ```\r\n\r\n4. Optionally submit [https://github.com/number1101/tillpad-mcp](https://github.com/number1101/tillpad-mcp) at [mcp.directory/submit](https://mcp.directory/submit).\r\n\r\n### Glama\r\n\r\nThis repo includes a **stdio catalog stub** (`src/main.ts`) so [Glama](https://glama.ai/mcp/servers) can build a container, start the process, and introspect the **35** tool definitions. It does not implement storage or billing — clients still connect to the hosted endpoint above.\r\n\r\nListing: [glama.ai/mcp/servers/number1101/tillpad-mcp](https://glama.ai/mcp/servers/number1101/tillpad-mcp)\r\n\r\nAfter claiming via [`glama.json`](glama.json), configure the Dockerfile admin page:\r\n\r\n| Field | Value |\r\n|-------|-------|\r\n| Build steps | `[\"npm ci\", \"npm run build\"]` |\r\n| CMD arguments | `[\"node\", \"dist/main.js\"]` |\r\n| Env schema | default (empty — no credentials needed) |\r\n| Placeholder params | `{}` |\r\n\r\nGlama generates its own Dockerfile from that form; the repo [`Dockerfile`](Dockerfile) is for local smoke tests only.\r\n\r\nScore badge (for awesome-mcp-servers and similar lists):\r\n\r\n```markdown\r\n[![number1101/tillpad-mcp MCP server](https://glama.ai/mcp/servers/number1101/tillpad-mcp/badges/score.svg)](https://glama.ai/mcp/servers/number1101/tillpad-mcp)\r\n```\r\n\r\nLocal verify:\r\n\r\n```bash\r\nnpm ci && npm run build && npm start   # hangs on stdio — expected\r\ndocker build -t tillpad-mcp-stub . && docker run -i tillpad-mcp-stub\r\n```\r\n\r\nFull step-by-step (claim, admin Dockerfile, release, awesome-mcp PR): [docs/glama-release.md](docs/glama-release.md).\r\n\r\n## License\r\n\r\n[MIT](./LICENSE) — catalog, documentation, and schema stub only.\r\n",
  "bytes": 10866,
  "sha": "747206a702297dd4cb5122b5fe1226af7d440de7069952b179dc2e08fdd3b733",
  "repo_slug": "number1101/tillpad-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_com_cnrcode_tillpad_54a31851/readme"
}