> ## 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.
# Authoring via an agent
> The MCP authoring loop — your coding agent drives blocks.init, setFiles, build, and publish end-to-end.
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](/authoring/in-app-editor). Both paths produce the same artifact.
## The flow
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](/mcp/setup) has per-client paths and the API key minting flow at `/settings/api-keys`.
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.
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](/mcp/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](/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
| Tool | Plan gate |
| ----------------------------------------------------------------------------- | --------------------------- |
| `blocks.init`, `setFiles`, `getFiles`, `build`, `publish`, `update`, `delete` | None — works on every plan. |
| `blocks.create` (AI generator) | Builder. |
| `blocks.setWidgetData` | None. |
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
Every field in `chatblocks.json`, with examples for both `code` and `embed` formats.
Auto-generated reference for every tool the agent can call.