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 free on every plan. 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 my Stripe MRR with a sparkline of the last 30 days.
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 your monthly build quota (100 for Free, much higher for Builder).
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.

​
AI-generated drafts

There’s a separate tool, blocks.create, for kicking off a brand-new block from a prompt. It runs the AI generator server-side and streams the partial source over Server-Sent Events. The output is saved as a draft (isPublished: false); the agent or human still has to call blocks.build and blocks.publish to ship it.
blocks.create is Builder-plan only. Free workspaces get a PRO_REQUIRED error and can hand-author blocks in the in-app editor.
The non-AI path (free on every plan): have your agent write the source itself using its own LLM budget, then call blocks.setFiles → blocks.build → blocks.publish. No platform-side AI calls, no AI-generation quota consumed.

​
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 non-AI authoring loop is intentionally not gated — Free users can hand-author blocks indefinitely. The gate is on the on-platform AI inference, not the act of publishing.

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