> ## 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 Qubrics documentation and product tools.

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

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

> [!NOTE]
>
> 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`.

> [accordion] Claude Code
>
> ```bash theme={null}
> claude mcp add sendmux-docs --transport http https://qubrics.com/docs/mcp
> ```

> [accordion] 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://qubrics.com/docs/mcp"
>     }
>   }
> }
> ```

> [accordion] VS Code
>
> Add this server to your user or workspace `mcp.json`.
>
> ```json theme={null}
> {
>   "servers": {
>     "sendmux-docs": {
>       "type": "http",
>       "url": "https://qubrics.com/docs/mcp"
>     }
>   }
> }
> ```

> [accordion] Codex
>
> Add this server to `~/.codex/config.toml` or a trusted project `.codex/config.toml`.
>
> ```toml theme={null}
> [mcp_servers.sendmux_docs]
> url = "https://qubrics.com/docs/mcp"
> ```

## 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 Qubrics in the authorisation flow, avoids distributing manual API keys to agents, and shows only the tools allowed by the grant.

> [!NOTE]
>
> PyPI package: `sendmux-mcp`
>
> PyPI version: `2.1.3`
>
> npm package: `sendmux-mcp`
>
> npm version: `1.0.0`
>
> Registry metadata version: `2.1.4`
>
> Hosted resource: `https://mcp.sendmux.ai/mcp`
>
> Hosted transport: Streamable HTTP
>
> Curated tool count: 54
>
> Certified protocol versions: `2025-11-25`, `2026-07-28`
>
> Runtime-accepted protocol versions: `2024-11-05`, `2025-03-26`, `2025-06-18`, `2025-11-25`, `2026-07-28`. Runtime acceptance provides compatibility; it does not certify each version.

| Setting | Value |
| - | - |
| Server URL | `https://mcp.qubrics.com/mcp` |
| Authorisation server | `https://app.qubrics.com` |
| Health check | `https://mcp.qubrics.com/health` |

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

[![Run in Postman](https://run.pstmn.io/button.svg)](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)

When you connect, Qubrics 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
> `qubrics_mailbox_list_granted_mailboxes` and pass the returned `mailbox_id` to tools
> that act on one mailbox.

## Connection modes

> [card] [Hosted OAuth](https://sendmux.ai/docs/ai-integrations/mcp/clients#hosted-oauth-clients)
>
> Use when your client can open a browser-based MCP OAuth flow.

> [card] [Local stdio](https://sendmux.ai/docs/ai-integrations/mcp/clients#local-stdio-clients)
>
> Use when your coding agent can launch a local command on your machine.

> [card] [Private HTTP](https://sendmux.ai/docs/ai-integrations/mcp/clients#private-http-clients)
>
> Use when a client needs a URL but you run the MCP package yourself.

## npm bridge

Requires Node.js 22 or later. Run the npm bridge:

```bash theme={null}
npx -y sendmux-mcp
```

The bridge connects stdio clients to the hosted server through browser OAuth. Tools follow your hosted grant.

```json theme={null}
{
  "mcpServers": {
    "sendmux": {
      "command": "npx",
      "args": ["-y", "sendmux-mcp"]
    }
  }
}
```

## Local package

> [!WARNING]
>
> Before upgrading an existing installation, keep its working package environment,
> dependency state, and MCP client and tool configuration. Version 2.0.0 removes
> local `file_path` and roots inputs from MCP attachment tools. Before switching
> existing agents, follow the [upgrade and rollback guidance](https://github.com/qubrics/qubrics-sdk/blob/main/packages/python/mcp/README.md#200-upgrade).

Install the local package from PyPI:

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

Run one surface:

```bash theme={null}
QUBRICS_API_KEY=smx_mbx_... sendmux-mcp-mailbox
QUBRICS_API_KEY=smx_root_... sendmux-mcp-management
QUBRICS_API_KEY=smx_mbx_... sendmux-mcp-sending
```

Run all product surfaces:

```bash theme={null}
QUBRICS_MCP_SURFACES=mailbox,management,sending \
QUBRICS_MAILBOX_API_KEY=smx_mbx_... \
QUBRICS_MANAGEMENT_API_KEY=smx_root_... \
QUBRICS_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}
QUBRICS_API_KEY=smx_mbx_... \
QUBRICS_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 `QUBRICS_MCP_HTTP_BEARER_TOKEN` unless you explicitly start it with `--allow-unauthenticated-http`.

## Configuration reference

> [accordion] Environment variables
>
> | Setting | Environment | Default |
> | - | - | - |
> | Tool surfaces | `QUBRICS_MCP_SURFACES` | Required for `sendmux-mcp` |
> | API key fallback | `QUBRICS_API_KEY` | None |
> | Mailbox API key | `QUBRICS_MAILBOX_API_KEY` | None |
> | Management API key | `QUBRICS_MANAGEMENT_API_KEY` | None |
> | Sending API key | `QUBRICS_SENDING_API_KEY` | None |
> | Management and Mailbox API base URL | `QUBRICS_APP_BASE_URL` | `https://app.sendmux.ai/api/v1` |
> | Sending API base URL | `QUBRICS_SENDING_BASE_URL` | `https://smtp.sendmux.ai/api/v1` |
> | Retry time budget, in seconds | `QUBRICS_MCP_RETRY_MAX_ELAPSED_SECONDS` | Unset |
> | Transport | `QUBRICS_MCP_TRANSPORT` | `stdio` |
> | HTTP host | `QUBRICS_MCP_HOST` | `127.0.0.1` |
> | HTTP port | `QUBRICS_MCP_PORT` | `8765` |
> | HTTP path | `QUBRICS_MCP_PATH` | `/mcp` |
> | HTTP bearer token | `QUBRICS_MCP_HTTP_BEARER_TOKEN` | Required for HTTP |
> | Allowed browser origins | `QUBRICS_MCP_ALLOWED_ORIGINS` | No browser origins |

> [accordion] Protected environment input
>
> ```bash theme={null}
> QUBRICS_MCP_SURFACES=mailbox,management,sending \
> QUBRICS_MAILBOX_API_KEY="$QUBRICS_MBX_KEY" \
> QUBRICS_MANAGEMENT_API_KEY="$QUBRICS_ROOT_KEY" \
> QUBRICS_SENDING_API_KEY="$QUBRICS_SENDING_KEY" \
> sendmux-mcp
> ```

## Compatibility names

Use the Qubrics names in new integrations. Existing integrations keep working.

For supported environment settings, the SDKs, CLI and MCP server read `QUBRICS_*` before the matching `SENDMUX_*` name. You can update a configuration while keeping older variables in place, including `SENDMUX_API_KEY`, `SENDMUX_ACCESS_TOKEN`, `SENDMUX_BASE_URL`, `SENDMUX_PROFILE`, `SENDMUX_APP_BASE_URL`, `SENDMUX_SENDING_BASE_URL`, `SENDMUX_MAILBOX_API_KEY`, `SENDMUX_MANAGEMENT_API_KEY` and `SENDMUX_SENDING_API_KEY`. Each `QUBRICS_MCP_*` setting in the configuration reference also accepts its matching `SENDMUX_MCP_*` name.

Each Qubrics header has a retained header with the same value. Requests accept either name wherever that header is valid:

| Qubrics header | Retained header |
| - | - |
| `X-Qubrics-Signature` | `X-Sendmux-Signature` |
| `X-Qubrics-Signature-V2` | `X-Sendmux-Signature-V2` |
| `X-Qubrics-Timestamp` | `X-Sendmux-Timestamp` |
| `X-Qubrics-Event-Id` | `X-Sendmux-Event-Id` |
| `X-Qubrics-Event-Type` | `X-Sendmux-Event-Type` |
| `X-Qubrics-Delivery-Attempt` | `X-Sendmux-Delivery-Attempt` |
| `X-Qubrics-Delivery-Group` | `X-Sendmux-Delivery-Group` |
| `X-Qubrics-Upload-Token` | `X-Sendmux-Upload-Token` |

MCP tools add `qubrics_` before their existing names, so `qubrics_mailbox_list_granted_mailboxes` and `mailbox_list_granted_mailboxes` call the same handler and return the same result, as do the corresponding `management_*` and `sending_*` tool names.

New mail webhook event data includes both `qubrics_message_id` and `sendmux_message_id` with the same value, which can be null. Calendar events use a separate payload without these fields. Older retained payloads and deliveries queued before this release can contain only `sendmux_message_id`. All compatibility names remain supported indefinitely.

## Tool discovery

> [accordion] 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

> [accordion] No tools appear
>
> Confirm the selected product surfaces and granted permissions. Hosted connections show only tools allowed by the grant.

> [accordion] 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] HTTP server returns 401
>
> Send `Authorization: Bearer <QUBRICS_MCP_HTTP_BEARER_TOKEN>` to private HTTP, or complete OAuth for hosted MCP.

> [accordion] HTTP server returns 403 origin\_forbidden
>
> Add the browser client's origin to `QUBRICS_MCP_ALLOWED_ORIGINS` for private HTTP.

> [accordion] Too many tools in one client
>
> Connect only the surfaces you need, or disable unused tools in the client.

## Next steps

> [card] [A2A](https://sendmux.ai/docs/ai-integrations/a2a.md)
>
> Use Qubrics through an A2A 1.0 agent endpoint with hosted OAuth.

> [card] [MCP clients](https://sendmux.ai/docs/ai-integrations/mcp/clients)
>
> Configure Qubrics MCP in Claude Code, Cursor, Codex, Gemini CLI, Qwen Code, Zed, and more.

> [card] [SDKs](https://sendmux.ai/docs/developer-tools/sdks)
>
> Use package-managed clients from application code.

> [card] [CLI](https://sendmux.ai/docs/developer-tools/cli.md)
>
> Install the CLI with Snap, Homebrew, or npm when you need terminal access.

> [card] [API keys](https://sendmux.ai/docs/account/api-keys.md)
>
> Create scoped credentials for local MCP setups.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.