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

# Workspace MCP

> Connect Claude, Cursor, VS Code, or any MCP client to one channel of 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 after you approve them — from updating a contact or sending a template to creating campaigns, applying one change to many contacts at once, and building AI agents and automations from a description.

There is nothing to install on the server — point your client at this URL with your API key.

> [!NOTE]
>
> The Developer Portal has a dedicated **MCP** tab (separate from API Reference). Inside it you see two columns: **Workspace MCP** (this page) and **Platform MCP** (for platform owners and superadmins only). Connecting a client needs an API key with the **API Access** permission (`settings:api`) — see [Authentication](https://docs.xpressbot.org/api-reference/authentication.md).
>
> MCP is a plan feature. The MCP tab only appears if MCP is enabled on your installation; if your plan doesn't include it, the tab shows an **Upgrade** badge and connections are refused until you upgrade.

### Server URL

```text theme={null}
https://YOUR_DOMAIN/api/workspace/v1/mcp
```

| | |
| - | - |
| **Transport** | Streamable HTTP (stateless — `GET` and `DELETE` answer `405`) |
| **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
* Have it create labels, custom fields, and pipelines (and add pipeline stages), and apply one change to many contacts or conversations at once with a background job you can check
* Have it write a WhatsApp template draft, create a campaign from an approved template, or send a free-form utility or authentication message with Direct Send
* Have it build a WhatsApp Flow (an in-chat form) from a description, saved as a draft you review and publish in **Flows**
* Have it build an AI agent from a description — instructions, knowledge, skills, capabilities, and human handoff — check that it is ready, and publish it
* Have it build an automation from a description, saved as an inactive draft, then replace the draft's flow, activate it, or pause it
* See the exact same tool list this page documents live in-app, under **Developer → Reference → MCP** — see the [tool catalog](https://docs.xpressbot.org/api-reference/mcp/workspace/tools/overview.md)

## How to use it

**1. Get your connection details**

**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.

**2. Connect your client**

Pick your client and copy the snippet, replacing `<API_KEY>` and `<CHANNEL_ID>` with your own values.

**Claude Code**

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/workspace/v1/mcp \
  --header "Authorization: Bearer <API_KEY>" \
  --header "X-Channel-Id: <CHANNEL_ID>"
```

**Claude Desktop**

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/workspace/v1/mcp",
        "--header",
        "Authorization:${AUTH}",
        "--header",
        "X-Channel-Id:${CHANNEL}"
      ],
      "env": {
        "AUTH": "Bearer <API_KEY>",
        "CHANNEL": "<CHANNEL_ID>"
      }
    }
  }
}
```

**Cursor**

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/workspace/v1/mcp",
      "headers": {
        "Authorization": "Bearer <API_KEY>",
        "X-Channel-Id": "<CHANNEL_ID>"
      }
    }
  }
}
```

**VS Code**

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/workspace/v1/mcp",
      "headers": {
        "Authorization": "Bearer <API_KEY>",
        "X-Channel-Id": "<CHANNEL_ID>"
      }
    }
  }
}
```

**Other**

Any MCP client that supports remote HTTP servers with custom headers can connect with these values.

```text theme={null}
URL:        https://YOUR_DOMAIN/api/workspace/v1/mcp
Transport:  Streamable HTTP
Header:     Authorization: Bearer <API_KEY>
Header:     X-Channel-Id: <CHANNEL_ID>
```

Replace `<API_KEY>` with your key. Keep the key out of shared files and repositories.

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

**3. Ask your assistant**

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."
* "Build an AI agent for order support from this description, then check that it is ready to publish."
* "Build a welcome automation for new conversations that asks for the customer's name and tags them as a lead, then turn it on."

## Available tools

What the assistant can use. Your key only sees the tools your permissions allow in the selected channel. See the [tool catalog](https://docs.xpressbot.org/api-reference/mcp/workspace/tools/overview.md) 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](https://docs.xpressbot.org/api-reference/mcp/rate-limits.md) as the Workspace API apply, with stricter limits for sending messages and starting automations. Creating a campaign counts as sending messages.
* Tools that reach customers — sending a template or Direct Send message, creating a campaign, activating an automation, publishing an AI agent — are marked **Reaches customers** in the Developer Portal. New AI agents and automations are always created inactive, so nothing goes live until you explicitly publish or activate it.

## Troubleshooting / Technical Notes

* **`400 channel_required`.** Send the channel as the `X-Channel-Id` header (or `?channelId=`). List yours with **List channels**.
* **`401` or `403`.** The key is missing or invalid, the key's owner lacks the API Access permission, or MCP isn't included in the plan. See [Authentication](https://docs.xpressbot.org/api-reference/mcp/authentication.md).
* **`404` for a channel I own.** The server answers `404` for any channel it can't resolve for your key, so channel ids can't be probed.
* **A tool doesn't show up, or a write never happens.** Tools depend on permissions, and every write needs your client's approval. See [errors](https://docs.xpressbot.org/api-reference/mcp/errors.md) and the [tool catalog](https://docs.xpressbot.org/api-reference/mcp/workspace/tools/overview.md).
* **I changed to the new URL.** The original `/api/mcp` address keeps working for clients already set up with it; new setups should use `/api/workspace/v1/mcp`.

## Related docs

* [MCP introduction](https://docs.xpressbot.org/api-reference/mcp/introduction.md)
* [Authentication](https://docs.xpressbot.org/api-reference/mcp/authentication.md)
* [Rate limits](https://docs.xpressbot.org/api-reference/mcp/rate-limits.md)
* [Errors](https://docs.xpressbot.org/api-reference/mcp/errors.md)
* [Workspace MCP tool catalog](https://docs.xpressbot.org/api-reference/mcp/workspace/tools/overview.md)
* [Platform MCP](https://docs.xpressbot.org/api-reference/mcp/platform/overview.md)
* [Developer Portal](https://docs.xpressbot.org/workspace/developer-portal.md)
* [Team](https://docs.xpressbot.org/workspace/team.md)


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