Lets AI agents manage ChatbotX contacts, conversations, flows, sequences, broadcasts, and AI agents through generated API tools.
Also known as ChatbotXIO/ChatbotX, mcp
- Stars
- 1,119
- Tools
- 55
- Downloads, 30 days
- —
- Latest version
- 1.8.1
- Last commit
- Nov 15, 2026
- License
- —
What is ChatbotX MCP?
ChatbotX lets AI agents manage ChatbotX contacts, conversations, flows, sequences, broadcasts, and AI agents through generated API tools. It exposes 55 tools, such as search_tools, call_tool, get_guide.
Summary generated from the project's README
About ChatbotX MCP server
Managing customer engagement workflows through AI agents is what ChatbotX enables for developers using Claude, Cursor, or ChatGPT. This MCP server connects your AI client directly to your ChatbotX workspace, allowing agents to interact with contacts, conversations, flows, sequences, and broadcasts. Instead of manual tool definitions, the server automatically generates tools from the ChatbotX OpenAPI specification, ensuring that your agent always has access to the latest API capabilities.
Users connect via OAuth 2.1 for remote clients or use workspace tokens for local stdio connections. To prevent overwhelming the agent's context, the server provides a curated set of 52 default tools while offering meta-tools like search_tools and call_tool to access the full catalog of approximately 350 operations. This architecture allows agents to discover specialized functions such as managing AI agents, coupons, or products on demand. The system also includes built-in safety features, requiring explicit human approval for mutating operations through a confirmation workflow.
What you can do with it
- 1Discover extended API capabilitiesHave the agent search for and execute tools related to products or coupons that are not in the default list.
Written from the project's README. Every use case is checked against a quote from it.
How to install ChatbotX MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall ChatbotX MCP in Claude Code
$ claude mcp add --transport http mcp https://app.chatbotx.io/mcp/messagesInstall ChatbotX MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"mcp": {
"url": "https://app.chatbotx.io/mcp/messages"
}
}
}Install ChatbotX MCP in VS Code
.vscode/mcp.json
{
"servers": {
"mcp": {
"type": "http",
"url": "https://app.chatbotx.io/mcp/messages"
}
}
}Install ChatbotX MCP in VS Code CLI
$ code --add-mcp '{"name":"mcp","type":"http","url":"https://app.chatbotx.io/mcp/messages"}'Install ChatbotX MCP in Codex
$ codex mcp add mcp --url https://app.chatbotx.io/mcp/messagesInstall ChatbotX MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.mcp] url = "https://app.chatbotx.io/mcp/messages"
Install ChatbotX MCP in Gemini CLI
$ gemini mcp add -s user --transport http mcp https://app.chatbotx.io/mcp/messagesInstall ChatbotX MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"mcp": {
"url": "https://app.chatbotx.io/mcp/messages",
"type": "http"
}
}
}ChatbotX MCP tools 55
Detected from the READMEsearch_toolscall_toolget_guidecapabilities_gettoken_getschemas_flow_specai_agents_listai_agents_createai_agents_updateai_files_listai_functions_listanalytics_new_contact_counts_per_day
Show all 55 toolsShow fewer tools
analytics_blocked_contacts_per_dayanalytics_flow_statsanalytics_broadcast_statsanalytics_sequence_step_statsbroadcasts_listbroadcasts_getbroadcasts_stopconnections_createconnection_providers_listconnect_sessions_getcontacts_createcontacts_getcontacts_listcontacts_list_tagscontacts_add_tags_by_namecontacts_list_custom_fieldscontacts_set_custom_fieldcontacts_list_messagescontacts_send_messagecontacts_send_flowcontacts_list_sequencescontacts_subscribe_sequencesconversations_listconversations_getconversations_assignerror_logs_listflows_listflows_getflows_createflows_update_draftflows_publishflows_validatekeywords_listmessages_listmini_apps_listmini_apps_createpipelines_listpipelines_list_itemspipelines_create_itempipelines_move_itemsequences_listsequences_getsequences_update
Configuration
CHATBOTX_ALLOW_SELF_SIGNED_CERTCHATBOTX_API_KEYCHATBOTX_API_URLCHATBOTX_MCP_TRANSPORTMCP_EVAL_SPEC_OUTPUT
Automated checks
Ran Nov 12, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work · What to fix for more points
- Source repository linked and reachablePass
- Open source license (OSI)No licenseFinding
- Commit or release in the last yearPass
- Package name not close to a popular packageNot checked
- Remote endpoint uses HTTPSPass
- Destructive tools are labelledPass
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesNot checked
README
View on GitHubChatbotX 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=<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:
| Tool | Description |
|---|---|
search_tools |
Search the full API for a tool not in the default set. Returns { matches, hint? }, where each match has its name, description, and input schema. |
call_tool |
Execute any tool by name, including ones search_tools found but tools/list doesn't show. |
get_guide |
Read an operational safety guide when a workflow involves approvals, flows, inbox handover, contacts, or pipelines. |
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 stringsearch_toolsreturned. - Unknown-tool suggestions: an unrecognized
namereturns the closest matching tool names instead of a bare error, so a model can self-correct without anothersearch_toolsround trip. - Pre-flight argument check: a
call_toolinvocation missing a field the selected tool'sinputSchemamarksrequiredis rejected immediately with the missing field names, instead of waiting for the real API's 422. A common wrapper mistake (nesting every field underbody/params/inputinstead of passing them at the top level) is called out explicitly. - Contact identifier auto-prefix: a bare email,
+-prefixed or local0-prefixed phone number, or numeric id passed asidentifierto 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_onlytoken only sees tools whosereadOnlyHintannotation is true — everyGETby default, plus any POST explicitly markedx-mcp.readOnlyHint: truefor an endpoint that reads without writing (no default tool currently uses this). capabilities_getandtoken_getare 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/listfalls 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
| Tool | Description |
|---|---|
capabilities_get |
Discover workspace entities and query channel before authoring a channel-bound FlowSpec to receive its supported blocks and limits. |
token_get |
Get the calling token's workspace id, permission (read_only/full), and scopes — check before attempting a write. |
schemas_flow_spec |
Get the JSON Schema for the spec object flows_publish/flows_update_draft/flows_validate accept — the authoritative reference for every flow step type. |
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
| Tool | Description |
|---|---|
capabilities_get |
Discover workspace entities and a requested channel's FlowSpec policy |
schemas_flow_spec |
Get JSON Schema for flow-spec DSL |
token_get |
Get calling token workspace id, permission, and scopes |
AI Agents
| Tool | Description |
|---|---|
ai_agents_list |
List AI agents |
ai_agents_create |
Create AI agent |
ai_agents_update |
Update AI agent |
ai_files_list |
List AI files |
ai_functions_list |
List AI functions |
Analytics
| Tool | Description |
|---|---|
analytics_new_contact_counts_per_day |
Get new contact counts per day |
analytics_blocked_contacts_per_day |
Get blocked contacts per day |
analytics_flow_stats |
Get flow analytics |
analytics_broadcast_stats |
Get broadcast stats |
analytics_sequence_step_stats |
Get sequence step stats |
Broadcasts
| Tool | Description |
|---|---|
broadcasts_list |
List broadcasts |
broadcasts_get |
Get broadcast |
broadcasts_stop |
Stop broadcast |
Connections
| Tool | Description |
|---|---|
connections_create |
Connect channel or integration |
connection_providers_list |
List connection providers |
connect_sessions_get |
Get connect session |
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
| Tool | Description |
|---|---|
contacts_create |
Create contact |
contacts_get |
Get contact by identifier (id:123, email:user@example.com, phone:+84...) |
contacts_list |
List contacts |
contacts_list_tags |
Get all tags added to contact |
contacts_add_tags_by_name |
Add tags to contact by name |
contacts_list_custom_fields |
Get all custom fields from contact |
contacts_set_custom_field |
Set contact custom field value |
contacts_list_messages |
List messages for contact |
contacts_send_message |
Send message to contact |
contacts_send_flow |
Send flow to contact |
contacts_list_sequences |
List contact sequence subscriptions |
contacts_subscribe_sequences |
Subscribe contact to sequences |
Conversations
| Tool | Description |
|---|---|
conversations_list |
List conversations |
conversations_get |
Get conversation |
conversations_assign |
Assign or unassign conversation to user or inbox team |
Error Logs
| Tool | Description |
|---|---|
error_logs_list |
List error logs |
Flows
| Tool | Description |
|---|---|
flows_list |
List flows |
flows_get |
Get flow |
flows_create |
Create flow |
flows_update_draft |
Update flow draft |
flows_publish |
Publish flow |
flows_validate |
Compile and validate flow spec without publishing |
Keywords
| Tool | Description |
|---|---|
keywords_list |
List keywords (automated responses) |
Messages
| Tool | Description |
|---|---|
messages_list |
List messages on conversation |
Mini Apps
| Tool | Description |
|---|---|
mini_apps_list |
List Mini Apps |
mini_apps_create |
Create Mini App |
Pipelines
| Tool | Description |
|---|---|
pipelines_list |
List pipelines |
pipelines_list_items |
List pipeline items |
pipelines_create_item |
Create pipeline item |
pipelines_move_item |
Move item to stage |
Sequences
| Tool | Description |
|---|---|
sequences_list |
List sequences |
sequences_get |
Get sequence |
sequences_update |
Update sequence name or active state |
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 for the stdio and workspace-token connection options.
Quick start
Option A — OAuth (recommended, remote)
Use the builder-hosted MCP endpoint. The client opens a browser for sign-in and consent; no workspace token belongs in the client configuration.
Claude Code:
claude mcp add chatbotx -t http -s user \
"https://app.chatbotx.io/mcp/messages"
Claude Desktop / Cursor:
{
"mcpServers": {
"chatbotx": {
"type": "http",
"url": "https://app.chatbotx.io/mcp/messages"
}
}
}
ChatGPT: add https://app.chatbotx.io/mcp/sse
as a custom connector. ChatGPT completes OAuth in the browser.
The load balancer must forward /mcp/* to the MCP server without stripping the
/mcp prefix. The builder serves protected-resource discovery under
/.well-known/oauth-protected-resource/mcp/*.
Option B — stdio (workspace token, local use)
Claude spawns the server process on demand. No server needs to be running. The workspace token is supplied via CHATBOTX_API_KEY.
The package is published to npm as chatbotx-mcp — npx -y chatbotx-mcp fetches and runs it with no local checkout or build required. Use a local node /path/to/dist/index.mjs instead when developing against this repo.
Claude Code CLI:
claude mcp add chatbotx \
-e CHATBOTX_API_KEY=<your-token> \
-e CHATBOTX_API_URL=https://your-instance.com/api \
-e CHATBOTX_MCP_TRANSPORT=stdio \
-s user \
-- npx -y chatbotx-mcp
Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"chatbotx": {
"command": "npx",
"args": ["-y", "chatbotx-mcp"],
"env": {
"CHATBOTX_API_KEY": "<your-token>",
"CHATBOTX_API_URL": "https://your-instance.com/api",
"CHATBOTX_MCP_TRANSPORT": "stdio"
}
}
}
}
Running from a local checkout instead (e.g. node /path/to/dist/index.mjs) works the same way — swap command/args accordingly.
Option C — SSE (workspace token, shared / remote access)
Run the server once and multiple clients connect via URL. Pass the workspace token in the request header.
# Start the server
pnpm start
# Add to Claude Code CLI
claude mcp add chatbotx \
-t sse \
-H "x-workspace-token: <your-token>" \
-s user \
"https://your-mcp-server.com/sse"
Claude Desktop:
{
"mcpServers": {
"chatbotx": {
"type": "sse",
"url": "https://your-mcp-server.com/sse",
"headers": {
"x-workspace-token": "<your-token>"
}
}
}
}
Option D — ChatGPT.com (workspace-token SSE)
ChatGPT.com connects via SSE. The server must be publicly reachable. Because ChatGPT does not support custom request headers, pass the workspace token directly in the URL:
- Start the server with
CHATBOTX_MCP_TRANSPORT=sse(orboth). - In ChatGPT Settings → Connectors → Add custom connector, set the URL:
When using this URL in a shell command, always quote it to preventhttps://your-mcp-server.com/sse?workspace_token=<your-token>?being interpreted as a glob:claude mcp add chatbotx -t sse -s user "https://your-mcp-server.com/sse?workspace_token=<your-token>" - Set
CHATBOTX_MCP_SERVER_INSTRUCTIONSso ChatGPT uses tools instead of its training data. Leave it unset unless replacing the full built-in workflow, including OAuth checkpoints.
Token resolution order
| Transport | Priority |
|---|---|
| SSE / Streamable HTTP | Authorization: Bearer (OAuth access token or workspace token) → ?workspace_token= or ?token= query param → x-workspace-token / x-chatbo-token header → CHATBOTX_API_KEY env |
| stdio | CHATBOTX_API_KEY env |
Configuration
Copy .env.example to .env and fill in the values:
cp .env.example .env
| Variable | Description | Default | Required |
|---|---|---|---|
CHATBOTX_API_KEY |
Workspace token for stdio only; leave empty on shared HTTP deployments | — | Yes (stdio) |
CHATBOTX_API_URL |
ChatbotX API origin, including /api (e.g. https://app.chatbotx.io/api) |
https://app.chatbotx.io/api |
Yes |
CHATBOTX_ALLOW_SELF_SIGNED_CERT |
Disable TLS verification (true/false) |
— | No |
CHATBOTX_SPEC_TTL_MS |
How long the fetched OpenAPI spec/tool list and a token's introspected scopes are trusted before a background re-fetch | 300000 |
No |
CHATBOTX_HTTP_TIMEOUT_MS |
Maximum duration for each OpenAPI, token introspection, or tool-call HTTP request | 30000 |
No |
CHATBOTX_MCP_TRANSPORT |
stdio | sse | both |
both |
No |
CHATBOTX_MCP_HOST |
SSE server host | 0.0.0.0 |
No |
CHATBOTX_MCP_PORT |
SSE server port | 3333 |
No |
CHATBOTX_MCP_SSE_PATH |
SSE endpoint path | /sse |
No |
CHATBOTX_MCP_MESSAGES_PATH |
JSON-RPC messages path | /messages |
No |
CHATBOTX_MCP_CORS_ORIGIN |
CORS origin allowed to call the SSE/HTTP endpoints | * |
No |
CHATBOTX_MCP_SERVER_NAME |
Display name sent to AI clients | package name | No |
CHATBOTX_MCP_SERVER_INSTRUCTIONS |
Instructions sent to AI clients on connect (helps ChatGPT know when to call tools) | built-in default | No |
CHATBOTX_MCP_OAUTH_ENABLED |
Enable OAuth 2.1 protected-resource metadata and bearer challenges | true |
No |
CHATBOTX_MCP_OAUTH_ISSUER |
Authorization server issuer URL | derived from CHATBOTX_API_URL |
No |
CHATBOTX_MCP_PUBLIC_URL |
Canonical public origin; required in production so metadata advertises the TLS endpoint | derived from request headers | Yes (production) |
Scripts
# Development with watch mode
pnpm dev:mcp
# Build for production
pnpm build
# Run built server
pnpm start
# Type check
pnpm check-types
# List loaded tools (requires CHATBOTX_API_URL and CHATBOTX_API_KEY in .env)
dotenv -e .env -- tsx src/test-tools.ts
Evaluating tool selection
Two layers of evaluation cover search_tools/call_tool accuracy — a fast offline gate and a full LLM-driven business eval.
eval:search — offline ranking gate (no API key, seconds)
Scores every prompt in the eval corpus (evals/cases.ts) through the real searchTools() ranker against a real generated spec, with no LLM in the loop. Use this after any change to src/server/search/ or to a public route's summary/description.
- Dump the current OpenAPI spec (the builder test already has a hook for this — see
apps/builder/__tests__/public-spec-operations.test.ts):MCP_EVAL_SPEC_OUTPUT=/absolute/path/public-spec.json \ pnpm --filter builder test -- public-spec-operations.test.ts - Run the gate against it:
Prints per-locale top-1/top-3/empty-result rates, but enforces the configured thresholds only for English.pnpm --filter chatbotx-mcp eval:search --spec /absolute/path/public-spec.json [--min-top1 0.65] [--min-top3 0.85] [--verbose]--verbosealso lists every prompt that missed the top 3, with the ranker's actual top matches, for targeted ranking or description fixes.
eval:business — full LLM-driven business eval
Spins up a synthetic HTTP sandbox implementing the generated spec's operations, connects a real MCP client, and drives gpt-4o-mini/gpt-4.1-mini (or any @ai-sdk/openai-supported model) through the selected corpus. business contains 240 prompts (48 families × 5 locales: vi, vi-unaccented, colloquial, en, mixed); multilingual is the 80-case smoke matrix (16 families × en, vi-natural, es, fr, zh). Requires OPENAI_API_KEY.
pnpm --filter chatbotx-mcp eval:business \
--spec /absolute/path/public-spec.json \
--out /absolute/path/out/baseline \
--phase smoke \
--seed 20260923 \
--models gpt-4o-mini,gpt-4.1-mini \
[--repeat N] \
[--corpus business|multilingual] \
[--exposure default|meta-only|both] \
[--cases family-a,family-b] \
[--server-source /absolute/path/to/apps/mcp-server]
--repeat Nruns every selected case under every model and exposure N times. Smoke runs default to 3; baseline and candidate runs default to 1.--exposure meta-onlyrestricts the model's tool set tosearch_tools/call_toolonly (no directly-listed default tools) — the path a client using only the default connection payload takes for any request outside the ~45 default-visible tools.both(the default) runs every case under both exposures.- Each episode is graded on semantic arguments, ordered tool sequences, its expected final HTTP state, API-error claims, post-failure mutations, and step exhaustion. The summary reports the pass rate per model × exposure × locale × family; episodes also record
searchRank,callToolErrorCount, andunknownToolCount. - The smoke sandbox includes contact, conversation reply, flow, broadcast, appointment, and analytics fixtures. No public appointment-availability operation exists, so unavailable-slot coverage exercises
appointments_bookreturning 422. - Compare two runs (regressions fail the command):
Reports any case that regressed from pass to non-pass, plus the averagepnpm --filter chatbotx-mcp eval:business --compare /absolute/path/out/baseline /absolute/path/out/candidatesearchRankand totalcallToolErrorCountdelta between the two runs.
Evaluation output is written under evals/out/ (gitignored) unless --out points elsewhere.
Project structure
src/
├── index.ts # Entry point — loads spec, starts transport(s)
├── env.ts # Environment variable schema
├── guides/ # Packaged markdown operational guides
├── http.ts # Timed fetch helper for OpenAPI, token, and tool requests
├── openapi-loader.ts # Fetches OpenAPI spec → DynamicTool list, x-mcp
│ # visibility/scope/HITL parsing, scope-filtered getVisibleTools()
├── token-introspection.ts # GET /v1/token → cached {permission, scopes} per token
├── test-tools.ts # Dev utility — prints loaded tools
└── server/
├── create-mcp-server.ts # MCP server factory, resources, tools/list + tools/call
├── hitl-gate.ts # Two-step confirmation gate for mutations
├── meta-tools.ts # search_tools / call_tool / get_guide definitions
├── execute-tool.ts # Shared HTTP dispatch, confirmation, argument normalization
├── search/ # search_tools ranking: normalization and IDF scoring
├── sse-server.ts # SSE / Streamable HTTP transport
└── stdio-server.ts # stdio transport
evals/
├── cases.ts # Eval corpus: business-intent prompts × 5 locale variants
├── sandbox.ts # Synthetic HTTP server implementing the generated spec
├── run.ts # eval:business — drives an LLM through the MCP server
└── search-audit.ts # eval:search — offline ranking gate, no LLM
ChatbotX MCP questions
How do I add ChatbotX MCP to Claude Code?
Run claude mcp add --transport http mcp https://app.chatbotx.io/mcp/messages in your terminal. Add --scope user to make it available in every project.
How do I add ChatbotX MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does ChatbotX MCP provide?
It exposes 55 tools, including search_tools, call_tool, get_guide, capabilities_get, token_get.
How do AI clients connect to the ChatbotX MCP server?
Remote clients authenticate through OAuth 2.1 against a single endpoint, using Streamable HTTP at /mcp/messages or legacy SSE at /mcp/sse, and pick the target workspace on the consent screen.
Why does ChatbotX MCP only show a subset of its API operations as tools?
Listing all ~350 operations would overwhelm an agent's context, so only a curated default set is exposed; search_tools and call_tool reach the rest of the API.
How do I use a tool that is not in the default tool list?
Search the full API with search_tools to find the tool, then execute it by name with call_tool.
Does ChatbotX MCP require confirmation before making changes?
Yes. Mutating operations return CONFIRMATION_REQUIRED with the policy and proposed arguments, and you repeat the call with _confirm: true after the user approves.
Which token can I use with the ChatbotX MCP server?
A workspace token works for stdio and legacy connections; OAuth 2.1 is recommended for remote clients.