> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chattermate.chat/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Let AI agents manage ChatterMate through the Model Context Protocol by connecting the MCP server to Claude, IDE assistants, or any MCP-compatible client.

# ChatterMate MCP Server

The ChatterMate MCP server (`chattermate-mcp`) exposes your ChatterMate instance to AI agents
through the [Model Context Protocol](https://modelcontextprotocol.io). 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](https://docs.chattermate.chat/features/in-app-actions.md),
[journeys](https://docs.chattermate.chat/features/journeys.md) and help center on your behalf.

> [!NOTE]
>
> **This is the inverse of [MCP Tools](https://docs.chattermate.chat/features/mcp-tools.md).** *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](https://docs.chattermate.chat/features/cli.md) and is authenticated with a
[Personal Access Token](https://docs.chattermate.chat/features/cli.md#personal-access-tokens).

> [card] stdio transport
>
> Launched by your MCP client as a subprocess — the standard way agents run local MCP servers.

> [card] Token auth
>
> Uses a `cmat_` Personal Access Token from the `CHATTERMATE_TOKEN` environment variable.

> [card] Scoped to your org
>
> Every action runs as the token's owner, limited to that user's organization and permissions.

## Prerequisites

**1. Install the package**

The server runs via `uvx` (no install) or after `pipx install chattermate-cli`. See the
[CLI installation guide](https://docs.chattermate.chat/features/cli.md#installation).

**2. Create a Personal Access Token**

```bash theme={null}
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:

[![Add ChatterMate MCP server to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=chattermate\&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyItLWZyb20iLCJjaGF0dGVybWF0ZS1jbGkiLCJjaGF0dGVybWF0ZS1tY3AiXSwiZW52Ijp7IkNIQVRURVJNQVRFX1RPS0VOIjoiY21hdF95b3VyX3Rva2VuX2hlcmUifX0%3D)

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.

```json Claude Desktop / generic theme={null}
{
  "mcpServers": {
    "chattermate": {
      "command": "uvx",
      "args": ["--from", "chattermate-cli", "chattermate-mcp"],
      "env": {
        "CHATTERMATE_TOKEN": "cmat_xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}
```

```bash Claude Code (CLI) theme={null}
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`:

```json theme={null}
{
  "mcpServers": {
    "chattermate": {
      "command": "chattermate-mcp",
      "env": {
        "CHATTERMATE_TOKEN": "cmat_xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}
```

> [!NOTE]
>
> 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.

> [tab] Agents & knowledge
>
> | 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 |

> [tab] Widgets & in-app actions
>
> | 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](https://docs.chattermate.chat/features/in-app-actions.md), 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 |

> [tab] Journeys
>
> Every journey tool takes the journey's id or its key. See [Journeys](https://docs.chattermate.chat/features/journeys.md).
>
> | 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 |

> [tab] Help center
>
> | Tool | Description |
> | - | - |
> | `help_center_settings` / `configure_help_center` | Read or change the [help center](https://docs.chattermate.chat/features/help-center.md)'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](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.

**1. 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.

**2. 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.

**3. Limit the widget to your app**

*"Limit the widget to app.acme.com."* This uses `set_widget_allowed_domains`.

**4. 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

> [!WARNING]
>
> 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.

## Next steps

> [card] [CLI](https://docs.chattermate.chat/features/cli.md)
>
> Manage tokens and resources from your terminal.

> [card] [MCP Tools](https://docs.chattermate.chat/features/mcp-tools.md)
>
> The reverse direction — give your ChatterMate agents external tools.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.