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

# Introduction

> Connect AI agents to ChatbotX using the Model Context Protocol (MCP).

Connect AI agents to ChatbotX using the Model Context Protocol (MCP).

ChatbotX MCP Server connects AI assistants to your self-hosted ChatbotX Workspace. Instead of manually typing commands, you can chat with an AI assistant to query contacts, update custom fields, send messages, or trigger automation flows.

```mermaid theme={null}
sequenceDiagram
  autonumber
  participant Agent as AI Agent (OpenClaw/Claude)
  participant MCP as ChatbotX MCP Server
  participant WS as ChatbotX Workspace

  Agent->>MCP: Connect with Workspace Token
  MCP-->>Agent: List available tools (e.g., list_contacts)
  Agent->>MCP: Call tool (e.g., send_contact_flow)
  MCP->>WS: Execute workspace action (API request)
  WS-->>MCP: Return action result
  MCP-->>Agent: Send tool response (JSON payload)
```

## When to use ChatbotX MCP

<Card title="When to use ChatbotX MCP?" icon="brain">
  * **Natural Language Operations**: Chatting 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).
</Card>

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

| 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.                                     |
| `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 requests. This token acts as a secret key to authenticate your AI assistant client. You can generate or find your token under **Settings → Developer → API Keys** (or **Settings → Integrations → Workspace token**).

## Connecting

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

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

Exposes the MCP server over standard input/output (stdio) when running the server locally via `node`:

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

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

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

Exposes the MCP server over HTTP Server-Sent Events (SSE).

* **Header-Based Connection**:
  ```json theme={null}
  {
    "url": "https://app.chatbotx.io/mcp/sse",
    "headers": {
      "x-workspace-token": "YOUR_WORKSPACE_TOKEN"
    }
  }
  ```
* **Token in URL** (when headers are not supported by the client):
  ```text theme={null}
  https://app.chatbotx.io/mcp/sse?token=YOUR_WORKSPACE_TOKEN
  ```

#### Custom SSE URL (Self-Hosted)

If you are self-hosting ChatbotX, point your MCP client to your own custom domain instead:

* **Header-Based Connection**:
  ```json theme={null}
  {
    "url": "https://app.yourdomain.com/mcp/sse",
    "headers": {
      "x-workspace-token": "YOUR_WORKSPACE_TOKEN"
    }
  }
  ```
* **Token in URL**:
  ```text theme={null}
  https://app.yourdomain.com/mcp/sse?token=YOUR_WORKSPACE_TOKEN
  ```

<Note>
  For detailed setup instructions on different platforms, see [Platform Setup](./platform-setup.mdx).
</Note>

## Quick Example

* Agent calls `list_contacts` - finds a contact by phone or email to get their `contactId`.
* Agent calls `add_contact_tags` with the `contactId` and `tagId` - tags the contact (e.g., VIP client).
* Agent calls `send_contact_flow` - triggers a specific onboarding flow for the contact.

## FAQ

### Do I need an OpenAI key to use ChatbotX MCP?

No. The MCP server runs on your self-hosted ChatbotX instance. However, your AI assistant client (such as Claude Code, OpenClaw, or VS Code) will require an API key from an LLM provider (Anthropic, OpenAI, Google Gemini, etc.) to understand and process your chat prompts.

### 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 your MCP client configurations.

### Self-hosted: how do I expose the MCP endpoint?

The MCP server starts as part of the ChatbotX backend and is reachable at `/mcp/sse` (Workspace token auth in headers) and `/mcp/sse?token=YOUR_WORKSPACE_TOKEN` (token in URL query parameters). Your reverse proxy must forward these paths to the backend and support Server-Sent Events (SSE) streaming (e.g., disabling proxy buffering with `proxy_buffering off;`).

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