Tools

The ChatbotX MCP Server gives AI agents direct programmatic access to your self-hosted ChatbotX Workspace. Tools are automatically generated from the ChatbotX OpenAPI specification (public-spec.json), exposing over 380 operations across the entire platform without manual tool definitions.

How Tools Reach Your Context

Listing all ~380 API operations at once would overwhelm an AI agent’s context window, increasing token cost and leading to hallucinated arguments. To prevent this, ChatbotX MCP uses a two-tier tool discovery model:

Curated Default Set (43 Tools)

A curated set of 43 essential tools (plus 2 meta-tools) is always visible in tools/list for common operations: contacts, conversations, flows, broadcasts, sequences, and analytics.

Meta-Tools (Full API Access)

Two fixed meta-tools (search_tools and call_tool) allow the agent to discover and run any of the ~337 extended API operations on demand with zero context cost.

Meta-Tools

When an agent needs an operation outside the default set (such as managing coupons, webhooks, tags, triggers, or workspace members), it uses the meta-tools:

Tool	Description	Input Arguments
`search_tools`	Search the full catalog of ~380 ChatbotX API tools. Returns matching tool names, descriptions, and input schemas.	`query` (string, required): Task description in natural language. `limit` (number, optional): Max results (default 10, max 25).
`call_tool`	Execute any ChatbotX tool by name, including tools discovered through `search_tools`.	`name` (string, required): Exact tool name. `arguments` (object, optional): Arguments JSON object for the tool.

Scope-Based Filtering

On connect, the server introspects the caller’s Workspace Token (GET /v1/token) and filters the visible tool list:

Missing Scopes: If a token lacks a required scope (e.g. broadcasts), tools requiring that scope are hidden from tools/list.
Read-Only Tokens: Tokens with read_only permission only see read operations (GET endpoints, protecting your workspace against unintended writes).
Auto-Refresh: The server re-fetches the OpenAPI specification and token cache every 5 minutes (CHATBOTX_SPEC_TTL_MS), ensuring newly deployed endpoints become available without restarting the MCP server.

Discovery Tools (Call These First)

Before performing business actions, AI agents should invoke discovery tools to inspect available workspace resources and verify permissions:

Tool	Method	Description
`capabilities_get`	`GET`	Discover active inboxes, WhatsApp templates, custom fields, bot fields, tags, AI agents, sequences, and flows. Returns the actual IDs needed for subsequent tool calls.
`token_get`	`GET`	Retrieve the calling token’s workspace ID, permission level (`read_only` or `full`), and assigned scopes. Always check this before attempting write operations.
`schemas_flow_spec`	`GET`	Retrieve the complete JSON Schema for the Flow DSL specification. Serves as the authoritative guide for building or updating flow nodes.

Default Tools (43 Core Tools)

The following 43 tools are registered in the default tools/list set. Tool names follow the OpenAPI operationId converted to snake_case.

Capabilities (3 tools)

Tools for environment discovery, token introspection, and schema validation.

Tool	Description
`capabilities_get`	Discover workspace inboxes, templates, custom fields, tags, sequences, and flows.
`schemas_flow_spec`	Get JSON Schema for the flow-spec DSL used by flow builders.
`token_get`	Get calling token workspace ID, permission, and authorized scopes.

AI Agents (5 tools)

Manage autonomous AI agents, knowledge base files, and custom AI functions.

Tool	Description
`ai_agents_list`	List all AI agents configured in the workspace.
`ai_agents_create`	Create a new AI agent with model settings and system instructions.
`ai_agents_update`	Update configuration, prompt, or attached tools of an existing AI agent.
`ai_files_list`	List knowledge base documents and media uploaded for AI agents.
`ai_functions_list`	List custom AI functions available to AI agents.

Analytics (5 tools)

Access workspace growth, contact activity, flow engagement, and sequence performance.

Tool	Description
`analytics_new_contact_counts_per_day`	Get daily counts of newly acquired contacts over a date range.
`analytics_blocked_contacts_per_day`	Get daily counts of contacts blocked by channel or user action.
`analytics_flow_stats`	Retrieve node-level execution and completion metrics for a flow.
`analytics_broadcast_stats`	Retrieve delivery, read, and failure metrics for a broadcast.
`analytics_sequence_step_stats`	Retrieve step-by-step progression and drop-off stats for a sequence.

Broadcasts (3 tools)

Send and control mass outbound campaigns across connected channels.

Tool	Description
`broadcasts_list`	List recent broadcast campaigns and their current delivery status.
`broadcasts_get`	Retrieve detailed configuration and target audience of a specific broadcast.
`broadcasts_stop`	Halt an ongoing broadcast campaign immediately.

Contacts (12 tools)

Comprehensive contact data management, tag assignment, custom fields, and direct messaging.

Tool	Description
`contacts_create`	Add a new contact with phone, email, or channel identifiers.
`contacts_get`	Retrieve a contact by ID or identifier (`id:123`, `email:user@example.com`, `phone:+84...`).
`contacts_list`	List contacts in the workspace with pagination and advanced filter conditions.
`contacts_list_tags`	List all tags applied to a specific contact.
`contacts_add_tags_by_name`	Add one or more tags to a contact using human-readable tag names.
`contacts_list_custom_fields`	Retrieve all custom field values stored on a contact.
`contacts_set_custom_field`	Update or set a custom field value for a contact.
`contacts_list_messages`	Retrieve message history for a specific contact.
`contacts_send_message`	Send a direct text message or interactive response to a contact.
`contacts_send_flow`	Trigger an automation flow for a contact.
`contacts_list_sequences`	List active sequence subscriptions for a contact.
`contacts_subscribe_sequences`	Enroll a contact into one or more automated sequences.

Conversations (3 tools)

Live chat inbox management and agent assignment.

Tool	Description
`conversations_list`	List active, pending, or closed inbox conversations.
`conversations_get`	Retrieve full details and metadata for a conversation thread.
`conversations_assign`	Assign or unassign a conversation to a specific agent or inbox team.

Error Logs (1 tool)

Inspect runtime execution errors across flows, webhooks, and integrations.

Tool	Description
`error_logs_list`	List recent system and execution error logs with stack traces.

Flows (6 tools)

Build, validate, test, and publish conversational automation flows.

Tool	Description
`flows_list`	List all automation flows in the workspace.
`flows_get`	Retrieve the complete flow definition and node graph by ID.
`flows_create`	Create a new flow draft with initial nodes and optionally publish immediately in one call.
`flows_update_draft`	Update node connections and contents of an unpublished flow draft.
`flows_publish`	Publish flow draft to make it live for incoming messages.
`flows_validate`	Compile and validate a flow spec DSL against schema rules without publishing.

Keywords (1 tool)

Automated keyword triggers that match customer messages.

Tool	Description
`keywords_list`	List configured keywords, matching rules, and linked response flows.

Messages (1 tool)

Conversation thread message inspection.

Tool	Description
`messages_list`	List messages within an inbox conversation thread.

Sequences (3 tools)

Drip campaigns and delayed follow-up messaging sequences.

Tool	Description
`sequences_list`	List all sequence automations configured in the workspace.
`sequences_get`	Retrieve sequence configuration, steps, delays, and enrolled contacts count.
`sequences_update`	Update sequence name, scheduling parameters, or active state.

Extended Operations via Meta-Tools

All other ChatbotX API endpoints (~337 operations) are fully functional through search_tools and call_tool. The agent can search by natural language keyword, receive the exact parameter schema, and invoke the operation. Common resource areas reachable via meta-tools:

Tags Management

Manage tags at the workspace level:

tags_list: List all available workspace tags.
tags_create: Create a new tag for audience segmentation.
tags_get: Get tag details by ID.
tags_update: Rename or re-color an existing tag.
tags_delete: Remove a tag from the workspace.

Custom Fields and Bot Fields

Define global variables and contact attributes:

custom_fields_list: List custom field definitions.
custom_fields_create: Define a new contact custom field (text, number, date, boolean).
custom_fields_delete: Remove a custom field definition.
bot_fields_list: List global workspace bot fields.
bot_fields_set: Set or update the global value of a bot field.

Triggers and Webhooks

Handle real-time event triggers and incoming webhooks:

triggers_list: List automation event triggers.
triggers_create: Create an event trigger (e.g. tag added, field changed).
webhooks_list: List registered incoming and outgoing webhooks.
webhooks_create: Register a new webhook endpoint.
webhooks_delete: Delete an obsolete webhook.

Saved Replies and Templates

Canned responses and multi-channel message templates:

saved_replies_list: List canned replies for live chat agents.
saved_replies_create: Add a new saved reply shortcut.
whatsapp_templates_list: List approved WhatsApp message templates.

Coupons and Gamification

Promotional marketing tools:

coupons_list: List active promotional coupon batches.
coupons_create: Generate single-use or multi-use discount coupons.
coupons_validate: Validate coupon code validity and redemption limits.

Team Members and Inboxes

Workspace collaboration and inbox management:

workspace_members_list: List workspace collaborators and roles.
invites_create_invite_token: Generate an invitation link for new team members.
inboxes_list: List connected inboxes and communication channels.

Tool Execution Protocol

When an AI assistant calls a tool, it formats the request as a standard JSON-RPC 2.0 message:

Example: Direct Tool Call (`contacts_create`)

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "contacts_create",
    "arguments": {
      "first_name": "Minh",
      "last_name": "Nguyen",
      "phone": "+84901234567",
      "email": "minh.nguyen@example.com"
    }
  },
  "id": 1
}

Example: Discovery via Meta-Tool (`search_tools` and `call_tool`)

Search for an extended operation

The agent searches for tag management tools:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "search_tools",
    "arguments": {
      "query": "create new tag for contacts"
    }
  },
  "id": 2
}

Inspect search results

The server returns matching tool definitions including tags_create with its inputSchema.

Execute the tool via call_tool

The agent invokes call_tool passing the target name and arguments:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "call_tool",
    "arguments": {
      "name": "tags_create",
      "arguments": {
        "name": "VIP Customer",
        "color": "#155dfc"
      }
    }
  },
  "id": 3
}

For instructions on setting up ChatbotX MCP with Claude, Cursor, ChatGPT, Codex, or OpenClaw, see Platform Setup.

Getting Started

Usage & Reference

How Tools Reach Your Context

Curated Default Set (43 Tools)

Meta-Tools (Full API Access)

Meta-Tools

Scope-Based Filtering

Discovery Tools (Call These First)

Default Tools (43 Core Tools)

Capabilities (3 tools)

AI Agents (5 tools)

Analytics (5 tools)

Broadcasts (3 tools)

Contacts (12 tools)

Conversations (3 tools)

Error Logs (1 tool)

Flows (6 tools)

Keywords (1 tool)

Messages (1 tool)

Sequences (3 tools)

Extended Operations via Meta-Tools

Tool Execution Protocol

Example: Direct Tool Call (`contacts_create`)

Example: Discovery via Meta-Tool (`search_tools` and `call_tool`)

​How Tools Reach Your Context

Curated Default Set (43 Tools)

Meta-Tools (Full API Access)

​Meta-Tools

​Scope-Based Filtering

​Discovery Tools (Call These First)

​Default Tools (43 Core Tools)

​Capabilities (3 tools)

​AI Agents (5 tools)

​Analytics (5 tools)

​Broadcasts (3 tools)

​Contacts (12 tools)

​Conversations (3 tools)

​Error Logs (1 tool)

​Flows (6 tools)

​Keywords (1 tool)

​Messages (1 tool)

​Sequences (3 tools)

​Extended Operations via Meta-Tools

​Tool Execution Protocol

​Example: Direct Tool Call (contacts_create)

​Example: Discovery via Meta-Tool (search_tools and call_tool)

How Tools Reach Your Context

Meta-Tools

Scope-Based Filtering

Discovery Tools (Call These First)

Default Tools (43 Core Tools)

Capabilities (3 tools)

AI Agents (5 tools)

Analytics (5 tools)

Broadcasts (3 tools)

Contacts (12 tools)

Conversations (3 tools)

Error Logs (1 tool)

Flows (6 tools)

Keywords (1 tool)

Messages (1 tool)

Sequences (3 tools)

Extended Operations via Meta-Tools

Tool Execution Protocol

Example: Direct Tool Call (`contacts_create`)

Example: Discovery via Meta-Tool (`search_tools` and `call_tool`)