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

# ChatbotX MCP Server: AI-Powered Workspace Automation

> Connect AI assistants to your ChatbotX Workspace via the Model Context Protocol. Query contacts, send messages, and trigger flows using natural language.

The **ChatbotX MCP Server** connects AI assistants to your self-hosted ChatbotX Workspace using the [Model Context Protocol (MCP)](https://modelcontextprotocol.io). Instead of manually typing commands, you can chat with an AI assistant to query contacts, update custom fields, send messages, or trigger automation flows — all through natural language. The MCP server runs as part of your ChatbotX backend and requires no additional infrastructure to operate.

## When to Use ChatbotX MCP

| Use Case                        | Why MCP Works Best                                                                                                               |
| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| **Natural Language Operations** | Chat naturally to manage contacts (e.g., *"Send a birthday discount flow to this contact"*)                                      |
| **Complex Reasoning**           | AI agent reads conversation context, makes business decisions, and automatically takes action (e.g., auto-tagging urgent issues) |

For scripting, cronjobs, and zero-token-cost automation, use the [ChatbotX CLI](/cli/introduction) instead.

## How It Works

The ChatbotX MCP server is built into your self-hosted instance and runs alongside the workspace. It exposes a **Server-Sent Events (SSE) endpoint** that acts as a bridge. When you connect an AI assistant (such as OpenClaw, Hermes, or Claude Code), the assistant queries the endpoint to discover available tools and execute actions on your behalf.

## Available Tools

All 12 tools are generated dynamically from your system's OpenAPI spec. When new APIs are added and the MCP Server is restarted, new tools appear automatically.

| Tool                         | Description                                                    |
| ---------------------------- | -------------------------------------------------------------- |
| `get_workspace`              | Retrieve details about the current workspace                   |
| `list_contacts`              | List or search contacts in the workspace (optionally filtered) |
| `create_contact`             | Add a new contact to the workspace                             |
| `upsert_contact`             | Create or update a contact by identifier                       |
| `add_contact_tags`           | Add tags to a contact                                          |
| `remove_contact_tags`        | Remove tags from a contact                                     |
| `list_contact_custom_fields` | List custom fields for a specific contact                      |
| `set_contact_custom_field`   | Update a contact's custom field value                          |
| `send_message`               | Send a direct chat message to a contact                        |
| `send_contact_flow`          | Trigger an automation flow for a contact                       |
| `list_flows`                 | Retrieve available automation flows                            |
| `list_channels`              | List connected channels (Telegram, WhatsApp, etc.)             |

## Authentication

### Workspace Token

ChatbotX MCP uses a **Workspace Token** to authorize all requests. This token acts as a secret key for your AI assistant client. Generate or find your token under **Settings → Developer → API Keys** (or **Settings → Integrations → Workspace token**).

<Warning>
  Keep your Workspace Token secret. Anyone who holds it can perform actions on your ChatbotX Workspace. Never share it in public repositories or chat messages.
</Warning>

## Connecting Your AI Assistant

You can connect your AI assistant to the ChatbotX MCP server using either **stdio** (recommended for local configurations) or **SSE** (for remote or shared configurations).

### Option 1: stdio Mode (Recommended for Local Use)

The stdio transport runs the MCP server over standard input/output when you launch the server locally via Node.js. This is the recommended approach for development and personal setups:

```bash theme={null}
claude mcp add chatbotx \
  -e CHATBOTX_API_KEY=YOUR_WORKSPACE_TOKEN \
  -e CHATBOTX_API_URL=https://app.chatbotx.io/api \
  -e CHATBOTX_MCP_TRANSPORT=stdio \
  -s user \
  -- node /path/to/dist/index.mjs
```

If you are running a self-hosted instance, replace `CHATBOTX_API_URL` with `https://app.yourdomain.com/api`.

### Option 2: SSE Mode (For Shared or Remote Access)

The SSE transport exposes the MCP server over HTTP Server-Sent Events, making it accessible from any client that supports SSE.

**Header-based authentication** (recommended when your client supports custom headers):

```json theme={null}
{
  "url": "https://app.chatbotx.io/mcp/sse",
  "headers": {
    "x-workspace-token": "YOUR_WORKSPACE_TOKEN"
  }
}
```

**Token-in-URL** (use when your client does not support custom headers):

```
https://app.chatbotx.io/mcp/sse?token=YOUR_WORKSPACE_TOKEN
```

#### Self-Hosted SSE URL

If you are self-hosting ChatbotX, replace the domain with your custom domain:

```json theme={null}
{
  "url": "https://app.yourdomain.com/mcp/sse",
  "headers": {
    "x-workspace-token": "YOUR_WORKSPACE_TOKEN"
  }
}
```

Or with token in URL:

```
https://app.yourdomain.com/mcp/sse?token=YOUR_WORKSPACE_TOKEN
```

<Info>
  Your reverse proxy must forward the `/mcp/sse` path to the backend and support Server-Sent Events (SSE) streaming. In Nginx, add `proxy_buffering off;` to your location block.
</Info>

For step-by-step setup instructions for specific platforms (OpenClaw, Hermes, Claude Code, VS Code, and others), see [Platform Setup](/mcp/platform-setup).

## Quick Example

Here is a three-step agentic flow that demonstrates what an AI assistant connected via MCP can do:

<Steps>
  <Step title="Find the contact">
    The agent calls `list_contacts` and searches by phone or email to retrieve the target contact's `contactId`.
  </Step>

  <Step title="Tag the contact">
    The agent calls `add_contact_tags` with the `contactId` and the relevant `tagId` — for example, tagging a contact as a VIP client.
  </Step>

  <Step title="Trigger a flow">
    The agent calls `send_contact_flow` to launch a specific onboarding or remarketing flow for that contact.
  </Step>
</Steps>

## FAQ

<AccordionGroup>
  <Accordion title="Do I need an OpenAI key to use ChatbotX MCP?">
    No. The MCP server runs on your self-hosted ChatbotX instance and does not require any OpenAI key. However, your AI assistant client (such as Claude Code, OpenClaw, or VS Code Copilot) will require an API key from an LLM provider (Anthropic, OpenAI, Google Gemini, etc.) to understand and process your chat prompts.
  </Accordion>

  <Accordion title="What happens when my Workspace token expires or is rotated?">
    Your AI assistant will lose access to the ChatbotX workspace and return `401 Unauthorized` or `403 Forbidden` errors. You must generate a new Workspace token and update it in all of your MCP client configurations.
  </Accordion>

  <Accordion title="Self-hosted: how do I expose the MCP endpoint?">
    The MCP server starts automatically as part of the ChatbotX backend. It is reachable at `/mcp/sse` (with the Workspace token in the `x-workspace-token` header) and at `/mcp/sse?token=YOUR_WORKSPACE_TOKEN` (with the token in the URL). Your reverse proxy must forward these paths to the backend and support SSE streaming — disable proxy buffering with `proxy_buffering off;` in Nginx.
  </Accordion>

  <Accordion title="Can MCP read and reply to messages?">
    Yes. The AI assistant can retrieve chat history using `list_conversations` or `list_contact_messages`, and send replies to WhatsApp, Telegram, or other active channels using `send_message`.
  </Accordion>
</AccordionGroup>