ChatterMate MCP Server

The ChatterMate MCP server (chattermate-mcp) exposes your ChatterMate instance to AI agents through the Model Context Protocol. Connect it to Claude, an IDE assistant, or any MCP-compatible client and the agent can read and manage your agents, workflows, knowledge sources, widgets, in-app actions, journeys and help center on your behalf.

This is the inverse of MCP Tools. MCP Tools let your ChatterMate agents call out to external services. The MCP Server described here lets an external AI agent call in to ChatterMate to configure it.

How it works

The server is a thin, stdio-based bridge over the ChatterMate API. It ships in the same chattermate-cli package as the CLI and is authenticated with a Personal Access Token.

stdio transport

Launched by your MCP client as a subprocess — the standard way agents run local MCP servers.

Token auth

Uses a cmat_ Personal Access Token from the CHATTERMATE_TOKEN environment variable.

Scoped to your org

Every action runs as the token’s owner, limited to that user’s organization and permissions.

Prerequisites

Install the package

The server runs via uvx (no install) or after pipx install chattermate-cli. See the CLI installation guide.

Create a Personal Access Token

chattermate token create my-agent

Copy the cmat_... secret — it’s shown only once.

Configuration

Using Cursor? Install it in one click, then replace cmat_your_token_here with your token in Cursor’s MCP settings:

For any other client, add the server to its MCP configuration, supplying your personal access token via CHATTERMATE_TOKEN. The server targets the hosted API (https://api.chattermate.chat) by default, so no API URL is needed. Running chattermate token create prints this exact snippet for you.

{
  "mcpServers": {
    "chattermate": {
      "command": "uvx",
      "args": ["--from", "chattermate-cli", "chattermate-mcp"],
      "env": {
        "CHATTERMATE_TOKEN": "cmat_xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

claude mcp add chattermate \
  --env CHATTERMATE_TOKEN=cmat_xxxxxxxxxxxxxxxxxxxx \
  -- uvx --from chattermate-cli chattermate-mcp

If you installed with pipx, you can use the chattermate-mcp command directly instead of uvx:

{
  "mcpServers": {
    "chattermate": {
      "command": "chattermate-mcp",
      "env": {
        "CHATTERMATE_TOKEN": "cmat_xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Targeting a local or self-hosted backend? Add "CHATTERMATE_API_URL": "http://localhost:8000" to the env block.

Available tools

The server exposes the tools below. Read-only tools are safe to run freely; the others create or change configuration. Deleting tools, and replacing a widget’s allowed sites, are marked destructive, so MCP clients that support it ask you before running them.

Agents & knowledge
Widgets & in-app actions
Journeys
Help center

Tool	Description
`whoami`	The authenticated user (id, email, organization, role)
`list_agents` / `get_agent`	List agents, or get one by id
`create_agent` / `update_agent`	Create an agent, or change its instructions, name or active state
`get_workflow` / `get_workflow_nodes`	The workflow on an agent, and its nodes and connections
`create_workflow` / `update_workflow` / `update_workflow_nodes`	Create a workflow, change its details, or replace its nodes
`list_knowledge`	Knowledge sources linked to an agent
`add_knowledge_url`	Add website or PDF URLs, optionally linked to an agent
`get_ingestion_status`	Progress of a knowledge import
`link_knowledge` / `unlink_knowledge`	Link or unlink a source and an agent

Tool	Description
`list_widgets` / `create_widget`	An agent’s widgets, or a new one (its id goes in the embed code)
`get_widget_embed_settings`	The sites a widget may run on
`set_widget_allowed_domains`	Replace that list. In-app actions only run on a widget limited to its sites
`list_actions`	An agent’s in-app actions, and when a page last registered each
`create_action`	Declare an action: name, label, description, argument schema, confirm policy
`update_action`	Change only the fields given; the action is named by its id or name
`set_action_enabled`	Turn an action on or off
`preview_action_for_model`	Exactly what the model is told about an action
`delete_action`	Delete an action

Every journey tool takes the journey’s id or its key. See Journeys.

Tool	Description
`list_journeys` / `get_journey`	An agent’s journeys in priority order, or one with its full definition
`journey_templates`	Templates to start from, with their steps and the actions they expect
`journey_context_keys`	Page fields sent with `setContext` that steps can use
`create_journey_from_template`	A draft journey from a template
`create_journey`	A journey from a full definition (the tool describes the format and its rules)
`update_journey`	Change only the fields given; a fetched journey can be sent back whole
`set_journey_status`	Make a journey live, pause it, or put it back to draft
`reorder_journeys`	Set which journey wins when several could start (first runs first)
`journey_funnel` / `journey_stuck_users`	How far users got per step, and who is waiting on one
`delete_journey`	Delete a journey and everyone’s progress through it

Tool	Description
`help_center_settings` / `configure_help_center`	Read or change the help center’s settings
`list_faqs` / `faq_categories`	FAQs (filter by status, category or text) and their categories
`create_faq` / `update_faq` / `delete_faq`	Manage one FAQ
`set_faq_status` / `delete_faqs`	Publish, unpublish or delete many at once
`import_faqs_from_url` / `import_faqs_from_pdf`	Import FAQs; poll the job with `help_center_job`
`upload_faq_image` / `set_help_center_logo`	Upload an image for an article, or the logo
`help_center_domain_status` / `set_help_center_domain` / `verify_help_center_domain`	Connect and verify a custom domain

Example prompts

Once connected, you can ask your AI agent things like:

“List my ChatterMate agents and tell me which ones have no workflow.”
“Create a customer_support agent named ‘Billing Bot’ with instructions to handle refunds and escalate disputes to a human.”
“Add https://docs.acme.com to the Billing Bot’s knowledge base and tell me when ingestion finishes.”
“Which of my agent’s actions has no page registered code for it yet?”
“Show me the funnel for the setup journey over the last week, and who is stuck on the invite step.”

The agent translates these into the appropriate tool calls.

Set up an in-app agent with an AI assistant

A coding assistant connected to both your codebase and this server can do the whole setup: declare the actions, write the handlers in your app, and build the journey.

Ask it to declare the actions

“Look at our settings and invoices code. Declare in-app actions on agent <id> for changing the currency (ask before overwriting), adding a client, and sending the latest draft invoice (always ask).” The assistant calls create_action for each one.

Ask it to write the handlers

“Register those actions on our app pages with ChatterMate.registerActions, calling our existing API client.” Then open your app, and list_actions shows when each action was first registered by a page.

Limit the widget to your app

“Limit the widget to app.acme.com.” This uses set_widget_allowed_domains.

Build the journey

“Create a draft three-step ‘First invoice’ journey that ends when the app sends invoice_sent, using those actions.” The assistant can start from journey_templates or write the definition itself, since the tool explains the format. Review it in the dashboard’s Journeys tab before you make it live.

Security

A Personal Access Token grants the agent the same permissions as its owner. Treat it like a password.

Scope risk by creating a dedicated token per agent/integration and setting an expiry with --expires-in-days.
Revoke a token at any time with chattermate token revoke <id> (or from the API); the server stops working immediately.
The server never stores your token — it reads it from the environment on each run.

Getting Started

Features

Channels

Developer Tools

Deployment

MCP Server

ChatterMate MCP Server

How it works

stdio transport

Token auth

Scoped to your org

Prerequisites

Configuration

Available tools

Example prompts

Set up an in-app agent with an AI assistant

Security

Next steps

CLI

MCP Tools

​ChatterMate MCP Server

​How it works

stdio transport

Token auth

Scoped to your org

​Prerequisites

​Configuration

​Available tools

​Example prompts

​Set up an in-app agent with an AI assistant

​Security

​Next steps

CLI

MCP Tools

ChatterMate MCP Server

How it works

Prerequisites

Configuration

Available tools

Example prompts

Set up an in-app agent with an AI assistant

Security

Next steps