> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xpressbot.org/llms.txt
> Use this file to discover all available pages before exploring further.
# MCP
> Connect Claude, Cursor, VS Code, or any MCP client to your workspace over Streamable HTTP.
## What is this?
**MCP** (Model Context Protocol) is a standard that lets AI assistants call an application's own tools directly, instead of you copying data back and forth. This platform runs an MCP server so you can connect an assistant such as Claude, Cursor, or VS Code to your workspace: they can read your inbox and conversation history, contacts, campaigns, automations and their runs, AI agents, orders, events, activity and the product docs, and make changes such as updating a contact or sending a template after you approve them.
There is nothing to install on the server — point your client at this URL with your API key.
The Developer Portal's **Reference** tab has three sub-tabs, in this order: **Workspace API**, **MCP**, **Platform API**. This page documents the **MCP** tab. Connecting a client needs an API key, which needs the **API Access** permission (`settings:api`) — see [Authentication](/api-reference/authentication).
\[SCREENSHOT: mcp-reference-tab — The Developer Portal's Reference tab with Workspace API, MCP, and Platform API sub-tabs, MCP selected]
### Server URL
```text theme={null}
https://YOUR_DOMAIN/api/mcp
```
| | |
| --------------- | ---------------------------------------------------------------------------------------------------------------------- |
| **Transport** | Streamable HTTP |
| **Server name** | `workspace` (the platform is white-labelled, so no brand name is sent to MCP clients) |
| **Auth** | API key, as an `Authorization: Bearer` header |
| **Scope** | One channel per connection, via the `X-Channel-Id` header (or `?channelId=` for clients that can't set custom headers) |
## What can I do here?
* Connect any MCP client that supports remote HTTP servers with custom headers
* Give the assistant read access to your inbox, conversations, contacts, labels, custom fields, pipelines, automations and their runs, campaigns, templates, AI agents, orders, catalog, events, connected networks, and the product docs
* Let it make approved changes: add a note, update a contact, set a custom field, add or remove a label, move a pipeline stage, send a template, close a conversation, hand off to a human, or trigger an automation
* See the exact same tool list this page documents live in-app, under **Developer → Reference → MCP** — see the [full tool catalog](/api-reference/mcp/tools)
## How to use it
**API key** — Generate a key in **API Keys** (in the Developer Portal). The assistant acts as you, with your permissions. Needs the **API Access** permission.
**Channel** — Each connection works inside one channel. Find your channel IDs with **List channels**, or pick one in the Developer Portal's MCP tab, which fills it into the setup snippets for you.
Pick your client and copy the snippet, replacing `` and `` with your own values.
Run this in your terminal, then run `/mcp` inside Claude Code to check the connection.
```bash theme={null}
claude mcp add --transport http workspace https://YOUR_DOMAIN/api/mcp \
--header "Authorization: Bearer " \
--header "X-Channel-Id: "
```
Settings → Developer → Edit Config, add this to `claude_desktop_config.json` and restart Claude. Needs Node.js installed.
```json theme={null}
{
"mcpServers": {
"workspace": {
"command": "npx",
"args": [
"mcp-remote",
"https://YOUR_DOMAIN/api/mcp",
"--header",
"Authorization:${AUTH}",
"--header",
"X-Channel-Id:${CHANNEL}"
],
"env": {
"AUTH": "Bearer ",
"CHANNEL": ""
}
}
}
}
```
Add this to `~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project) and enable the server in Cursor settings.
```json theme={null}
{
"mcpServers": {
"workspace": {
"url": "https://YOUR_DOMAIN/api/mcp",
"headers": {
"Authorization": "Bearer ",
"X-Channel-Id": ""
}
}
}
}
```
Add this to `.vscode/mcp.json` in your project, then start the server from the MCP view.
```json theme={null}
{
"servers": {
"workspace": {
"type": "http",
"url": "https://YOUR_DOMAIN/api/mcp",
"headers": {
"Authorization": "Bearer ",
"X-Channel-Id": ""
}
}
}
}
```
Any MCP client that supports remote HTTP servers with custom headers can connect with these values.
```text theme={null}
URL: https://YOUR_DOMAIN/api/mcp
Transport: Streamable HTTP
Header: Authorization: Bearer
Header: X-Channel-Id:
```
Replace `` with your key. Keep the key out of shared files and repositories.
Claude on the web (claude.ai connectors) is not supported yet: it only signs in with OAuth, and this server uses API keys. Use Claude Code or Claude Desktop.
Once connected, just ask in plain language. For example:
* "Find the contact named John and show his labels."
* "Which events next week still have seats?"
* "Tag everyone who asked about pricing today with the Lead label."
## Available tools
What the assistant can use. Your key only sees the tools your permissions allow in the selected channel. See the [full tool catalog](/api-reference/mcp/tools) for every tool, grouped by area, with its description, mode, and required permission.
## How it stays safe
* Your client asks you to approve every change before it runs.
* Nothing can be deleted or cancelled over MCP. Those actions stay in the dashboard.
* The assistant has exactly your permissions, checked again on every call.
* Every call stays inside the channel you connected. Other channels are never visible.
* The same rate limits as the Workspace API apply, with stricter limits for sending messages and starting automations.
## Troubleshooting / Technical Notes
| Code | What it means |
| ----- | ------------------------------------------------------------------- |
| `400` | Missing channel. Send the `X-Channel-Id` header (or `?channelId=`). |
| `401` | Missing or invalid API key. Check the `Authorization` header. |
| `403` | The key's owner does not have the API Access permission. |
| `404` | The channel does not exist or you cannot access it. |
| `429` | Too many requests. Wait a minute and try again. |
* **`400` in detail.** The response is `{"error": "channel_required", "message": "Send the channel to work in as the X-Channel-Id header (or ?channelId=). List yours with /api/workspace/v1/channels/list."}`. Add the header or query parameter shown in the connection snippets above.
* **`404` instead of `403` for a channel you can't access.** This is deliberate: the server always returns 404 for a channel id it can't resolve for your key, whether it doesn't exist or you simply don't have access to it, so channel ids can never be probed or leaked.
* **A tool doesn't show up, or a call fails with a permission error.** The MCP server only ever offers tools your API key's owner has permission to use, re-checked on every call — grant the underlying permission (see each tool's "Permission needed" in the [tool catalog](/api-reference/mcp/tools)), not the API Access permission again.
* **A write never seems to happen.** Every write tool needs your MCP client's own approval step (Claude Code, Claude Desktop, Cursor, and VS Code all prompt you before running a tool call) — check your client isn't waiting on an approval dialog.
* **Nothing about deleting or cancelling.** By design: destructive actions (like cancelling a registration) are never exposed over MCP and stay dashboard-only.
## Related docs
* [MCP tool catalog](/api-reference/mcp/tools)
* [Introduction](/api-reference/introduction)
* [Authentication](/api-reference/authentication)
* [Rate limits](/api-reference/rate-limits)
* [Errors](/api-reference/errors)
* [Developer Portal](/workspace/developer-portal)
* [Team](/workspace/team)