> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chatblocks.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP setup

> Connect your agent to the hosted Chatblocks MCP server at /api/mcp/v1.

Chatblocks hosts a single MCP endpoint:

```
https://chatblocks.ai/api/mcp/v1
```

Every MCP-capable agent connects to it the same way: an `Authorization: Bearer cb_live_*` header on the HTTPS request. The key is **workspace-scoped** — one key carries one workspace's context, and you generate a key per agent (or per machine) so revocation is per-place.

If the agent needs to create the workspace before a human has signed up, use [agent-created canvases](/mcp/agent-created-canvases). That flow returns a temporary MCP key immediately and emails the human a claim link.

## Mint a key

<Steps>
  <Step title="Open /settings/api-keys">
    Settings → **API keys** tab. Workspace admin only. API keys are **free on every plan** — connect your agent and author blocks within your plan's caps.
  </Step>

  <Step title="cb_live keys → New key">
    Pick a label (e.g. "Claude Desktop — my laptop"). The platform shows the plaintext **once** and stores only a hash. Copy it now — there's no "show again."
  </Step>

  <Step title="Paste into your agent's config">
    Snippets below.
  </Step>
</Steps>

<Warning>
  Keys are workspace-admin-equivalent for the MCP write surface. Treat them like passwords: one per device, rotate on leave, no committing to git.
</Warning>

## Connect from clients

<Tip>
  The fastest way to get the right snippet for your client is the **agent connect overlay** on your canvas (toolbar chip → empty state, or `?connectAgent=1`). It renders the snippet below with your actual `cb_live_*` key already pasted in. The forms below are the canonical shapes if you'd rather copy by hand.
</Tip>

<Tabs>
  <Tab title="Claude">
    Run in your terminal:

    ```bash theme={null}
    claude mcp add chatblocks \
      --transport http \
      https://chatblocks.ai/api/mcp/v1 \
      --header "Authorization: Bearer cb_live_..."
    ```

    Works for both Claude Code and Claude Desktop on current Claude releases. To paste manually instead, write the standard `mcpServers` JSON (see the Codex tab) into `~/.claude/mcp.json`.
  </Tab>

  <Tab title="Codex">
    Add to `~/.codex/config.toml`:

    ```toml theme={null}
    [mcp_servers.chatblocks]
    url = "https://chatblocks.ai/api/mcp/v1"
    bearer_token_env_var = "CHATBLOCKS_API_KEY"
    ```

    Then launch Codex from a shell with the key set:

    ```bash theme={null}
    export CHATBLOCKS_API_KEY="cb_live_..."
    ```
  </Tab>

  <Tab title="Cursor">
    Add to `~/.cursor/mcp.json` (or paste into the Cursor settings UI):

    ```json theme={null}
    {
      "mcpServers": {
        "chatblocks": {
          "url": "https://chatblocks.ai/api/mcp/v1",
          "headers": {
            "Authorization": "Bearer cb_live_..."
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Windsurf">
    Add to `~/.codeium/windsurf/mcp_config.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "chatblocks": {
          "url": "https://chatblocks.ai/api/mcp/v1",
          "headers": {
            "Authorization": "Bearer cb_live_..."
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="OpenClaw">
    Run in your terminal:

    ```bash theme={null}
    openclaw mcp set chatblocks '{"url":"https://chatblocks.ai/api/mcp/v1","transport":"streamable-http","headers":{"Authorization":"Bearer cb_live_..."}}'
    openclaw mcp doctor chatblocks --probe
    ```

    Chatblocks uses hosted Streamable HTTP MCP with a static Bearer token. The `doctor --probe` command verifies that OpenClaw can see the Chatblocks tools.
  </Tab>

  <Tab title="Poke">
    Run in your terminal:

    ```bash theme={null}
    npx poke@latest mcp add https://chatblocks.ai/api/mcp/v1 \
      -n "Chatblocks" \
      -k "cb_live_..."
    ```

    Poke uses Chatblocks' canonical hosted MCP endpoint. A Poke Kitchen recipe is the distribution path after direct setup is verified.
  </Tab>

  <Tab title="Other">
    Any MCP-compatible client (OpenCode, Cline, Gemini CLI, Goose, Kilo Code, Amazon Q Developer, Continue.dev, Zed, VS Code/GitHub Copilot, etc.) accepts the same generic JSON shape:

    ```json theme={null}
    {
      "mcpServers": {
        "chatblocks": {
          "url": "https://chatblocks.ai/api/mcp/v1",
          "headers": {
            "Authorization": "Bearer cb_live_..."
          }
        }
      }
    }
    ```

    If your client only speaks stdio, you can pipe through the `chatblocks-mcp` CLI — see [CLI → Install](/cli/install) — but the HTTP transport is preferred where supported.
  </Tab>
</Tabs>

## Discovery for agents

If you are giving an agent current Chatblocks context, use these app-domain files:

```text theme={null}
https://chatblocks.ai/agent.md
https://chatblocks.ai/llms.txt
https://chatblocks.ai/llms-full.txt
```

For marketplace and platform-specific setup paths, see [platform integrations](/mcp/platform-integrations).

## Direct HTTP usage

Anything that speaks JSON-RPC over HTTP can talk to the server directly. Example with curl:

```bash theme={null}
curl -s https://chatblocks.ai/api/mcp/v1 \
  -H "Authorization: Bearer cb_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'
```

A `tools/call` is the same envelope:

```bash theme={null}
curl -s https://chatblocks.ai/api/mcp/v1 \
  -H "Authorization: Bearer cb_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "blocks.list",
      "arguments": { "published": true }
    }
  }'
```

The server is fresh-per-request — an `McpServer` instance is built on every POST. There's no session state to maintain client-side.

## Streaming tools

A handful of tools return Server-Sent Events instead of a single JSON-RPC reply (`blocks.create`, `blocks.build`, `dataSources.testConnection`, `dataSources.triggerRefresh`, `schedule.preview`). When you call one of these, the response `Content-Type` switches to `text/event-stream` and the body streams progress notifications until the final `result` event.

Most MCP clients (Claude Code / Codex / Cursor / Windsurf / OpenClaw / Poke) handle this transparently. The stdio proxy bridges streaming responses but only forwards the final result to the stdio client today; intermediate progress isn't bridged. From curl, append `--no-buffer` to see deltas as they arrive.

## What's next

<CardGroup cols={2}>
  <Card title="Tool reference" icon="list" href="/mcp/tool-reference">
    The full list of tools, auto-generated from the server source.
  </Card>

  <Card title="Agent-created canvases" icon="bot" href="/mcp/agent-created-canvases">
    Let an agent create a temporary canvas first, then hand it to a human.
  </Card>

  <Card title="Platform integrations" icon="network" href="/mcp/platform-integrations">
    OpenClaw, Poke, Context7, and other agent-discovery surfaces.
  </Card>

  <Card title="Errors and limits" icon="triangle-exclamation" href="/mcp/errors-and-limits">
    JSON-RPC error codes, HTTP statuses, and per-plan rate limits.
  </Card>
</CardGroup>