On this page
Connect the Cumulus MCP
MCP connects a coding assistant to Cumulus. Your assistant can look up the platform's current documentation, inspect your agents and help you make changes using the customer SDK and API.
Start with the public documentation connection. Add workspace access when you want the assistant to work with your agents.
| Connection | URL | Access |
|---|---|---|
| Documentation | https://mcp.cumuluslabs.io/mcp/docs | Public guides, API schemas and workflow prompts. No key needed. |
| Your workspace | https://mcp.cumuluslabs.io/mcp | Your agents and runs, using a Cumulus API key. |
If your organization supplies a separate deployment, use its MCP URLs instead. An API URL is different from an MCP URL: use CUMULUS_API_URL for SDK/REST requests and the URLs above for MCP connections.
Connect documentation
Choose your client below. After connecting, ask:
Read the Cumulus overview and TypeScript tutorial.
Explain how I would build a service agent that looks up delivery information
in my backend. Which parts run in Cumulus, and which parts do I implement?
The assistant can search, read complete pages and inspect exact API fields:
| Tool | Use it to |
|---|---|
docs_search | Find a guide, SDK method, operation or error. |
docs_get | Read a guide or a specific section. |
docs_get_operation | Read an operation's request, response and workflow guidance. |
These tools cannot read your workspace. Markdown pages and the documentation index are also available for assistants without MCP support.
Set up your client
Codex
Add the public server and check the connection:
codex mcp add cumulus-docs \
--url https://mcp.cumuluslabs.io/mcp/docs
codex mcp list
For workspace access, make your Cumulus key available as CUMULUS_API_KEY in the environment that launches Codex, then add:
codex mcp add cumulus \
--url https://mcp.cumuluslabs.io/mcp \
--bearer-token-env-var CUMULUS_API_KEY
The configuration stores the variable's name; keep the key itself in your local secret manager. See the Codex MCP documentation for other configuration options.
Claude Code
Add the public server:
claude mcp add --transport http cumulus-docs \
https://mcp.cumuluslabs.io/mcp/docs
claude mcp list
For workspace access, merge this entry into your project's .mcp.json. It reads the key from the environment rather than storing the key in the file:
{
"mcpServers": {
"cumulus": {
"type": "http",
"url": "https://mcp.cumuluslabs.io/mcp",
"headers": { "Authorization": "Bearer ${CUMULUS_API_KEY}" }
}
}
}
Set the variable before launching Claude Code and use /mcp to check the connection. Claude Code's MCP documentation explains configuration scopes and environment variables.
Cursor, VS Code and Claude Desktop
Add the documentation URL as a remote Streamable HTTP server. To access your workspace, add a second connection to /mcp that sends Authorization: Bearer <your key> using the client's secret input or environment settings. The workspace connection uses API-key authentication. A client that only supports OAuth sign-in cannot use that connection directly.
Work with your agents
Create a dedicated key in Studio → Settings → API keys. A viewer key lets the assistant inspect agents and results. A member key also permits authoring and runs; phone calls require call permission. See API key roles.
Begin with a read:
Identify my current environment and list my agents. Do not change anything.
Confirm the returned workspace. Then give the assistant a specific task:
Help me build a service-desk voice agent with a delivery/repair lookup tool.
Use the TypeScript SDK tutorial and put the handler in my application.
Include a clear failure path. Validate the definition locally and show me the
remote preview before applying it. Do not assign a number or place a call.
The useful sequence is the same as when you work directly: define the agent, implement and test the tool, preview the changes, apply the draft, then publish. Build with an AI agent shows reusable project instructions.
Build with the customer SDK
The workspace connection uses @cumulus/sdk 0.3.4. Its workflow tools call the same SDK functions you use in your application:
| Task | MCP tools | SDK reference |
|---|---|---|
| Review a definition | sdk_agent_compile, sdk_agent_preview | Compile and preview |
| Save and publish a reviewed change | sdk_agent_apply, sdk_agent_validate, sdk_agent_publish | Authoring |
| Promote or export a version | sdk_agent_promote, sdk_agent_export | Authoring |
| Prepare and place a call | sdk_call_prepare, sdk_call_place | Calls |
| Wait for results | sdk_run_wait, sdk_recording_wait, sdk_analysis_wait | Results |
| Assign phone numbers | sdk_integration_assign | Number assignments |
Each tool's schema describes its arguments. Definitions, bindings, plans and receipts are JSON versions of the SDK values; the connection supplies the authenticated client. Your API key determines which tools are available. Customer-hosted handlers still run in your application: the MCP helps write and test them using the server SDK.
Keep the plan returned by preview and pass it unchanged to apply after reviewing the changes. Save every receipt and checkpoint returned by apply or publish, including those attached to an error. They identify the draft, revision and publication needed to recover an interrupted operation. Publishing and recovery explains the workflow.
Preparing a call does not dial. Persist the full command returned by sdk_call_prepare before passing it to sdk_call_place. Placing a phone call with test: true still dials. A new command can create another call, so reconcile an uncertain result using the saved command. Calls and results explains retries and outcome checks.
Call an individual API operation
Use sdk_client_call for customer HTTP operations such as reading an agent or a transcript. First ask the assistant to read docs_get_operation for the operation's exact fields. For example:
{
"name": "sdk_client_call",
"arguments": {
"operationId": "agents.list",
"input": {}
}
}
This calls Cumulus.call('agents.list', {}) with your key. Other operations accept path, query, body and idempotencyKey inside input, as documented in the customer HTTP API reference. Preserve the same request and key when reconciling a command whose outcome is unknown.
Wait tools return within 25 seconds. A wait_timeout includes the last observed state and does not cancel the run; call the wait again to keep watching.
Troubleshooting
| Symptom | Check |
|---|---|
401 on the workspace connection | The client sent the key, it has not expired, and it belongs to the selected deployment. |
| Documentation works, but workspace tools do not | The public connection needs no key; workspace access is a separate authenticated connection. |
| An expected tool is absent | Available tools follow the key's current permissions. |
404 or a sign-in page | Use the full MCP URL, including /mcp or /mcp/docs. |
| An operation is refused | Read its error and required configuration in the API reference. |
Protocol and permissions
The hosted server uses Streamable HTTP. It authenticates each workspace request with the caller's bearer key, and Cumulus checks the operation against that key's current permissions. Studio session cookies are not used for this connection.
The public /mcp/docs connection only serves documentation. The authenticated connection also includes those documentation tools. Use its tools/list inventory for the operations available to your key.
More tasks to try
- Explain an agent's flow and its tool bindings.
- Compare my local definition with the current draft.
- Help reconcile a draft conflict after a teammate's Studio edit.
- Read a run's transcript and tool results to explain why it failed.
- Propose tests for a change before I publish it.
For each task, give the assistant the intended workspace and goal. Keep credentials and personal phone numbers out of prompts and shared recordings.
Tool reference
Use the API reference for exact operation fields, results and errors, and customer SDK for application integration. Use the workflow tools for SDK tasks and sdk_client_call for individual HTTP operations.