MCP setup

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 available to every signed-in workspace — connect your agent and author blocks within the workspace 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"
http_headers = { Authorization = "Bearer cb_live_..." }
startup_timeout_sec = 30
tool_timeout_sec = 180

Replace any existing Chatblocks section, save, and restart Codex or reload MCP. This works in Desktop and CLI without a shell export. Keep this file private: it contains your API key.

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_..."
      }
    }
  }
}

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

Most MCP clients (Claude Code / Codex / Cursor / Windsurf / OpenClaw / Poke) handle this transparently. 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 rate limits.

Get started

Concepts

Authoring blocks

MCP server

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