> ## Documentation Index
> Fetch the complete documentation index at: https://sendmux.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP

> Connect AI tools to Sendmux documentation and product tools.

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 |

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

## Doc Search MCP

Doc Search MCP exposes `search_sendmux`.

<AccordionGroup>
  <Accordion title="Claude Code">
    ```bash theme={null}
    claude mcp add sendmux-docs --transport http https://sendmux.ai/docs/mcp
    ```
  </Accordion>

  <Accordion title="Cursor">
    Add this server to `.cursor/mcp.json` for one project or `~/.cursor/mcp.json` for all projects.

    ```json theme={null}
    {
      "mcpServers": {
        "sendmux-docs": {
          "url": "https://sendmux.ai/docs/mcp"
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="VS Code">
    Add this server to your user or workspace `mcp.json`.

    ```json theme={null}
    {
      "servers": {
        "sendmux-docs": {
          "type": "http",
          "url": "https://sendmux.ai/docs/mcp"
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Codex">
    Add this server to `~/.codex/config.toml` or a trusted project `.codex/config.toml`.

    ```toml theme={null}
    [mcp_servers.sendmux_docs]
    url = "https://sendmux.ai/docs/mcp"
    ```
  </Accordion>
</AccordionGroup>

## 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:

<a href="https://god.gw.postman.com/run-collection/6a35f8625c47dbcfb6327aa1?action=collection%2Ffork&source=rip_markdown&collection-url=entityId%3D6a35f8625c47dbcfb6327aa1%26entityType%3Dcollection%26workspaceId%3Df4e271d9-e749-4386-b2ca-bee78917b3d1" rel="nofollow noopener noreferrer" target="_blank">
  <img src="https://run.pstmn.io/button.svg" alt="Run in Postman" />
</a>

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.

<Note>
  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.
</Note>

## Connection modes

<CardGroup cols={2}>
  <Card title="Hosted OAuth" icon="shield-check" href="/docs/guides/mcp-clients#hosted-oauth-clients">
    Use when your client can open a browser-based MCP OAuth flow.
  </Card>

  <Card title="Local stdio" icon="terminal" href="/docs/guides/mcp-clients#local-stdio-clients">
    Use when your coding agent can launch a local command on your machine.
  </Card>

  <Card title="Private HTTP" icon="network" href="/docs/guides/mcp-clients#private-http-clients">
    Use when a client needs a URL but you run the MCP package yourself.
  </Card>
</CardGroup>

## Local package

Install the local package from PyPI:

```bash theme={null}
pip install sendmux-mcp
```

Run one surface:

```bash theme={null}
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:

```bash theme={null}
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.

```bash theme={null}
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

<AccordionGroup>
  <Accordion title="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               |
  </Accordion>

  <Accordion title="Command flags">
    ```bash theme={null}
    sendmux-mcp \
      --surfaces mailbox,management,sending \
      --mailbox-api-key smx_mbx_... \
      --management-api-key smx_root_... \
      --sending-api-key smx_mbx_...
    ```
  </Accordion>
</AccordionGroup>

## Tool discovery

<Accordion title="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.
</Accordion>

## Troubleshooting

<AccordionGroup>
  <Accordion title="No tools appear">
    Confirm the selected product surfaces and granted permissions. Hosted connections show only tools allowed by the grant.
  </Accordion>

  <Accordion title="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_`.
  </Accordion>

  <Accordion title="HTTP server returns 401">
    Send `Authorization: Bearer <SENDMUX_MCP_HTTP_BEARER_TOKEN>` to private HTTP, or complete OAuth for hosted MCP.
  </Accordion>

  <Accordion title="HTTP server returns 403 origin_forbidden">
    Add the browser client's origin to `SENDMUX_MCP_ALLOWED_ORIGINS` for private HTTP.
  </Accordion>

  <Accordion title="Too many tools in one client">
    Connect only the surfaces you need, or disable unused tools in the client.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="MCP clients" icon="plug" href="/docs/guides/mcp-clients">
    Configure Sendmux MCP in Claude Code, Cursor, Codex, Gemini CLI, Qwen Code, Zed, and more.
  </Card>

  <Card title="SDKs" icon="code" href="/docs/sdks">
    Use package-managed clients from application code.
  </Card>

  <Card title="CLI" icon="terminal" href="/docs/cli">
    Install the CLI with Snap, Homebrew, or npm when you need terminal access.
  </Card>

  <Card title="API keys" icon="key" href="/docs/guides/api-keys">
    Create scoped credentials for local MCP setups.
  </Card>
</CardGroup>