Connect an AI assistant (MCP)

Connect InboxAgents to an AI assistant like Claude or ChatGPT and let it provision its own inboxes and read the mail that arrives — "make me an inbox and watch for the verification email", "read the latest thread in inbox inb_8f2a1c9d", "download the attachment from that message" — instead of wiring up an integration by hand.

Fastest path: install the Skill

If you use a coding agent (Claude Code, Cursor, or Codex), install the InboxAgents Skill with one command:

npx skills add inboxagents

It preconfigures this MCP connection and teaches your agent the provision → receive → read loop, so it can create an inbox and act on incoming mail with no further setup. Set your key (below) and you're done. The manual add in Developer setup is the fallback for platforms without Skill support — nothing is lost.

The simple way (point-and-click)

Best for Claude Desktop, claude.ai, and ChatGPT — no files, no commands.

The server address is:

https://mcp.theinboxagents.com/mcp

Point-and-click clients authenticate by passing your InboxAgents API key as an x-api-key header when they add the connector.

Claude Desktop or claude.ai

1. Open Settings → Connectors → Add custom connector.
2. Paste the InboxAgents server address https://mcp.theinboxagents.com/mcp.
3. Add an x-api-key header set to your InboxAgents API key (an ia_… secret).
4. Click Add, then Connect — Claude discovers the tools and can start working your inboxes.

ChatGPT

Remote connectors need a paid ChatGPT plan with Developer mode turned on (if you want the easiest route, Claude Desktop is simpler):

1. Settings → Apps & Connectors → Advanced settings → turn on Developer mode.
2. Settings → Connectors → Create. Name it InboxAgents and set the Connector URL to https://mcp.theinboxagents.com/mcp.
3. Add your API key as an x-api-key header, then enable the connector in a conversation.

What the assistant can do

Once connected, the assistant acts with exactly the scope and permissions of the API key you gave it — nothing more. Within that scope it can:

• Provision inboxes — create, list, inspect, and delete inboxes (inbox_create and inbox_delete permissions gate the create/delete tools).
• Read mail — list threads, read a full thread or a single message, and fetch a presigned download link for an attachment.
• Check identity and usage — confirm what its key can see (whoami) and read the tenant's usage totals (get_usage, requires metrics_read).

Sending, replying, and webhook/key management are not available over MCP in v1 — manage those through the REST API or the dashboard. See every tool's fields in the API reference.

Developer setup

For coding tools. The server is a remote Streamable HTTP MCP endpoint:

https://mcp.theinboxagents.com/mcp

Authenticate with your InboxAgents API key, passed either as an x-api-key header or as an ?apiKey= query parameter on the URL. There is no OAuth dance in v1 — a single API key is all a client needs.

Claude Code

Add the server with your key as a header:

claude mcp add --transport http inboxagents https://mcp.theinboxagents.com/mcp \
  --header "x-api-key: YOUR_INBOXAGENTS_API_KEY"

Add --scope project to share it with your team via a checked-in .mcp.json, or --scope user to use it across all your projects (the default is this project only). Run /mcp inside a session to confirm the tools loaded.

Cursor

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (this project). Use ${env:VAR} so the key isn't hardcoded:

{
  "mcpServers": {
    "inboxagents": {
      "url": "https://mcp.theinboxagents.com/mcp",
      "headers": { "x-api-key": "${env:INBOXAGENTS_API_KEY}" }
    }
  }
}

Or one-click: Add to Cursor — the deeplink adds the server; set your x-api-key header afterward.

VS Code

Add to .vscode/mcp.json (workspace). Note VS Code uses servers (not mcpServers) and requires "type": "http". Prompt for the key securely with an input so it's never stored in plain text:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "inboxagents-api-key",
      "description": "InboxAgents API key",
      "password": true
    }
  ],
  "servers": {
    "inboxagents": {
      "type": "http",
      "url": "https://mcp.theinboxagents.com/mcp",
      "headers": { "x-api-key": "${input:inboxagents-api-key}" }
    }
  }
}

Or run MCP: Add Server from the Command Palette and follow the guided flow.

Query-param auth

Any client that can't set custom headers can carry the key in the URL instead:

https://mcp.theinboxagents.com/mcp?apiKey=YOUR_INBOXAGENTS_API_KEY

Prefer the x-api-key header where you can — a URL is more likely to end up in logs. Never commit either form; read the key from an environment variable or a secret input.

Other clients

Any client that supports remote Streamable HTTP MCP servers works — point it at https://mcp.theinboxagents.com/mcp and authenticate with an x-api-key header or an ?apiKey= query parameter.

Minimum client requirements

The server speaks Streamable HTTP only. A client must support remote Streamable HTTP MCP servers to connect. Clients that only support the older stdio or SSE transports can't connect — there is no silent partial connection; a missing or invalid key is rejected outright with a clear auth error and no tools are exposed. Because the server is hosted, there's nothing to install or run locally, and the tool set updates centrally.

Access & revoking

• Scope — every connection acts with exactly the connecting key's scope and permissions, and only ever sees its own tenant's data. An inbox-scoped key sees just that one inbox.
• Revoking — disconnect in your client (remove the connector in a GUI client, or drop the server from your MCP config for Claude Code / Cursor / VS Code), or delete the API key in the dashboard under Settings → API keys. Deleting a key stops it working immediately on every surface (REST, SDK, CLI, WebSocket, and MCP). There is no separate rotate step — create a new key, then delete the old one.

Troubleshooting

• Tools don't appear / connection failed — the API key is missing or invalid. Check the x-api-key header (or ?apiKey= query param) carries a current ia_… key; a rejected key exposes no tools.
• A tool returns forbidden — the key is valid but lacks that tool's permission (e.g. inbox_create) or is scoped to a different inbox. Grant the permission or use an in-scope key.
• A read returns nothing / not-found — the id is unknown or out of the key's scope (the two are indistinguishable on purpose — no cross-tenant leakage), or the inbox is simply empty (an empty result, not an error).
• Spam or unauthenticated mail is missing — it's hidden by default. Pass the include_spam / include_unauthenticated flag; reading spam also requires the key's label_spam_read permission.
• Config-file changes don't take effect — restart the client. Claude Desktop and VS Code re-read MCP config on restart.
• Client can't connect at all — confirm it supports remote Streamable HTTP MCP servers (see Minimum client requirements).

Prefer raw HTTP? Everything here is also available over the REST API with the same API key.