ChatbotX

ChatbotX MCP Server

Model Context Protocol server for ChatbotX. Gives AI agents (Claude, Cursor, ChatGPT, etc.) access to your ChatbotX workspace through tools that are automatically generated from the ChatbotX OpenAPI spec — no manual tool definitions needed.

Published skill/agent distribution docs live in the separate chatbotx-agent package; this repo owns the MCP server implementation and README.

How it works

On startup the server fetches {CHATBOTX_API_URL}/public-spec.json and registers one MCP tool per API operation the spec marks x-mcp.visibility: "default". CHATBOTX_API_URL is the origin including the /api path prefix (e.g. https://app.chatbotx.io/api). Adding a new default-visible API endpoint in ChatbotX automatically makes it available as a tool — the spec is re-fetched in the background whenever it's older than CHATBOTX_SPEC_TTL_MS (default 5 minutes), so a new/changed operation shows up on the next tools/list call without a server restart.

OAuth 2.1

Remote MCP clients should authenticate through OAuth 2.1. The production endpoints are https://app.chatbotx.io/mcp/messages for Streamable HTTP and https://app.chatbotx.io/mcp/sse for legacy SSE — the same URL for every account, so it works as a Claude or ChatGPT marketplace connector. The user picks the target workspace on the consent screen, and every token the client holds acts on that workspace; to switch, disconnect and connect again. Only workspace owners and superAdmin members can authorize. An explicit ?workspace_id= (or x-workspace-id header) may select a workspace only for legacy connections that predate the picker. A different workspace than the one consented for a new connection is rejected; disconnect and connect again to switch. The builder settings block Settings → Integrations → ChatbotX MCP provides the exact connection URL and lets each user revoke their OAuth grants.

Legacy workspace tokens remain supported for stdio and existing connections.

Default tools vs. the full API

ChatbotX's public API has ~350 operations. Listing all of them as MCP tools overwhelms an agent's context and its ability to pick the right one, so tools/list returns only a curated default set (see below) plus three meta-tools:

Use search_tools when the task needs something outside the default set (e.g. deleting a resource, managing AI agents, coupons, products) — then invoke it with call_tool.

search_tools's catalog (tool names, summaries, descriptions) is entirely English. The calling client must translate the user's intent into an English "action + resource" query before searching; the ranker does not translate. When an accented Latin or non-Latin query reaches the server, search_tools returns a hint asking the client to translate and retry in English.

• Name normalization: a dotted or camelCase operation label (contacts.get, contactsGet) is accepted and re-derived to the executable snake_case name — you don't have to pass the exact string search_tools returned.
• Unknown-tool suggestions: an unrecognized name returns the closest matching tool names instead of a bare error, so a model can self-correct without another search_tools round trip.
• Pre-flight argument check: a call_tool invocation missing a field the selected tool's inputSchema marks required is rejected immediately with the missing field names, instead of waiting for the real API's 422. A common wrapper mistake (nesting every field under body/params/input instead of passing them at the top level) is called out explicitly.
• Contact identifier auto-prefix: a bare email, +-prefixed or local 0-prefixed phone number, or numeric id passed as identifier to a contact tool is automatically prefixed (email:/phone:/id:) before the request is sent, matching what the API actually requires.

Human approval

Every operation carries an x-mcp.hitlPolicy from the public OpenAPI spec; reads use none. Mutating operations return CONFIRMATION_REQUIRED with the policy, proposed arguments, and current state when available; show that response to the user, then repeat the same call with _confirm: true only after explicit approval. _confirm is a compatibility guardrail, not an authorization boundary.

Writes that are read-only computations declare hitlPolicy: "none" in the backend. Destructive writes also carry the MCP destructiveHint annotation. When a current-state read fails for any reason, currentState is omitted and currentStateUnavailable explains why; the failed read never blocks confirmation.

Every tools/list definition also includes a human-readable title and explicit readOnlyHint, destructiveHint, idempotentHint, and openWorldHint annotations. Dynamic tool titles come from the OpenAPI operation summary. The loader marks confirm_outbound operations as open-world by default; an x-mcp.openWorldHint override takes precedence.

Scope-based filtering

tools/list is further narrowed to what the calling token can actually use, resolved once per token via GET /v1/token (introspectToken, cached per token value for CHATBOTX_SPEC_TTL_MS):

• A token missing a scope never sees that scope's tools (they still exist for search_tools/call_tool, which always hit the real API and get a real 403 if unauthorized).
• A read_only token only sees tools whose readOnlyHint annotation is true — every GET by default, plus any POST explicitly marked x-mcp.readOnlyHint: true for an endpoint that reads without writing (no default tool currently uses this).
• capabilities_get and token_get are always visible regardless of scope — an agent needs them to discover what it *can* do and what its token allows before anything else works.
• If token introspection itself fails (network blip, unreachable API), filtering fails open — tools/list falls back to the full default set. The actual API call still enforces the token's real permissions either way.

Discovery tools an agent should call first

Available tools

Tool names are derived from the OpenAPI operationId converted to snake_case (e.g. tags.list → tags_list). The current default set has 52 tools:

Capabilities

AI Agents

Analytics

Broadcasts

Connections

For connections_create with provider: "api", the response includes a one-time secret.token. Store it before discarding the response; it is never retrievable again.

Contacts

Conversations

Error Logs

Flows

Keywords

Messages

Mini Apps

Pipelines

Sequences

Everything else — deletes, less-common resources (coupons, products, webhooks, saved replies, tags/triggers/inboxes/custom-fields management, workspace members, etc.), connection lifecycle management beyond the initial connect (disconnect, reconnect, refresh, verify, rename) — is reachable via search_tools → call_tool, not tools/list.

Operations whose security names no workspace-token scheme are not tools at all — isWorkspaceTokenOperation (src/openapi-loader.ts) drops them, so neither tools/list nor search_tools returns them. That covers deprecated operations, channel-token operations (/v1/channels/api/*), and the mobile-app-only member surface (/v1/me*, /v1/realtime/connect-token, marked by MOBILE_APP_TOKEN_ONLY_PATHS in apps/builder/src/lib/orpc/public-spec.ts): an MCP OAuth or workspace token has no member identity and would always get 401.

conversations_list accepts view: "compact" to drop ad attribution and thread-control metadata from each conversation's contact inboxes (default full); flows_list accepts enableInInbox: true to return only flows that can be started from the inbox.

Prerequisites

• Node.js >= 24
• A workspace token only