MCP (remote + local) · Integrations docs

Remote server (recommended)#

BotInbox hosts an MCP server at https://botinbox.dev/mcp (Streamable HTTP). Authenticate with an API key in the Authorization header; tools respect the key's scope, so an inbox key only sees its inbox. The dashboard's "Connect your agent" panel creates a scoped key and fills in these snippets.

Shell

claude mcp add --transport http botinbox https://botinbox.dev/mcp \
  --header "Authorization: Bearer $BOTINBOX_API_KEY"

Cursor, Windsurf, and VS Code#

Cursor (~/.cursor/mcp.json) uses url + headers as below; Windsurf (~/.codeium/windsurf/mcp_config.json) uses serverUrl + headers; VS Code (.vscode/mcp.json) uses type "http" with url and headers and can prompt for the key with an input variable.

JSON

{
  "mcpServers": {
    "botinbox": {
      "url": "https://botinbox.dev/mcp",
      "headers": {
        "Authorization": "Bearer bi_your_key"
      }
    }
  }
}

Local (stdio) clients#

For clients that only launch local commands, such as Claude Desktop's config file, bridge to the hosted server with the open-source mcp-remote package. You get the same tools and the same key scope. Requires Node.js 18+. A native @botinbox/mcp package is coming soon.

JSON

{
  "mcpServers": {
    "botinbox": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://botinbox.dev/mcp",
        "--header",
        "Authorization:${BOTINBOX_AUTH}"
      ],
      "env": {
        "BOTINBOX_AUTH": "Bearer bi_your_key"
      }
    }
  }
}

Note

The CLI prints this snippet with your stored key already filled in: botinbox mcp --client claude-desktop --show-key.

Tools#

list_inboxes, create_inbox, get_inbox, send_email, reply_to_message, list_messages (unread, query, from, since, label), get_message (full body, reply_text, attachment metadata), mark_read, list_threads, get_thread, create_draft, send_draft, list_labels, add_label, remove_label, wait_for_email, account_usage, and the conversation insights tools set_message_sentiment, set_conversation_outcome, request_human_handoff, cancel_human_handoff and get_conversation_insights (see Conversation insights). Read-only tools carry readOnlyHint so clients can auto-approve them. Tools that take inbox_id may omit it when the key can access exactly one inbox.

Verification codes with wait_for_email#

Trigger the email elsewhere (for example a sign-up form using your inbox address), then call wait_for_email with from and/or subject_contains. It blocks up to 55 seconds and returns the newest matching unread message from the last 5 minutes, plus detected numeric codes and links. On timeout it returns status timeout; call it again to keep waiting.

JSON

{"name":"wait_for_email","arguments":{"from":"github.com","subject_contains":"verification","timeout_seconds":45}}

Protocol details#

POST one JSON-RPC message per request; responses are application/json and notifications return 202. The server supports MCP 2026-07-28 (stateless requests with _meta, server/discover, and the MCP-Protocol-Version, Mcp-Method, and Mcp-Name headers) and initialize-based clients from 2024-11-05 through 2025-11-25. There are no sessions, GET and DELETE return 405, and a missing or invalid key returns 401. Tool calls count against the key's API rate limit.

Security#

Prefer one inbox- or pod-scoped key per agent rather than an account key. Email content is untrusted: the server instructions tell the model not to follow instructions found inside messages without the user's confirmation. Requests from unknown browser origins are rejected; CLI, IDE, and desktop clients are unaffected.