> ## Documentation Index
> Fetch the complete documentation index at: https://docs.theomnibot.io/llms.txt
> Use this file to discover all available pages before exploring further.

# ChatbotX MCP Platform Setup Guide for AI Assistants

> Step-by-step instructions for connecting ChatbotX MCP to OpenClaw, Hermes, Claude Code, VS Code, Gemini CLI, and ChatGPT Developer Mode.

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

<Steps>
  <Step title="Install Node.js v22 and OpenClaw">
    ```bash theme={null}
    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
    ```
  </Step>

  <Step title="Configure OpenClaw">
    ```bash theme={null}
    openclaw configure
    ```

    Follow the interactive prompts to set your LLM provider API key.
  </Step>

  <Step title="Install the ChatbotX skill">
    Install the official ChatbotX skill from ClawHub, then configure your environment variables:

    ```bash theme={null}
    openclaw skills install chatbotx
    ```

    Set your credentials:

    ```bash theme={null}
    CHATBOTX_API_KEY=YOUR_WORKSPACE_TOKEN
    CHATBOTX_API_URL=https://app.chatbotx.io/api
    ```

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

    ```bash theme={null}
    CHATBOTX_ALLOW_SELF_SIGNED_CERT=true
    ```
  </Step>

  <Step title="Start the gateway and verify">
    ```bash theme={null}
    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.
  </Step>
</Steps>

***

## Hermes

<Steps>
  <Step title="Install Hermes">
    ```bash theme={null}
    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
    ```
  </Step>

  <Step title="Run the setup wizard">
    ```bash theme={null}
    hermes setup
    ```
  </Step>

  <Step title="Connect ChatbotX MCP Server">
    Add the ChatbotX MCP server using SSE transport:

    ```bash theme={null}
    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`.
  </Step>

  <Step title="Enable and verify via systemd">
    ```bash theme={null}
    sudo systemctl daemon-reload
    sudo systemctl enable --now hermes
    hermes mcp list
    journalctl -u hermes -f
    ```
  </Step>
</Steps>

***

## Claude Code

<Steps>
  <Step title="Install Claude Code">
    ```bash theme={null}
    npm install -g @anthropic-ai/claude-code
    ```
  </Step>

  <Step title="Add the ChatbotX MCP server">
    Choose either remote (SSE) or local (stdio) connection:

    **Option A: Remote SSE Connection**

    ```bash theme={null}
    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**

    ```bash theme={null}
    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`.
  </Step>

  <Step title="Verify the connection">
    ```bash theme={null}
    claude mcp list
    claude mcp get chatbotx
    ```

    The output should include your `chatbotx` server entry with the correct URL and transport type.
  </Step>
</Steps>

The Claude Desktop `claude_desktop_config.json` entry looks like this:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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`):

```json theme={null}
{
  "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`:

```bash theme={null}
# 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

<Steps>
  <Step title="Open BotFather">
    Open Telegram, search for the official **@BotFather** (verified with a blue checkmark), and click **Start**.
  </Step>

  <Step title="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`).
  </Step>

  <Step title="Copy the bot token">
    BotFather will return a **Telegram Bot Token** (e.g., `123456789:ABCdefGhIJKlmNoPQRs...`). Save it securely.
  </Step>
</Steps>

### Step 2: Find Your Chat ID

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

<Steps>
  <Step title="Get your Chat ID">
    Search for **@userinfobot** on Telegram and click **Start**. Copy the **Id** number it returns.
  </Step>

  <Step title="Save your Chat ID">
    Enter this Chat ID in your OpenClaw or Hermes configuration wizard to restrict bot access to your account only.
  </Step>
</Steps>

***

## 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         |