Model Context Protocol

Sendbound has two MCP transports. Both call the same project API:

• Remote Streamable HTTP: use the MCP server URL with Authorization: Bearer <your-secret-project-key> on every request. Anonymous access and a shared server-owned fallback key are not supported.
• Local stdio: the npm package is @sendbound/mcp, not @sendbound/mcp-server. It reads your key from server-side environment variables.

Remote configuration

Use the URL shown by your MCP deployment. For the Sendbound-hosted server, the endpoint is https://mcp.sendbound.com/mcp.

{
  "mcpServers": {
    "sendbound": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.sendbound.com/mcp", "--header", "Authorization: Bearer ${SENDBOUND_API_KEY}"],
      "env": {"SENDBOUND_API_KEY": "<set through your client’s secure environment configuration>"}
    }
  }
}

Configure the variable securely; do not paste a real key into a chat or commit it to source control. Clients with native Streamable HTTP can send the bearer header directly without mcp-remote. This server uses bearer keys, not an OAuth login flow.

Each session is bound to the caller's key. Revoked keys are checked again on subsequent requests. Sessions expire after 30 minutes without activity; reconnect after a session-expired response. Deploy a single worker or use sticky sessions when load balancing: sessions are held in memory, not shared between workers.

Browser clients must use an allowed origin; operators can configure MCP_ALLOWED_ORIGINS. A public pk_ tracking key cannot initialize the remote server.

Stdio configuration

{
  "mcpServers": {
    "sendbound": {
      "command": "npx",
      "args": ["-y", "@sendbound/mcp"],
      "env": {
        "SENDBOUND_API_KEY": "<set securely>",
        "SENDBOUND_API_URL": "https://api.sendbound.com"
      }
    }
  }
}

SENDBOUND_READ_ONLY=true removes mutating tools from the stdio server. The npm CLI retains its established convenience tools. Additional contract tools use the prefix sendbound_api_; the existing campaign-send convenience tool is retained instead of adding a second route around its audience preview and confirmation.

The CLI supports its SDK's current and legacy protocol versions. The remote server and CLI are separate deployments: installing the currently published npm version does not automatically install local, unreleased changes.

Tool input

The complete API catalog gives the remote tool name for each operation. Path parameters are top-level arguments, JSON is nested under body, and filters are nested under query.

{
  "name": "create_webhook",
  "arguments": {
    "body": {
      "url": "https://your-app.example/webhooks/inbound",
      "events": ["email.received"],
      "inboundDomain": "inbound.your-verified-domain.example",
      "inboundPattern": "*"
    }
  }
}

The corresponding stdio contract tool is sendbound_api_create_webhook. For send and batch tools, an optional top-level idempotencyKey is forwarded as the API's Idempotency-Key header. Duplicate requests return 409 rather than replaying a result.

File uploads use a body file field containing filename, contentType, and base64; the transport creates the multipart request. Attachment downloads return contentType, size, and Base64 content, subject to a 20 MiB response ceiling. Large data exports should be downloaded with the API directly.

Signing secrets and provider credentials are redacted from tool results. Retrieve those securely in the dashboard, not through a model transcript.

Permissions and approval

Remote write tools and new stdio contract write tools request human confirmation. Declining does not call the API. Clients without the required elicitation support cannot perform those writes. Headless operators may explicitly opt out using SENDBOUND_ALLOW_UNCONFIRMED_SENDS=true; doing so removes this protection.

Tools cannot administer users, API keys, enterprise SSO, or billing by borrowing a project key. Administrator endpoints, provider callbacks, tracking-only browser operations, and credential-import operations are intentionally not remote tools. See Coverage & Permissions for the complete classification.

Inbound receiving tools cover domain settings, routes, test messages, email listing/detail, private attachments, signing-secret rotation, and delivery history. A synthetic route test proves webhook plumbing, not external SMTP or MX delivery. The inbound guide describes those separate checks.