Skip to main content
Chatblocks is agent-first: your agent (Claude Code, Codex, Cursor, Windsurf, OpenClaw, Poke, or any MCP client) authors blocks by calling tools on the hosted MCP server. The agent writes the code, the platform builds and publishes it, and the result lands on your canvas.
Agent authoring uses workspace API keys, which are available to every signed-in workspace. You can also author with the in-app editor.
If you’d rather drive the same workflow keyboard-first, see In-app editor. Both paths produce the same artifact.

The flow

1

Connect your agent

On your canvas, click the agent status chip in the toolbar (or land with ?connectAgent=1 after signup). The connect overlay is a 3-step wizard with top-level profiles for Claude, Codex, Cursor, Windsurf, OpenClaw, Poke, and Other. Each tile shows the exact config snippet to paste.Cross-reference: MCP → Setup has per-client paths and the API key minting flow at /settings/api-keys.
2

Tell the agent what to build

Plain English. For example:
Make me a block that shows a countdown to my next trip.
The agent figures out the rest. Watch the live-sync badge in your canvas chrome — it flips from “empty” to “live” on the first MCP call.
3

Watch the build land

Refresh your canvas (or wait — it’s reactive). The block tile appears with the freshly-published bundle.

Agent-first canvas workflow

If the agent starts before the human has a Chatblocks account, use agent-created canvases. The agent calls /api/agent/bootstrap, receives a temporary cb_live_* MCP key, builds on the canvas immediately, and sends the returned claim link to the human. This is the preferred path for marketplace recipes, demos, and background agents that need to show useful work before the human signs in.

The MCP tools the agent calls

Every block goes through the same loop. Agents don’t need to be told this — they read the tool descriptions on tools/list — but you’ll see these names in the audit log.
Scaffold a new block. Returns a blockId. The block starts unpublished with a minimal chatblocks.json and a placeholder entry. Free.
Write source files into the block’s virtual filesystem. Caps: 100 files, 250 KB per file, 1 MB total. The agent can call this repeatedly — each call replaces the file set.
Read the current file set. Agents use this to inspect what’s already there before editing.
Run the Vercel Sandbox build of the current files. Produces an HTML bundle and uploads it to Convex storage. Counts against the shared cap of 1000 builds per 30-day window.
Cut a new blockPublishedVersions row pointing at the latest build. The render route now serves the new bundle. Canvas placements pinned to “latest” pick it up immediately.
Full tool reference: MCP → Tool reference.

Live-sync badge

The canvas toolbar shows a small badge with three states, derived from your workspace’s most-recent apiKeys.lastUsedAt:
  • Empty — no MCP calls yet from any key on this workspace. Onboarding hasn’t connected.
  • Live — your agent called within the last few minutes. Builds and edits will show up in real time.
  • Idle — historically connected, but quiet right now.
It’s a sanity check — if you tell your agent to do something and the badge stays “empty,” the agent isn’t actually reaching the MCP server.

Block-expanded overlay

Click any block on your canvas to open the expanded overlay. The right rail shows:
  • File list — every file in the current draft.
  • Recent agent edits — last few setFiles calls with timestamps and the calling key.
  • Monaco diff viewer — compare any two consecutive states.
  • “Open full editor” escape hatch — drop into /blocks/[blockId]/edit for keyboard editing.
When the agent publishes, the overlay iframe re-keys on publishedVersionId so you see the new bundle without a hard refresh.

Constraints

The authoring loop uses the workspace caps.

What’s next

Manifest

Every field in chatblocks.json, with examples for both code and embed formats.

MCP tool reference

Auto-generated reference for every tool the agent can call.