Set Up ChatbotX MCP by Platform

Connect your AI assistants, coding environments, and autonomous agent frameworks to the ChatbotX MCP Server. The server runs directly alongside your ChatbotX workspace and exposes the full API through the open Model Context Protocol.

Authentication

The ChatbotX MCP Server authenticates every tool request using a Workspace Token:

Request Header (Recommended for IDEs and CLI tools): Pass the token in the x-workspace-token HTTP header (or x-chatbo-token).
URL Query Parameter (For web connectors): Pass the token as ?token=YOUR_WORKSPACE_TOKEN or ?workspace_token=YOUR_WORKSPACE_TOKEN. Use this for clients like Perplexity Computer that cannot set custom request headers.
Environment Variable (For local stdio processes): Set CHATBOTX_API_KEY=YOUR_WORKSPACE_TOKEN in the environment.

Find or copy your token in the ChatbotX dashboard under Settings > Integrations > Workspace token.

Configuration files are static data files, not shell scripts. Wherever a sample shows YOUR_WORKSPACE_TOKEN, paste your actual token string if your client does not expand environment variables.

Connect your client

Select your platform below to view setup commands and configuration files. Clients that share the same configuration format are grouped into unified tabs.

OpenClaw and NanoClaw are autonomous agent runtimes in the Claw ecosystem. Both connect to ChatbotX using the official chatbotx skill and workspace credentials.

OpenClaw

OpenClaw runs as a background gateway and connects to messaging channels like Telegram:

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

Install ChatbotX skill

Install the official skill from ClawHub:

openclaw skills install chatbotx

Configure your environment variables in ~/.openclaw/.env:

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

For self-hosted instances, set CHATBOTX_API_URL to your custom backend origin (e.g. https://app.yourdomain.com/api). If using a self-signed certificate, add CHATBOTX_ALLOW_SELF_SIGNED_CERT=true.

Start gateway and verify

openclaw gateway start
openclaw mcp list
openclaw logs --follow

NanoClaw

NanoClaw provides lightweight, container-isolated personal agent execution in sandboxed Docker containers.Run the container directly with environment variables:

docker run -d \
  --name nanoclaw-agent \
  -e CHATBOTX_API_KEY=YOUR_WORKSPACE_TOKEN \
  -e CHATBOTX_API_URL=https://app.chatbotx.io/api \
  nanoclaw/agent:latest

Or configure within nanoclaw.json:

{
  "skills": ["chatbotx"],
  "env": {
    "CHATBOTX_API_KEY": "YOUR_WORKSPACE_TOKEN",
    "CHATBOTX_API_URL": "https://app.chatbotx.io/api"
  }
}

NousResearch Hermes Agent connects to ChatbotX via HTTP Server-Sent Events (SSE).

Install Hermes Agent

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 Hermes setup wizard

hermes setup

Add the ChatbotX SSE endpoint with your token:

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 systemd daemon

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

Anthropic Claude Code CLI supports both remote SSE and local stdio connections.

Install Claude Code CLI

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

Add ChatbotX MCP server

Option A: Remote SSE (Recommended)Connects directly to your running instance without local Node dependencies:

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

Option B: Local stdioSpawns the MCP server process locally on demand:

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 the URL with https://app.yourdomain.com/mcp/sse (SSE) or https://app.yourdomain.com/api (stdio).

Verify connection

Inspect your configured MCP servers:

claude mcp list
claude /mcp

OpenAI Codex CLI and Codex agents configure MCP servers in TOML format.

Configuration File

Add the server block to your user config ~/.codex/config.toml (or project-level .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"

If you are self-hosting ChatbotX, replace https://app.chatbotx.io/mcp/sse with https://app.yourdomain.com/mcp/sse.

Antigravity IDE and Paperclip multi-agent orchestration both connect using standard JSON mcpServers declarations with header authorization.

Antigravity

Add the server configuration in Antigravity settings (settings.json or .agent/mcp.json):

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

Paperclip

In paperclip.config.json or within an agent manifest:

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

For self-hosted instances, update the endpoint URL to https://app.yourdomain.com/mcp/sse.

Perplexity Computer connects to the ChatbotX MCP server via HTTP Server-Sent Events (SSE) using URL token authentication.

Account Settings (Web Dashboard)

Navigate to Connectors

Open Perplexity, click your profile icon, and go to Account Settings > Connectors.

Add MCP Connector

Click Add MCP Server and enter your endpoint:

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

Save and verify

Set Authentication type to None (the workspace token is authenticated directly by query parameter). Save the connector to enable ChatbotX tools in Perplexity reasoning sessions.

Perplexity CLI

claude mcp add chatbotx --transport sse "https://app.chatbotx.io/mcp/sse?token=YOUR_WORKSPACE_TOKEN"

Always wrap URLs containing ?token= in double quotes when executing in shell terminals to prevent characters like ? and & from being interpreted as shell operators.

Self-Hosted Reverse Proxy Configuration

When hosting ChatbotX behind Nginx or Caddy, ensure your reverse proxy supports long-lived Server-Sent Events (SSE) by disabling proxy buffering.

Nginx

location /mcp/ {
    proxy_pass http://chatbotx_backend;
    proxy_http_version 1.1;
    proxy_set_header Connection "";
    proxy_set_header Host $host;
    proxy_buffering off;
    proxy_cache off;
    proxy_read_timeout 86400s;
    chunked_transfer_encoding off;
}

Caddy

Caddy streams SSE natively. Ensure timeouts allow long-lived connections:

app.yourdomain.com {
    reverse_proxy localhost:3000 {
        transport http {
            keepalive 86400s
        }
    }
}

Additional Guide: Create and Secure a Telegram Bot

Both OpenClaw and Hermes allow you to interact with your AI assistant using Telegram. To set this up, you need a Telegram Bot Token and your personal Chat ID for security.

Step 1: Create a Telegram Bot

Open the Telegram app, search for the official @BotFather (verified with a blue checkmark), and click Start.
Send the /newbot command.
Enter a display name for your bot (e.g. ChatbotX Assistant).
Enter a unique username ending in bot (e.g. chatbotx_mcp_bot).
Copy the Telegram Bot Token provided (e.g. 123456789:ABCdefGhIJKlmNoPQRs...).

Step 2: Retrieve Your Chat ID for Security

To prevent unauthorized users from executing commands on your ChatbotX workspace via the Telegram bot, restrict bot access to your Telegram account using your Chat ID:

Search for @userinfobot on Telegram and click Start.
Copy the Id number returned in the message.
Save this Chat ID in your OpenClaw or Hermes configuration wizard to restrict access.

Getting Started

Usage & Reference

Authentication

Connect your client

OpenClaw

NanoClaw

Configuration File

Antigravity

Paperclip

Account Settings (Web Dashboard)

Perplexity CLI

Self-Hosted Reverse Proxy Configuration

Nginx

Caddy

Additional Guide: Create and Secure a Telegram Bot

Step 1: Create a Telegram Bot

Step 2: Retrieve Your Chat ID for Security

​Authentication

​Connect your client

​OpenClaw

​NanoClaw

​Configuration File

​Antigravity

​Paperclip

​Account Settings (Web Dashboard)

​Perplexity CLI

​Self-Hosted Reverse Proxy Configuration

​Nginx

​Caddy

​Additional Guide: Create and Secure a Telegram Bot

​Step 1: Create a Telegram Bot

​Step 2: Retrieve Your Chat ID for Security

Authentication

Connect your client

OpenClaw

NanoClaw

Configuration File

Antigravity

Paperclip

Account Settings (Web Dashboard)

Perplexity CLI

Self-Hosted Reverse Proxy Configuration

Nginx

Caddy

Additional Guide: Create and Secure a Telegram Bot

Step 1: Create a Telegram Bot

Step 2: Retrieve Your Chat ID for Security