# Chatblocks Agent Context

Chatblocks is an agent-friendly canvas platform for small sandboxed web apps called blocks. Agents use the hosted MCP server to create, edit, build, publish, and place blocks on persistent canvases.

## Canonical URLs

- Product: https://chatblocks.ai
- Human agent page: https://chatblocks.ai/agents
- Agent guide: https://chatblocks.ai/agent.md
- Compact LLM index: https://chatblocks.ai/llms.txt
- Hosted MCP endpoint: https://chatblocks.ai/api/mcp/v1
- Agent bootstrap endpoint: https://chatblocks.ai/api/agent/bootstrap
- Human sign-in: https://chatblocks.ai/login

## Setup Paths

### Human-first setup

Use this when the human already has a Chatblocks account.

1. Ask the human to create a workspace API key from Chatblocks settings or from the canvas agent-connect overlay.
2. Configure the agent as a remote HTTP MCP client:

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

3. Verify with tools/list.
4. Use the MCP tools to create and publish blocks.

### Agent-first setup

Use this when the agent is the first actor and the human has not created a Chatblocks account yet.

1. Call:

   POST https://chatblocks.ai/api/agent/bootstrap

   Request JSON:

   {
     "humanEmail": "owner@example.com",
     "agentName": "OpenClaw",
     "workspaceName": "Launch dashboard",
     "canvasName": "Launch dashboard canvas"
   }

2. The response includes:

   {
     "apiKey": "cb_live_...",
     "mcpUrl": "https://chatblocks.ai/api/mcp/v1",
     "claimUrl": "https://chatblocks.ai/claim/cb_claim_...",
     "canvasUrl": "https://chatblocks.ai/canvas/<canvasId>",
     "limits": { "buildsPerDay": 10 }
   }

3. Connect to mcpUrl with Authorization: Bearer apiKey.
4. Build on the temporary canvas immediately.
5. Send the claimUrl to the human. The canvasUrl opens after claim. The workspace expires after 24 hours if unclaimed.

## Core MCP Workflow

The standard authoring loop is:

1. canvases.list - find available canvases.
2. blocks.init - create a new draft block.
3. blocks.setFiles - write the block source files.
4. blocks.build - build and validate the block bundle.
5. blocks.publish - publish the successful build.
6. placements.create - place the published block on a canvas if needed.

Use blocks.getFiles before editing an existing block. Only publish after a successful build. Return the canvas or block URL to the human.

## Block Model

- Blocks are small React or HTML apps.
- Blocks render in sandboxed iframes.
- Source files live in a virtual workspace and are written through MCP.
- A published version is immutable; future edits produce another draft/build/publish cycle.
- Public and unlisted URLs should be treated as public surfaces.

## Platform Integrations

OpenClaw:

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

Poke:

npx poke@latest mcp add https://chatblocks.ai/api/mcp/v1 -n "Chatblocks" -k "cb_live_..."

Poke uses the same canonical hosted MCP endpoint as other remote HTTP MCP clients.

Codex:

[mcp_servers.chatblocks]
url = "https://chatblocks.ai/api/mcp/v1"
bearer_token_env_var = "CHATBLOCKS_API_KEY"

## First Task Prompt

Create a small dashboard block on my welcome canvas, build it, publish it, and return the canvas URL.

## Safety Rules

- Do not scrape Chatblocks pages. Use MCP and documented HTTP routes.
- Treat cb_live_* keys as workspace-admin credentials.
- Do not put secrets, private tokens, private customer data, or unapproved credentials into public block source or rendered output.
- Do not create phishing, impersonation, spam, malware, credential collection, hidden tracking, or deceptive blocks.
- Do not bypass plan limits, workspace permissions, moderation, or human verification.
- For agent-first setup, send the human the claimUrl and explain that unclaimed workspaces expire.

## Distribution Status

Chatblocks has first-party setup profiles for Claude, Codex, Cursor, Windsurf, OpenClaw, Poke, and generic MCP clients. Marketplace artifacts for OpenClaw ClawHub and Poke Kitchen live in the Chatblocks repo under integrations/agent-platforms.