ChatbotX MCP Server: AI-Powered Workspace Automation

The ChatbotX MCP Server connects AI assistants to your self-hosted ChatbotX Workspace using the Model Context Protocol (MCP). 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 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).

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.

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:

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):

{
  "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:

{
  "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

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.

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

Quick Example

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

Find the contact

The agent calls list_contacts and searches by phone or email to retrieve the target contact’s contactId.

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.

Trigger a flow

The agent calls send_contact_flow to launch a specific onboarding or remarketing flow for that contact.

FAQ

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.

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.

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.

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.

Get Started

Channels

Automation

AI Agents

Inbox & Contacts

Remarketing

Tools & Growth

Integrations

Analytics

White Label

CLI & MCP

ChatbotX MCP Server: AI-Powered Workspace Automation

When to Use ChatbotX MCP

How It Works

Available Tools

Authentication

Workspace Token

Connecting Your AI Assistant

Option 1: stdio Mode (Recommended for Local Use)

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

Self-Hosted SSE URL

Quick Example

FAQ

​When to Use ChatbotX MCP

​How It Works

​Available Tools

​Authentication

​Workspace Token

​Connecting Your AI Assistant

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

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

​Self-Hosted SSE URL

​Quick Example

​FAQ

When to Use ChatbotX MCP

How It Works

Available Tools

Authentication

Workspace Token

Connecting Your AI Assistant

Option 1: stdio Mode (Recommended for Local Use)

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

Self-Hosted SSE URL

Quick Example

FAQ