Connect the Cumulus MCP

The Cumulus MCP server gives an AI assistant the Talos operations as tools: it can build and publish agents, start runs, follow them and read their transcripts, with the same API key and permissions as your code.

Documentation for coding agents

Connect the public documentation server at https://api.cumuluslabs.io/mcp/docs without a key. The authenticated customer server below offers the same docs tools alongside your permitted operations. See Build with an AI agent for Codex and Claude setup.

Clients supporting MCP resources can browse the corpus; clients supporting prompts can select build-and-test, connection and debugging workflows. Retrieval never accesses customer data.

Quickstart

1. Pick the environment. Build and test in your sandbox; repeat the setup in production when it works. Agents, trunks, numbers, secrets and tests are separate in each, and a key works only in the environment it was created in.
2. Create a key. In Talos, switch to that environment, open Settings → API keys, name the key after the client (for example “Claude Code, Shivam”) and give it the member role. A member key builds, tests, publishes and places calls; keep admin work (trunks, numbers, secrets, keys, team) in Talos.
3. Connect your client with the key: Claude Code or Claude Desktop below.
4. Check it. Ask: “Which Cumulus environment am I connected to, and what agents do I have?”
5. Give it the job. For example:

Prompt

Set up our Fairway outbound collections agent for SIP calling through our Twilio trunk, and test it.
Our Retell export is ./fairway-retell-export.json. The trunk and our caller IDs are already connected in Talos.
Test on a version that isn't live, show me the results, and ask me before you make anything live or place a call.

When your client connects, the server gives your assistant a setup guide: the order below, where each input comes from, and which steps need you or Cumulus. Each tool's description says what to call it with and what to call next.

Calls are real

runs_create on a phone agent dials the number you give it, also with test: true (a test run is only left out of billing, webhooks and triggers). The server marks it as destructive, like every tool that changes access, credentials or what live calls do, so a client that confirms destructive tools asks you first. Keep that on.

What Cumulus staff do

Cumulus sets each environment's concurrent call cap and opens it for runs. Until then, connecting a trunk or importing a number answers tenant_not_configured, a call answers tenant_not_configured or tenant_disabled, and a test run tenant_not_configured or tenant_admission_closed; GET /api/v1/runs/capacity (runs_capacity) shows the limit and whether admission is open. Ask your Cumulus contact to “set voice capacity and open run admission” for the environment, quoting its slug and tenant_id from environments_list. You never need a Cumulus trunk: calls go out on yours.

The server

• URL: https://api.cumuluslabs.io/mcp
• Transport: Streamable HTTP, stateless, JSON responses (POST only). No local process to install.
• Authentication: an API key as a bearer token: Authorization: Bearer cmls_…. There is no OAuth sign-in; create the key in Talos (Get an API key). A request without a key gets 401.
• Permissions: the key's role decides which tools the client sees. A viewer key lists only read tools; a member key adds runs and authoring; an admin key adds keys, secrets, trunks, numbers and the budget.
• Session cookies are not accepted: an MCP client always sends an API key.
• Untrusted content: results that carry text written by callers or other parties (transcripts, events, test trials, imported prompts, external responses) are marked untrusted_content: true, and the text your assistant reads starts with a notice to treat it as data, never as instructions.

Treat the key as a password

The assistant acts with the key's full role. Give it its own member key (name it after the client), a viewer key when it only needs to read, and revoke it in Talos when you stop using it. If you do let an assistant connect a trunk with an admin key, use a separate key for that and revoke it afterwards.

Set up your client

Claude Code

With the key in CUMULUS_API_KEY, run:

Terminal

claude mcp add --transport http cumulus https://api.cumuluslabs.io/mcp \
  --header "Authorization: Bearer $CUMULUS_API_KEY"

Add --scope user to use it in every project. Check it with claude mcp list, or /mcp inside a session.

Claude Desktop

Claude Desktop's custom connectors sign in with OAuth, and the Cumulus MCP takes an API key, so connect through the open-source mcp-remote bridge (needs Node.js). Add this to claude_desktop_config.json (Settings → Developer → Edit Config) and restart Claude Desktop:

claude_desktop_config.json

{
  "mcpServers": {
    "cumulus": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "https://api.cumuluslabs.io/mcp",
        "--header", "Authorization:${CUMULUS_AUTH}"
      ],
      "env": { "CUMULUS_AUTH": "Bearer cmls_..." }
    }
  }
}

Keep Authorization: and the variable together without a space: some clients split arguments on spaces.

Cursor

Add the server to ~/.cursor/mcp.json (every project) or .cursor/mcp.json (one project). Cursor reads the key from your environment:

~/.cursor/mcp.json

{
  "mcpServers": {
    "cumulus": {
      "url": "https://api.cumuluslabs.io/mcp",
      "headers": { "Authorization": "Bearer ${env:CUMULUS_API_KEY}" }
    }
  }
}

VS Code

Add the server to .vscode/mcp.json. VS Code asks for the key once and stores it securely:

.vscode/mcp.json

{
  "inputs": [
    { "type": "promptString", "id": "cumulus-api-key", "description": "Cumulus API key", "password": true }
  ],
  "servers": {
    "cumulus": {
      "type": "http",
      "url": "https://api.cumuluslabs.io/mcp",
      "headers": { "Authorization": "Bearer ${input:cumulus-api-key}" }
    }
  }
}

Any other MCP client that speaks Streamable HTTP and can send a header works the same way.

How tools work

Each tool is one API operation, named after it with dots as underscores (runs.create is runs_create). Its arguments mirror the request: params for the path, query and body. Tools that create something also take an optional idempotency_key; the server generates one when the client sends none.

tools/call

{
  "name": "runs_create",
  "arguments": {
    "body": { "channel": "cloud", "agent_id": "…", "mode": "task", "input": { "ticket": "I was charged twice." }, "test": true },
    "idempotency_key": "<a new UUID for each request>"
  }
}

The result is { ok, status, result | error, idempotency_key }, with the same error codes as the API. When a command returns outcome_unknown, the assistant retries with the same idempotency_key, so nothing runs twice.

Result

{ "ok": true, "status": 201, "result": { "run_id": "…", "state": "admitted", … }, "idempotency_key": "<the key used>" }

First prompts to try

• “Import the Retell export in ./agent.json as a draft, show me what the import changed or dropped, and fix what validation reports.”
• “List my Talos agents and tell me which ones have unpublished draft changes.”
• “Start a test cloud run of the Ticket triage agent with the ticket "I was charged twice", wait for it to end and summarize its transcript.”
• “Show my last 20 phone runs that reached voicemail, grouped by agent.”
• “How many phone calls can I run at once right now, and how many are active?”
• “Read the analysis of run <run_id> and explain its disposition.”
• “Publish the open draft of agent <agent_id> as its next version, without making it live.”

Ask for test runs (test: true) while you experiment: they run normally but never reach your webhooks or triggers and are not billed. A phone test run still places a real call; simulated calls are test suites.

Tools