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 is agent-first: your coding agent (Claude Code, Codex, Cursor, Windsurf, 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. 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

Pick your agent at /onboarding/agent — a 4-tile picker (Claude / Codex / Cursor / Windsurf) plus an Other option for any MCP client. Each tile shows the exact config snippet to paste.Cross-reference: MCP → Setup has per-client paths and the API key minting flow.
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.

​
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 that points back at the BYOK authoring loop as the free alternative.
The Free path: 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 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

ToolPlan gate
blocks.init, setFiles, getFiles, build, publish, update, deleteNone — works on every plan.
blocks.create (AI generator)Builder.
blocks.setWidgetDataNone.
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.