Skip to main content
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.
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.
Add this server to .cursor/mcp.json for one project or ~/.cursor/mcp.json for all projects.
Add this server to your user or workspace mcp.json.
Add this server to ~/.codex/config.toml or a trusted project .codex/config.toml.

MCP

MCP exposes the product surfaces you grant. 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.
PyPI package: sendmux-mcpPyPI version: 2.1.3npm package: sendmux-mcpnpm version: 1.0.0Registry metadata version: 2.1.4Hosted resource: https://mcp.sendmux.ai/mcpHosted transport: Streamable HTTPCurated tool count: 54Certified protocol versions: 2025-11-25, 2026-07-28Runtime-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.
Use the Postman collection when you want to test MCP requests from Postman: Run in Postman 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.
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

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.

npm bridge

Requires Node.js 22 or later. Run the npm bridge:
The bridge connects stdio clients to the hosted server through browser OAuth. Tools follow your hosted grant.

Local package

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.
Install the local package from PyPI:
Run one surface:
Run all product surfaces:
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.
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

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

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

Confirm the selected product surfaces and granted permissions. Hosted connections show only tools allowed by the grant.
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_.
Send Authorization: Bearer <QUBRICS_MCP_HTTP_BEARER_TOKEN> to private HTTP, or complete OAuth for hosted MCP.
Add the browser client’s origin to QUBRICS_MCP_ALLOWED_ORIGINS for private HTTP.
Connect only the surfaces you need, or disable unused tools in the client.

Next steps

A2A

Use Qubrics through an A2A 1.0 agent endpoint with hosted OAuth.

MCP clients

Configure Qubrics 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.