Skip to main content

​
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, and knowledge sources 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-sdk 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

1

Install the package

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

Create a Personal Access Token

chattermate token create my-agent
Copy the cmat_... secret — it’s shown only once.

​
Configuration

Add the server to your MCP client’s 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-sdk", "chattermate-mcp"],
      "env": {
        "CHATTERMATE_TOKEN": "cmat_xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}
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 following tools. Read-only tools are safe to run freely; mutating tools create or change configuration.
ToolDescription
whoamiReturn the authenticated user (id, email, organization, role)
list_agentsList all agents in the organization
get_agentGet a single agent by id
get_workflowGet the workflow attached to an agent
get_workflow_nodesGet all nodes and connections for a workflow
list_knowledgeList knowledge sources linked to an agent
get_ingestion_statusCheck the status of a knowledge ingestion job

​
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.”
  • “Create an ‘Onboarding’ workflow for agent <id> and publish it.”
The agent translates these into the appropriate tool calls.

​
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.

​
Next steps

CLI

Manage tokens and resources from your terminal.

MCP Tools

The reverse direction — give your ChatterMate agents external tools.