Testing & Troubleshooting

Learn how to verify your ChatbotX MCP Server connection, test live tool executions, and resolve common configuration or network issues.

For the comprehensive directory of all default and extended tools, see Tools. For client installation instructions, see Platform Setup.

Testing Connection

Before connecting AI assistants, verify that your ChatbotX MCP endpoint is reachable and streaming events properly.

Test SSE Stream via cURL

Run curl with streaming output enabled (-N) and a short timeout:

Linux / macOS (Bash)
Windows (PowerShell)

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

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

# Cloud instance
curl.exe -i -N --max-time 10 `
  -H "x-workspace-token: YOUR_WORKSPACE_TOKEN" `
  -H "Accept: text/event-stream" `
  "https://app.chatbotx.io/mcp/sse"

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

When the connection is working, the server immediately responds with HTTP 200 OK and an initial SSE endpoint message:

HTTP/1.1 200 OK
Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive
event: endpoint
data: /mcp/messages?sessionId=a1b2c3d4-e5f6-7890-abcd-ef1234567890

SSE connections stay open continuously to receive server-sent events. It is completely normal for the command to stop when the --max-time limit expires. As long as you see HTTP/1.1 200 OK and event: endpoint, your server is operational.

Testing Tool Execution

You can test a tool call directly over HTTP without opening an AI assistant interface.

Test capabilities_get

Send a JSON-RPC 2.0 request to inspect your workspace capabilities:

curl https://app.chatbotx.io/mcp/sse \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "x-workspace-token: YOUR_WORKSPACE_TOKEN" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "capabilities_get",
      "arguments": {}
    },
    "id": 1
  }'

A successful response returns your workspace metadata, connected channels, and available automation resources:

{
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"workspace\":{\"id\":\"ws_123\",\"name\":\"Acme Store\"},\"channels\":[{\"type\":\"whatsapp\",\"status\":\"active\"}],\"tags\":[{\"id\":\"t_vip\",\"name\":\"VIP\"}]}"
      }
    ]
  },
  "id": 1
}

Common Issues & Resolutions

401 Unauthorized

Cause: The Workspace Token is missing, expired, or invalid.Resolution:

Go to Settings > Integrations > Workspace token in your ChatbotX dashboard and copy your token.
If using headers, verify the header name is x-workspace-token (or x-chatbo-token).
If using web connectors (ChatGPT / Perplexity), verify the token is appended to the URL: ?token=YOUR_WORKSPACE_TOKEN.

403 Forbidden

Cause: Token lacks required scopes, or a read_only token attempted a write operation.Resolution:

Call token_get to check your token’s permission level (read_only vs full) and authorized scopes.
If your token has read_only permission, write tools like contacts_create, contacts_send_flow, and flows_publish are intentionally blocked.
Generate a token with write access in Settings > Integrations > Workspace token if modification actions are required.

Tools not appearing in tools/list

Cause: The tool is either hidden behind meta-tools, filtered by token scope, or recently added to the API.Resolution:

Curated default set: Only 43 primary tools appear directly in tools/list. The remaining ~337 API operations are accessed via search_tools and call_tool.
OpenAPI cache TTL: The MCP server caches the OpenAPI spec for 5 minutes (CHATBOTX_SPEC_TTL_MS). Newly deployed endpoints appear on the next automatic refresh, or immediately upon restarting the MCP server.
Missing token scope: If your token lacks a specific scope (e.g. broadcasts), matching tools are hidden from tools/list.

SSE Connection hangs or drops (Self-Hosted)

Cause: The reverse proxy (Nginx / Cloudflare / Apache) is buffering responses instead of streaming them immediately.Resolution:

For Nginx, add proxy_buffering off; and proxy_cache off; inside the /mcp/ location block.
Increase read timeout settings: proxy_read_timeout 86400s;.
If using Cloudflare, ensure response buffering is disabled for the /mcp/ path.

Self-signed TLS certificate rejected

Cause: The client runtime rejects self-signed certificates during local development.Resolution:

Set CHATBOTX_ALLOW_SELF_SIGNED_CERT=true in your MCP server environment variables or .env file.
For Node-based clients, you can also set NODE_TLS_REJECT_UNAUTHORIZED=0 in local development shells.

Port 3333 already in use

Cause: A previous instance of chatbotx-mcp-server is still running in the background.Resolution:

Find and terminate the process:
lsof -ti:3333 | xargs kill -9
Or change the listening port by setting CHATBOTX_MCP_PORT=3334 in your environment.

ChatGPT / Perplexity cannot discover tools

Cause: URL parameters are missing, or custom headers are not supported.Resolution:

Both ChatGPT and Perplexity web connectors require the token inside the connector URL query string:
https://app.chatbotx.io/mcp/sse?token=YOUR_WORKSPACE_TOKEN
In the connector authentication dialog, select None or No Authentication because credentials are already embedded in the URL.

Diagnostic Checklist

Before opening an issue or contacting support, verify the following:

ChatbotX backend is running and /api endpoints respond to health checks.
Workspace token was copied directly from Settings > Integrations > Workspace token.
SSE endpoint responds with HTTP 200 OK and event: endpoint when tested with curl.
Reverse proxy has proxy_buffering off; configured for streaming paths.
Client configuration file syntax is valid (valid JSON for Antigravity/Cursor, valid TOML for Codex).

Getting Started

Usage & Reference

Testing Connection

Test SSE Stream via cURL

Testing Tool Execution

Test capabilities_get

Common Issues & Resolutions

Diagnostic Checklist

​Testing Connection

​Test SSE Stream via cURL

​Testing Tool Execution

​Test capabilities_get

​Common Issues & Resolutions

​Diagnostic Checklist

Testing Connection

Test SSE Stream via cURL

Testing Tool Execution

Test capabilities_get

Common Issues & Resolutions

Diagnostic Checklist