Introduction

Connect Claude, ChatGPT, Codex, Cursor, OpenClaw, or any MCP client to the ChatbotX MCP Server and let AI assistants query contacts, send messages, trigger automation flows, run broadcasts, and manage conversations. The ChatbotX MCP Server is built directly into your ChatbotX instance and implements the open Model Context Protocol. Tools are dynamically generated from the platform OpenAPI specification, providing comprehensive tool coverage for both interactive pair programming and fully autonomous agent workflows.

When to use ChatbotX MCP

Natural Language Operations

Manage your CRM and inbox through plain chat. Tell your AI assistant to find leads, update custom attributes, enroll contacts in sequences, or assign tickets.

Autonomous Business Reasoning

Let autonomous agents read conversation context, classify customer intent, trigger targeted flows, and escalate complex issues without human intervention.

Zero-Config Tool Discovery

With ~350 operations auto-generated from the OpenAPI spec, agents dynamically discover and invoke the right tool on demand without manual API integration.

Developer Automation

Automate testing, build flow specs with schema validation, inspect system error logs, and manage webhooks straight from your code editor.

First Call

Connect the server to your client and test your first command. In Claude Code CLI, run:

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

Verify your active MCP connection:

claude /mcp

Then ask your assistant to inspect the workspace:

“Check our workspace capabilities and show me active communication channels.”

The assistant calls capabilities_get, returning workspace details, connected channels, available WhatsApp templates, tags, and automation flows:

Found ChatbotX Workspace: "Acme Store" (ID: ws_98a7b6c5)

Connected Channels:
- WhatsApp Business: +84 90 123 4567 (Status: Connected)
- Facebook Messenger: Acme Brand Page (Status: Connected)
- Telegram Bot: @AcmeHelpBot (Status: Connected)

Active Automation:
- 14 published flows, 5 drip sequences, 28 contact tags

Autonomous Agents

Autonomous agents operating without an interactive browser session authenticate using an API key or Workspace Token via headers or query parameters. Because the ChatbotX MCP server supports Streamable HTTP and SSE, you can test or trigger tool executions directly using standard HTTP requests:

curl https://app.chatbotx.io/mcp/sse \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "x-workspace-token: YOUR_WORKSPACE_TOKEN" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "contacts_list",
      "arguments": {
        "keyword": "Minh Nguyen"
      }
    },
    "id": 1
  }'

Response (200 OK) returns the matching contact records:

{
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Found 1 contact: Minh Nguyen (ID: 10429, Phone: +84901234567, Channel: whatsapp)"
      }
    ]
  },
  "id": 1
}

Authentication

Workspace Token

ChatbotX MCP uses a Workspace Token to authorize every operation. Find or copy your token in the ChatbotX web dashboard under Settings > Integrations > Workspace token.

Token Resolution Priority

The MCP server checks credentials in the following order:

Priority	Source	Transport	Description
1	URL Query Parameter	SSE / HTTP	`?workspace_token=...` or `?token=...` (required for ChatGPT connector).
2	Request Header	SSE / HTTP	`x-workspace-token: ...` or `x-chatbo-token: ...` (standard header for Claude Code and Cursor).
3	Environment Variable	stdio / SSE	`CHATBOTX_API_KEY` (standard for local stdio processes).

How Tools Reach Context

Your client never loads all ~380 tools at once, avoiding context window bloat and excessive token consumption:

43 Default Tools: Essential tools covering contacts, conversations, flows, broadcasts, sequences, AI agents, and analytics remain always visible in tools/list.
Meta-Tools (search_tools and call_tool): Two fixed meta-tools allow the assistant to search the full OpenAPI catalog for less-common operations (coupons, webhooks, tags, custom fields, workspace members) and call them with zero context overhead until needed.
Discovery Tools (capabilities_get, token_get, schemas_flow_spec): Entry-point tools an agent should call first to discover workspace resources and inspect authorization scopes.

For the complete reference of all default tools, discovery endpoints, and extended meta-tools, see Tools.

Connecting

You can connect your AI assistant to the ChatbotX MCP server using either stdio (recommended for local use) or SSE (for remote and shared instances). Select your platform below for a quick connection snippet:

Install the ChatbotX skill from ClawHub or configure environment variables for your container:

openclaw skills install chatbotx

CHATBOTX_API_KEY=YOUR_WORKSPACE_TOKEN
CHATBOTX_API_URL=https://app.chatbotx.io/api

Connect Hermes Agent via SSE with your token in the URL:

hermes mcp add chatbotx --url "https://app.chatbotx.io/mcp/sse?token=YOUR_WORKSPACE_TOKEN"
hermes config set mcp_servers.chatbotx.transport sse

Connect Claude Code via remote SSE or local stdio:

claude mcp add chatbotx -t sse -H "x-workspace-token: YOUR_WORKSPACE_TOKEN" -s user https://app.chatbotx.io/mcp/sse

Add the server to your Codex config.toml:

[mcp_servers.chatbotx]
url = "https://app.chatbotx.io/mcp/sse"
enabled = true

[mcp_servers.chatbotx.http_headers]
"x-workspace-token" = "YOUR_WORKSPACE_TOKEN"

Both Antigravity IDE and Paperclip use standard JSON mcpServers configuration with header authorization:

{
  "mcpServers": {
    "chatbotx": {
      "serverUrl": "https://app.chatbotx.io/mcp/sse",
      "headers": {
        "x-workspace-token": "YOUR_WORKSPACE_TOKEN"
      }
    }
  }
}

Connect using the SSE URL in Perplexity Account Settings > Connectors:

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

For detailed step-by-step setup guides, installation prerequisites, and background daemon configurations for all 8 platforms, see Platform Setup.

Quick Workflow Example

A typical customer onboarding workflow executed by an AI assistant:

Find contact: Agent calls contacts_get with phone or email identifier (phone:+84901234567) to retrieve the contact ID.
Tag contact: Agent calls contacts_add_tags_by_name to assign the tag VIP Member.
Trigger flow: Agent calls contacts_send_flow to start the welcome automation flow for that contact.
Notify team: Agent calls conversations_assign to assign the conversation thread to the customer care team.

FAQ

Do I need an OpenAI or Anthropic API key to use ChatbotX MCP?

No key is needed for the MCP server itself. The MCP server runs inside your self-hosted ChatbotX instance. However, your client application (Claude Code, Cursor, OpenClaw, VS Code) requires an API key from an LLM provider (Anthropic, OpenAI, Google) to understand your prompts and decide which tools to call.

What happens when my Workspace Token expires or is rotated?

The AI assistant loses access and receives 401 Unauthorized responses. Generate or copy a new token under Settings > Integrations > Workspace token and update your client configuration.

How do I configure reverse proxies for self-hosted SSE?

The MCP endpoint at /mcp/sse requires long-lived streaming connections. In Nginx or Caddy, ensure proxy buffering is turned off:

location /mcp/ {
    proxy_pass http://chatbotx_backend;
    proxy_http_version 1.1;
    proxy_set_header Connection "";
    proxy_buffering off;
    proxy_cache off;
    chunked_transfer_encoding off;
}

Can MCP read and reply to customer messages in real time?

Yes. AI assistants can retrieve conversation history using messages_list or contacts_list_messages, and send immediate replies through connected channels using contacts_send_message.

Getting Started

Usage & Reference

When to use ChatbotX MCP

Natural Language Operations

Autonomous Business Reasoning

Zero-Config Tool Discovery

Developer Automation

First Call

Autonomous Agents

Authentication

Workspace Token

Token Resolution Priority

How Tools Reach Context

Connecting

Quick Workflow Example

FAQ

Do I need an OpenAI or Anthropic API key to use ChatbotX MCP?

What happens when my Workspace Token expires or is rotated?

How do I configure reverse proxies for self-hosted SSE?

Can MCP read and reply to customer messages in real time?

​When to use ChatbotX MCP

Natural Language Operations

Autonomous Business Reasoning

Zero-Config Tool Discovery

Developer Automation

​First Call

​Autonomous Agents

​Authentication

​Workspace Token

​Token Resolution Priority

​How Tools Reach Context

​Connecting

​Quick Workflow Example

​FAQ

​Do I need an OpenAI or Anthropic API key to use ChatbotX MCP?

​What happens when my Workspace Token expires or is rotated?

​How do I configure reverse proxies for self-hosted SSE?

​Can MCP read and reply to customer messages in real time?

When to use ChatbotX MCP

First Call

Autonomous Agents

Authentication

Workspace Token

Token Resolution Priority

How Tools Reach Context

Connecting

Quick Workflow Example

FAQ

Do I need an OpenAI or Anthropic API key to use ChatbotX MCP?

What happens when my Workspace Token expires or is rotated?

How do I configure reverse proxies for self-hosted SSE?

Can MCP read and reply to customer messages in real time?