Skip to main content

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.

ChatBlocks hosts a single MCP endpoint: 
https://chatblocks.ai/api/mcp/v1
Every coding agent that speaks MCP 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.

​
Mint a key

1

Open /settings

Workspace admin only. Free workspaces can mint keys (no plan gate on key creation); the gate is on what the tools do.
2

API Keys panel → 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.”
3

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 in-app wizard at /onboarding/agent. 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.

​
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) 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.

Errors and limits

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