MCP setup - Chatblocks

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. That flow returns a temporary MCP key immediately and emails the human a claim link.

Mint a key

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.

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.”

Paste into your agent's config

Snippets below.

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

Connect from clients

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.

Run in your terminal:

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.

Add to ~/.codex/config.toml:

[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:

export CHATBLOCKS_API_KEY="cb_live_..."

Add to ~/.cursor/mcp.json (or paste into the Cursor settings UI):

{
  "mcpServers": {
    "chatblocks": {
      "url": "https://chatblocks.ai/api/mcp/v1",
      "headers": {
        "Authorization": "Bearer cb_live_..."
      }
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "chatblocks": {
      "url": "https://chatblocks.ai/api/mcp/v1",
      "headers": {
        "Authorization": "Bearer cb_live_..."
      }
    }
  }
}

Run in your terminal:

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.

Run in your terminal:

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.

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:

{
  "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 — but the HTTP transport is preferred where supported.

Discovery for agents

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

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.

Direct HTTP usage

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

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:

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

Tool reference

The full list of tools, auto-generated from the server source.

Agent-created canvases

Let an agent create a temporary canvas first, then hand it to a human.

Platform integrations

OpenClaw, Poke, Context7, and other agent-discovery surfaces.

Errors and limits

JSON-RPC error codes, HTTP statuses, and per-plan rate limits.

​Mint a key

​Connect from clients

​Discovery for agents

​Direct HTTP usage

​Streaming tools

​What’s next

Tool reference

Agent-created canvases

Platform integrations

Errors and limits

Mint a key

Connect from clients

Discovery for agents

Direct HTTP usage

Streaming tools

What’s next