Skip to main content
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.

​
When to use ChatbotX MCP

When to use ChatbotX MCP?

  • 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).

​
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

ToolDescription
get_workspaceRetrieve details about the current workspace.
list_contactsList or search contacts in the workspace (optionally filtered).
create_contactAdd a new contact to the workspace.
upsert_contactCreate or update a contact.
add_contact_tagsAdd tags to a contact.
remove_contact_tagsRemove tags from a contact.
list_contact_custom_fieldsList custom fields for a specific contact.
set_contact_custom_fieldUpdate a contact’s custom field value.
send_messageSend a direct chat message to a contact.
send_contact_flowTrigger an automation flow for a contact.
list_flowsRetrieve available automation flows.
list_channelsList 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). Exposes the MCP server over standard input/output (stdio) when running the server locally via node: 
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 the CHATBOTX_API_URL value with https://app.yourdomain.com/api.

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

Exposes the MCP server over HTTP Server-Sent Events (SSE).
  • Header-Based Connection: 
    {
  "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): 
    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: 
    {
  "url": "https://app.yourdomain.com/mcp/sse",
  "headers": {
    "x-workspace-token": "YOUR_WORKSPACE_TOKEN"
  }
}
  • Token in URL: 
    https://app.yourdomain.com/mcp/sse?token=YOUR_WORKSPACE_TOKEN
For detailed setup instructions on different platforms, see Platform Setup.

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