MCP server

Endpoint and auth

Authenticate with a normal Chatbox AI API key, created in the dashboard under Settings → API & Webhooks (see Authentication). The key's scopes decide which tools work. A tool whose scope the key lacks answers insufficient_scope, so an agent connected with a read-only key cannot send anything.

Client setup

Claude Code

claude mcp add --transport http chatbox-ai https://api.chatboxai.dev/mcp --header "Authorization: Bearer cbk_live_YOUR_KEY"

Or read the key from an environment variable so it never lands in your shell history as text:

export CHATBOX_API_KEY="cbk_live_YOUR_KEY"
claude mcp add --transport http chatbox-ai https://api.chatboxai.dev/mcp --header "Authorization: Bearer $CHATBOX_API_KEY"

Claude Desktop

Add this to claude_desktop_config.json. It runs the server through the mcp-remote bridge:

{
  "mcpServers": {
    "chatbox-ai": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.chatboxai.dev/mcp",
        "--header",
        "Authorization:${CHATBOX_AUTH}"
      ],
      "env": {
        "CHATBOX_AUTH": "Bearer cbk_live_YOUR_KEY"
      }
    }
  }
}

Note there is no space after the colon in Authorization:${CHATBOX_AUTH}: some clients split arguments on spaces. The CHATBOX_AUTH environment value carries the full Bearer cbk_live_... string instead. Restart Claude Desktop after saving.

Codex CLI

In ~/.codex/config.toml, point Codex at the HTTP endpoint and tell it which environment variable holds the key:

[mcp_servers.chatbox-ai]
url = "https://api.chatboxai.dev/mcp"
bearer_token_env_var = "CHATBOX_API_KEY"

export CHATBOX_API_KEY=cbk_live_YOUR_KEY

Alternatively, use the mcp-remote stdio bridge:

[mcp_servers.chatbox-ai]
command = "npx"
args = ["-y", "mcp-remote", "https://api.chatboxai.dev/mcp", "--header", "Authorization:${CHATBOX_AUTH}"]
env = { CHATBOX_AUTH = "Bearer cbk_live_YOUR_KEY" }

Cursor

{
  "mcpServers": {
    "chatbox-ai": {
      "url": "https://api.chatboxai.dev/mcp",
      "headers": {
        "Authorization": "Bearer cbk_live_YOUR_KEY"
      }
    }
  }
}

VS Code

In .vscode/mcp.json, VS Code prompts for the key the first time the server starts and stores it securely, so the file itself is safe to commit:

{
  "servers": {
    "chatbox-ai": {
      "type": "http",
      "url": "https://api.chatboxai.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${input:chatbox-api-key}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "chatbox-api-key",
      "description": "Chatbox AI API key",
      "password": true
    }
  ]
}

Windsurf and any other MCP client

Any client that supports Streamable HTTP needs just the URL and the header:

Transport:  Streamable HTTP
URL:        https://api.chatboxai.dev/mcp
Header:     Authorization: Bearer cbk_live_YOUR_KEY

A client that only runs local (stdio) servers can use the mcp-remote bridge, with CHATBOX_AUTH set to Bearer cbk_live_YOUR_KEY in its environment:

npx -y mcp-remote https://api.chatboxai.dev/mcp --header "Authorization:${CHATBOX_AUTH}"

Tools

Each tool maps onto the matching API endpoint and follows the same rules (24-hour window, opt-out, idempotency, pagination).

Example prompts

• "Send the order_shipped template to +919999900000 with Asha, #1234 and Friday."
• "List contacts tagged vip."
• "Which of my templates are approved, and how many parameters does each one need?"
• "Did the last message to +919999900000 get delivered?"
• "Mark order clx9q7r4v0005 as shipped."
• "Show me the failed webhook deliveries for my WooCommerce subscription."

Safety

• messages:send spends your allowance. Every send counts against the workspace's monthly message allowance, and Meta's charges apply as usual.
• Create a key with only the scopes you need. For an agent that answers questions about your contacts and templates, give it contacts:read and templates:read and nothing else. Make a separate key for the agent so you can revoke it on its own.
• Your agent should ask before sending. Most MCP clients show each tool call for approval before it runs. Keep approval on for send_template_message and send_text_message rather than auto-approving them, and read the recipient and template before you accept.
• Opted-out contacts cannot be messaged through the MCP server any more than through the API.

Troubleshooting

Every other error has the same shape and codes as the REST API: see the errors table.