ChatbotX MCP Platform Setup Guide for AI Assistants

This guide walks you through connecting your AI assistant client to the ChatbotX MCP Server. Select the platform you use and follow the steps below. For each platform you will need your Workspace Token and your API URL — either https://app.chatbotx.io/api for cloud instances or https://app.yourdomain.com/api for self-hosted instances.

Environment Variables

Regardless of which client you use, you will reference these two environment variables throughout the setup:

Variable	Value
`CHATBOTX_API_KEY`	Your Workspace Token (found in Settings → Developer → API Keys)
`CHATBOTX_API_URL`	`https://app.chatbotx.io/api` (or your self-hosted domain)
`CHATBOTX_ALLOW_SELF_SIGNED_CERT`	`true` — only required if your server uses a self-signed certificate

OpenClaw

Install Node.js v22 and OpenClaw

sudo apt update && sudo apt upgrade -y
sudo apt install -y curl git build-essential
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
nvm install 22
nvm use 22
nvm alias default 22
curl -fsSL https://openclaw.ai/install.sh | bash

Configure OpenClaw

openclaw configure

Follow the interactive prompts to set your LLM provider API key.

Install the ChatbotX skill

Install the official ChatbotX skill from ClawHub, then configure your environment variables:

openclaw skills install chatbotx

Set your credentials:

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

If your server uses a self-signed certificate, also add:

CHATBOTX_ALLOW_SELF_SIGNED_CERT=true

Start the gateway and verify

openclaw gateway start
openclaw mcp list
openclaw logs --follow

You should see chatbotx in the MCP server list and connection events in the log output.

Hermes

Install Hermes

sudo apt update && sudo apt upgrade -y
sudo apt install -y curl git build-essential
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
source ~/.bashrc

Run the setup wizard

hermes setup

Connect ChatbotX MCP Server

Add the ChatbotX MCP server using SSE transport:

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

For self-hosted instances, replace the URL with https://app.yourdomain.com/mcp/sse?token=YOUR_WORKSPACE_TOKEN.

Enable and verify via systemd

sudo systemctl daemon-reload
sudo systemctl enable --now hermes
hermes mcp list
journalctl -u hermes -f

Claude Code

Install Claude Code

npm install -g @anthropic-ai/claude-code

Add the ChatbotX MCP server

Choose either remote (SSE) or local (stdio) connection:Option A: Remote SSE Connection

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

Option B: Local stdio Connection

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

For self-hosted instances, replace https://app.chatbotx.io with https://app.yourdomain.com.

Verify the connection

claude mcp list
claude mcp get chatbotx

The output should include your chatbotx server entry with the correct URL and transport type.

The Claude Desktop claude_desktop_config.json entry looks like this:

{
  "servers": {
    "chatbotx": {
      "type": "sse",
      "url": "https://app.chatbotx.io/mcp/sse",
      "headers": {
        "x-workspace-token": "YOUR_WORKSPACE_TOKEN"
      }
    }
  }
}

VS Code (Copilot / MCP Extension)

Add the following to your VS Code MCP settings:

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

Gemini CLI

Add the following configuration, using httpUrl (or serverUrl if your version does not support httpUrl):

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

ChatGPT (Developer Mode)

ChatGPT’s Developer Mode does not support custom headers, so use the token-in-URL format:

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

Select No additional authentication when prompted, since the token is already embedded in the URL.

Testing Your Connection

After setup, verify that the MCP endpoint is reachable using curl:

# Cloud instances
curl -i -N --max-time 12 \
  -H "x-workspace-token: YOUR_WORKSPACE_TOKEN" \
  -H "Accept: text/event-stream" \
  "https://app.chatbotx.io/mcp/sse"

# Self-hosted instances
curl -i -N --max-time 12 \
  -H "x-workspace-token: YOUR_WORKSPACE_TOKEN" \
  -H "Accept: text/event-stream" \
  "https://app.yourdomain.com/mcp/sse"

A successful connection returns:

HTTP/1.1 200 OK
Content-Type: text/event-stream
event: endpoint
data: /mcp/messages?sessionId=...

SSE connections stay open. It is normal for the command to stop after the timeout — as long as you see 200 OK and event: endpoint, the connection is working correctly.

Additional Guide: Telegram Bot for OpenClaw and Hermes

Both OpenClaw and Hermes support interacting with your AI assistant via Telegram. To set this up, you need a Telegram Bot Token and your personal Chat ID.

Step 1: Create a Telegram Bot

Open BotFather

Open Telegram, search for the official @BotFather (verified with a blue checkmark), and click Start.

Create your bot

Send the /newbot command. Enter a display name (e.g., ChatbotX Assistant) and a unique username ending in bot (e.g., chatbotx_mcp_bot).

Copy the bot token

BotFather will return a Telegram Bot Token (e.g., 123456789:ABCdefGhIJKlmNoPQRs...). Save it securely.

Step 2: Find Your Chat ID

To prevent unauthorized access, restrict your bot to only your Telegram account:

Get your Chat ID

Search for @userinfobot on Telegram and click Start. Copy the Id number it returns.

Save your Chat ID

Enter this Chat ID in your OpenClaw or Hermes configuration wizard to restrict bot access to your account only.

Best Practices

Follow these guidelines to operate safely with an AI assistant connected via MCP. Authenticate first. Every MCP tool call requires a valid Workspace token. Confirm your configuration has the token set via header or URL parameters before issuing any commands. Resolve IDs before actions. Adding tags, starting flows, updating fields, or sending messages all require internal IDs. Instruct the assistant to verify target records and retrieve IDs first. Use human-in-the-loop for bulk actions. For broadcasts, bulk field updates, or mass messaging, require the assistant to list the target contacts and show the list before executing. Example prompt for safe bulk operations:

Find Contacts tagged VIP who have not purchased in 30 days.
Show me the list first.
Draft a WhatsApp message with a discount code.
Do not send anything until I approve.
After approval, send only to the approved list and show the result.

Common Issues

Issue	Common Cause	Fix
Not connected	Token is incorrect or header name is wrong	Check the token and verify the header is `x-workspace-token`
`401` or `403`	Token is expired, revoked, or lacks access	Create a new Workspace token and update all client configurations
AI assistant cannot find tools	Client was not restarted or config syntax is invalid	Check JSON/TOML syntax and restart your MCP client
ChatGPT cannot see tools	Developer Mode not enabled or URL token missing	Enable Developer Mode and use the `?token=...` URL format

Get Started

Channels

Automation

AI Agents

Inbox & Contacts

Remarketing

Tools & Growth

Integrations

Analytics

White Label

CLI & MCP

ChatbotX MCP Platform Setup Guide for AI Assistants

Environment Variables

OpenClaw

Hermes

Claude Code

VS Code (Copilot / MCP Extension)

Gemini CLI

ChatGPT (Developer Mode)

Testing Your Connection

Additional Guide: Telegram Bot for OpenClaw and Hermes

Step 1: Create a Telegram Bot

Step 2: Find Your Chat ID

Best Practices

Common Issues

​Environment Variables

​OpenClaw

​Hermes

​Claude Code

​VS Code (Copilot / MCP Extension)

​Gemini CLI

​ChatGPT (Developer Mode)

​Testing Your Connection

​Additional Guide: Telegram Bot for OpenClaw and Hermes

​Step 1: Create a Telegram Bot

​Step 2: Find Your Chat ID

​Best Practices

​Common Issues

Environment Variables

OpenClaw

Hermes

Claude Code

VS Code (Copilot / MCP Extension)

Gemini CLI

ChatGPT (Developer Mode)

Testing Your Connection

Additional Guide: Telegram Bot for OpenClaw and Hermes

Step 1: Create a Telegram Bot

Step 2: Find Your Chat ID

Best Practices

Common Issues