@cig-chat/mcp

MCP server for the cig.chat API. Connect Claude, Cursor, or any MCP client to your cig.chat bot and drive subscribers, tags, flows, WhatsApp templates, broadcasts and the shop in plain language.

243 API operations · 250 tools · 13 toolsets.

This package is a client for your own cig.chat account. It ships with no credentials and no default account. You supply your own bot token at setup, it stays on your machine, and it is never logged, echoed or transmitted anywhere except to app.cig.chat.

---

1. Get your API token

1. Sign in to cig.chat.
2. Open the bot you want to control.
3. Go to Settings → API and copy the token.

One token controls exactly one bot. There is no workspace-wide token and no bot selector — to work with a second bot, add a second server entry with that bot's token.

Treat the token like a password: it can read your subscriber list and send messages on your behalf. Never commit it, never paste it into a chat, and rotate it in cig.chat if it leaks.

2. Add the server

Claude Code

claude mcp add cigchat --env CIGCHAT_API_TOKEN=your-token-here -- npx -y @cig-chat/mcp

Claude Desktop

Edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "cigchat": {
      "command": "npx",
      "args": ["-y", "@cig-chat/mcp"],
      "env": { "CIGCHAT_API_TOKEN": "your-token-here" }
    }
  }
}

Cursor

Same shape, in ~/.cursor/mcp.json.

3. Check it works

CIGCHAT_API_TOKEN=your-token-here npx -y @cig-chat/mcp --check

Then ask your assistant: "Which cig.chat bot am I connected to?" — it will call cigchat_whoami.

---

Safety

This server can spend money and cannot undo what it does. Read this section before you enable it for a production bot.

Every tool is available by default. That includes broadcasting to your entire subscriber list. The protections are:

Protection	What it does
Named by risk	Every fan-out tool is cigchat_broadcast_*, every 1:1 send cigchat_send_*. One deny rule covers the class.
Confirmation step	broadcast and destructive tools refuse the first call and return an impact statement, an audience count, and a one-time token.
Argument binding	The token is bound to a hash of the exact arguments — approval for a 12-person test cannot be replayed on a 50,000-person blast.
No blind retry	A rate-limited send or broadcast is never retried automatically, because the messages may already have gone out.
Credential masking	API keys in responses are truncated to ***last4; your token never appears in output.

Your MCP client's approval prompt is the real gate. This server can present the facts; only you can approve. Do not enable auto-approval for cigchat_broadcast_*.

Recommended settings for a production bot

"env": {
  "CIGCHAT_API_TOKEN": "your-token-here",
  "CIGCHAT_MAX_BROADCAST_RECIPIENTS": "500",
  "CIGCHAT_ALLOW": "read,write,send"
}

That keeps everyday work available, caps any broadcast, and leaves fan-out off entirely.

Trying it safely

"env": { "CIGCHAT_API_TOKEN": "your-token-here", "CIGCHAT_DRY_RUN": "true" }

Every write becomes a no-op that reports exactly what it would have sent. Reads still work.

---

Configuration

Variable	Default	Purpose
CIGCHAT_API_TOKEN	—	Required. Your bot-scoped token.
CIGCHAT_TOOLSETS	all	all, dynamic, or a comma-separated list of toolset ids.
CIGCHAT_ALLOW	all tiers	Which risk tiers to expose: read,write,send,broadcast,destructive.
CIGCHAT_CONFIRM_TIERS	broadcast,destructive	Which tiers require a confirmation token.
CIGCHAT_DRY_RUN	false	true makes every write a no-op that echoes the request.
CIGCHAT_MAX_BROADCAST_RECIPIENTS	0 (no cap)	Refuse broadcasts above this audience size.
CIGCHAT_RPS	5	Client-side request rate limit.
CIGCHAT_MAX_RETRIES	3	Retry attempts for rate limits and server errors.
CIGCHAT_MAX_RESPONSE_CHARS	20000	Truncate long responses instead of flooding context.
CIGCHAT_BASE_URL	https://app.cig.chat/api	Override the API base URL.

Toolsets

250 tools is a lot of context on clients that send every schema up front. Narrow with CIGCHAT_TOOLSETS, or set it to dynamic to start with just the core tools and let the assistant switch on what it needs.

Id	Tools	Covers
core	4	Identity, lookup, toolset discovery. Always on.
subscribers	40	Find, create, update subscribers; tags, labels, fields, opt-in.
flow	43	Sub-flows, tags, user/bot fields, shortcuts, closing notes, segments.
conversations	2	Conversation history and agent activity.
whatsapp	8	WhatsApp and Facebook utility templates.
messaging	21	Sends and broadcasts.
shop	49	Products, variants, orders, discounts, locations, carts.
team	17	Ticket lists, labels, agent groups.
ai	13	AI agents and tasks, OpenAI embeddings.
integrations	30	Third-party integration credentials, mini-apps.
workspace	17	Workspace settings, members, analytics.
templates	3	Flow templates and install links.
escape	1	cigchat_api_call for anything not wrapped.

Full list: docs/TOOLS.md.

---

Names instead of ids

cig.chat identifies most things by opaque ids like f123t456. You do not have to know them — every tool accepts the entity's name and resolves it:

"Tag Dana as VIP customers" → resolves VIP customers → f123t456 → tags her.

If a name is ambiguous the server refuses and lists the candidates rather than guessing. Use cigchat_resolve to browse what exists.

WhatsApp templates

Template variables are defined when the template is approved, so ask first:

cigchat_describe_whatsapp_template({ name: "order_ready" })
→ expected_variables: ["HEADER_IMAGE", "BODY_1", "BODY_2"]

Then send with those exact keys. Getting this wrong on a broadcast is an expensive way to discover a typo.

---

Troubleshooting

Symptom	Cause
401 / credentials failed	Token is wrong, revoked, or from a different bot. Regenerate in Settings → API.
A tool is missing	Its toolset or tier is disabled. Run cigchat_list_toolsets.
429 rate limited	Lower CIGCHAT_RPS. Sends are never auto-retried — check whether the message went out before re-running.
422 field is required	An array parameter needs objects, not strings: [{"tag_ns":"f1t1"}].
Broadcast returns requires_confirmation	Working as designed. Show the impact statement to a human, then re-call with the token.

Development

npm install
npm run spec:pull   # refresh spec/openapi.json from the live API
npm run gen         # regenerate tools from the spec + spec/overrides.ts
npm test
npm run build

Tools are generated from the vendored OpenAPI document; spec/overrides.ts is the only hand-maintained mapping. Generated output is committed, so an upstream API change shows up as a reviewable diff.

Links

• cig.chat developer tools
• REST API reference
• Report an issue

License

MIT © Dialogue Online Services LTD