MCP

Sendmux has two MCP connections. Use Doc Search MCP when you want an AI tool to search Sendmux docs. Use MCP when you want an agent to work with Sendmux tools you authorise.

Connection	Use it for	Server
Doc Search MCP	Search Sendmux guides and API references.	`https://sendmux.ai/docs/mcp`
MCP	Use Management, Mailbox, and Sending tools.	`https://mcp.sendmux.ai/mcp` or the local `sendmux-mcp` package

MCP exposes a curated agent toolset, not every API endpoint. Use the SDKs, CLI, or API reference when you need full endpoint coverage.

Doc Search MCP

Doc Search MCP exposes search_sendmux.

Claude Code

claude mcp add sendmux-docs --transport http https://sendmux.ai/docs/mcp

Cursor

Add this server to .cursor/mcp.json for one project or ~/.cursor/mcp.json for all projects.

{
  "mcpServers": {
    "sendmux-docs": {
      "url": "https://sendmux.ai/docs/mcp"
    }
  }
}

VS Code

Add this server to your user or workspace mcp.json.

{
  "servers": {
    "sendmux-docs": {
      "type": "http",
      "url": "https://sendmux.ai/docs/mcp"
    }
  }
}

Codex

Add this server to ~/.codex/config.toml or a trusted project .codex/config.toml.

[mcp_servers.sendmux_docs]
url = "https://sendmux.ai/docs/mcp"

MCP exposes the product surfaces you grant.

Surface	Use it for	Access
Mailbox	Search, read, organise, and send from granted mailboxes.	Hosted grant with Mailbox access, an `smx_mbx_` key, or a scoped `smx_agent_` token locally
Management	Manage team resources such as domains, mailboxes, sending accounts, logs, metrics, billing, and webhooks.	Hosted grant with Management access, or an `smx_root_` key locally
Sending	Send single or batch emails.	Hosted grant with Sending access, an `smx_mbx_` key, or an owner-approved Sending-resource `smx_agent_` token locally

Hosted MCP is the default when your client supports remote MCP with browser OAuth. It keeps Sendmux in the authorisation flow, avoids distributing manual API keys to agents, and shows only the tools allowed by the grant.

Setting	Value
Server URL	`https://mcp.sendmux.ai/mcp`
Authorisation server	`https://app.sendmux.ai`
Health check	`https://mcp.sendmux.ai/health`

Use the Postman collection when you want to test MCP requests from Postman:

When you connect, Sendmux asks you to choose a team, product surfaces, and mailbox access where relevant. Access tokens are short-lived. Refresh tokens rotate on use and can last up to 30 days unless the connection is disconnected or expires.

If you grant more than one mailbox, start mailbox workflows with mailbox_list_granted_mailboxes and pass the returned mailbox_id to tools that act on one mailbox.

Connection modes

Hosted OAuth

Use when your client can open a browser-based MCP OAuth flow.

Local stdio

Use when your coding agent can launch a local command on your machine.

Private HTTP

Use when a client needs a URL but you run the MCP package yourself.

Local package

Install the local package from PyPI:

pip install sendmux-mcp

Run one surface:

SENDMUX_API_KEY=smx_mbx_... sendmux-mcp-mailbox
SENDMUX_API_KEY=smx_root_... sendmux-mcp-management
SENDMUX_API_KEY=smx_mbx_... sendmux-mcp-sending

Run all product surfaces:

SENDMUX_MCP_SURFACES=mailbox,management,sending \
SENDMUX_MAILBOX_API_KEY=smx_mbx_... \
SENDMUX_MANAGEMENT_API_KEY=smx_root_... \
SENDMUX_SENDING_API_KEY=smx_mbx_... \
sendmux-mcp

The server validates key prefixes before starting. Management requires smx_root_. Sending accepts a send-capable smx_mbx_ key or owner-approved Sending-resource smx_agent_ token. Mailbox accepts an smx_mbx_ key or a scoped smx_agent_ token.

Private HTTP

HTTP mode is useful when your MCP client connects to a server URL but you still want to run the package yourself.

SENDMUX_API_KEY=smx_mbx_... \
SENDMUX_MCP_HTTP_BEARER_TOKEN=local-mcp-token \
sendmux-mcp-mailbox --transport http --host 127.0.0.1 --port 8765

The endpoint defaults to /mcp. /health returns the selected surfaces. HTTP mode requires SENDMUX_MCP_HTTP_BEARER_TOKEN unless you explicitly start it with --allow-unauthenticated-http.

Configuration reference

Environment variables

Setting	Environment	Default
Tool surfaces	`SENDMUX_MCP_SURFACES`	Required for `sendmux-mcp`
API key fallback	`SENDMUX_API_KEY`	None
Mailbox API key	`SENDMUX_MAILBOX_API_KEY`	None
Management API key	`SENDMUX_MANAGEMENT_API_KEY`	None
Sending API key	`SENDMUX_SENDING_API_KEY`	None
Management and Mailbox API base URL	`SENDMUX_APP_BASE_URL`	`https://app.sendmux.ai/api/v1`
Sending API base URL	`SENDMUX_SENDING_BASE_URL`	`https://smtp.sendmux.ai/api/v1`
Transport	`SENDMUX_MCP_TRANSPORT`	`stdio`
HTTP host	`SENDMUX_MCP_HOST`	`127.0.0.1`
HTTP port	`SENDMUX_MCP_PORT`	`8765`
HTTP path	`SENDMUX_MCP_PATH`	`/mcp`
HTTP bearer token	`SENDMUX_MCP_HTTP_BEARER_TOKEN`	Required for HTTP
Allowed browser origins	`SENDMUX_MCP_ALLOWED_ORIGINS`	No browser origins

Command flags

sendmux-mcp \
  --surfaces mailbox,management,sending \
  --mailbox-api-key smx_mbx_... \
  --management-api-key smx_root_... \
  --sending-api-key smx_mbx_...

Tool discovery

How tool discovery works

Tool names are generated from the current public API surfaces. Open your MCP client’s tool picker after authorisation to see the tools available to that connection.Hosted connections show only the tools allowed by the selected product surfaces, permissions, and mailbox grant. Local servers show the tools for the surfaces and keys you provide at startup.

Troubleshooting

No tools appear

Confirm the selected product surfaces and granted permissions. Hosted connections show only tools allowed by the grant.

Local server fails before starting

Check the API key prefix. Management needs smx_root_; Sending accepts smx_mbx_ or owner-approved Sending-resource smx_agent_; Mailbox accepts smx_mbx_ or scoped smx_agent_.

HTTP server returns 401

Send Authorization: Bearer <SENDMUX_MCP_HTTP_BEARER_TOKEN> to private HTTP, or complete OAuth for hosted MCP.

HTTP server returns 403 origin_forbidden

Add the browser client’s origin to SENDMUX_MCP_ALLOWED_ORIGINS for private HTTP.

Too many tools in one client

Connect only the surfaces you need, or disable unused tools in the client.

Next steps

MCP clients

Configure Sendmux MCP in Claude Code, Cursor, Codex, Gemini CLI, Qwen Code, Zed, and more.

SDKs

Use package-managed clients from application code.

CLI

Install the CLI with Snap, Homebrew, or npm when you need terminal access.

API keys

Create scoped credentials for local MCP setups.

Getting started

SDKs

CLI

Integrations

AI integrations

Teams and access

Sending

Receiving

Monitoring

Billing

Webhooks

MCP

Doc Search MCP

MCP

Connection modes

Hosted OAuth

Local stdio

Private HTTP

Local package

Private HTTP

Configuration reference

Tool discovery

Troubleshooting

Next steps

MCP clients

SDKs

CLI

API keys

​Doc Search MCP

​MCP

​Connection modes

Hosted OAuth

Local stdio

Private HTTP

​Local package

​Private HTTP

​Configuration reference

​Tool discovery

​Troubleshooting

​Next steps

MCP clients

SDKs

CLI

API keys

Doc Search MCP

MCP

Connection modes

Local package

Private HTTP

Configuration reference

Tool discovery

Troubleshooting

Next steps