Source: https://docs.cumuluslabs.io/ai-agents
Content version: 010b8d9a

# Build with an AI agent

Give your coding agent the same Cumulus documentation you read here. Connect public documentation first, then add authenticated tools when you are ready to work in an environment.

## Prerequisites {#prerequisites}

- Codex, Claude Code, Cursor, VS Code, or another Streamable HTTP MCP client.
- Public documentation needs no account or key.
- Customer operations need a Cumulus API key. Create a dedicated member key in [Talos settings](https://app.cumuluslabs.io/settings/api-keys). Use a viewer key for diagnosis.
- SDK packages are currently supplied by your Cumulus contact; use HTTPS until you have them. See [SDKs](/docs/sdks).

## Connect public documentation {#public-docs}

The public documentation server is `https://api.cumuluslabs.io/mcp/docs`. It exposes documentation search, reads, resources and workflow prompts. It cannot access your organization or run agents.

### Codex {#codex}

Register the public server from your terminal:

```bash
codex mcp add cumulus-docs --url https://api.cumuluslabs.io/mcp/docs
```

For customer tools, put this in your Codex MCP configuration. Set `CUMULUS_API_KEY` in the environment available to your client, then restart it. Desktop launch environments can differ from your terminal.

```toml
[mcp_servers.cumulus]
url = "https://api.cumuluslabs.io/mcp"
bearer_token_env_var = "CUMULUS_API_KEY"
```

### Claude Code {#claude-code}

```bash
claude mcp add --transport http cumulus-docs https://api.cumuluslabs.io/mcp/docs
claude mcp list
```

For customer tools, use environment expansion in project `.mcp.json` rather than committing a key:

```json
{
  "mcpServers": {
    "cumulus-docs": {
      "type": "http",
      "url": "https://api.cumuluslabs.io/mcp/docs"
    },
    "cumulus": {
      "type": "http",
      "url": "https://api.cumuluslabs.io/mcp",
      "headers": { "Authorization": "Bearer ${CUMULUS_API_KEY}" }
    }
  }
}
```

Approve the project connection in your client, then use `/mcp` to check it. [Other clients](/docs/mcp#setup) have their own configuration format.

## Verify the connection {#verify}

Ask your assistant:

```text
Search the Cumulus documentation for publishing a test version without going live.
Read the relevant section and cite its source URL.
If customer tools are connected, identify the current environment and list my agents.
Do not change anything yet.
```

Expected result: the assistant cites the publish guide, explains `live: false`, and reads the environment from `environments_list` rather than guessing it. A missing customer key does not prevent documentation retrieval.

## Add project instructions {#project-instructions}

Copy this into your project's `AGENTS.md` or `CLAUDE.md` and adapt the task-specific sentence:

```markdown
For Cumulus integrations, consult https://docs.cumuluslabs.io/llms.txt.
Use the Cumulus docs MCP tools to search and read the relevant sections before coding.
Read operation schemas with docs_get_operation; do not invent fields, IDs or endpoints.
Use the current environment and IDs returned by Cumulus tools.
Validate drafts and publish a test version before promoting it.
Reuse the same idempotency key after an unknown outcome.
A phone run places a real call even with test: true; obtain authorization for its destination.
Keep API keys in environment variables, never in code, documentation links or prompts.
```

## Send a page to your assistant {#handoff}

Each page offers Open in Codex, Open in Claude, Copy agent prompt and View Markdown. Heading links select a section for the handoff. The prompt includes the canonical URL and tells the assistant to retrieve context first. Codex opens a new chat composer; Claude opens a new Claude Code composer in Claude Desktop. Neither link sends the prompt automatically. Copy agent prompt works when an application or browser cannot open the link. See the [Codex deep-link reference](https://learn.chatgpt.com/docs/reference/commands) and [Claude deep-link reference](https://support.claude.com/en/articles/14729294-open-claude-desktop-with-a-link).

## Troubleshooting {#troubleshooting}

- No tools: check the HTTP transport and endpoint path. `/mcp/docs` is public; `/mcp` requires a bearer key.
- A 401 on customer operations: check that the client actually receives `CUMULUS_API_KEY`, then verify the key has not been revoked.
- Missing admin tools: member keys cannot manage trunks, numbers, secrets or team access. Ask an admin to do those steps in Talos.
- Wrong environment: use the key for the intended environment. Agents and secrets are not shared across environments.

Next: [Build and test recipes](/docs/recipes), [MCP protocol details](/docs/mcp), or [Using the API](/docs/api).