Give your agent a board it will not make a mess of.
Agents are bad at guessing coordinates. These tools do the geometry, so objects land clear of each other and connectors stay readable.
MCP is local only
Hosted development and production MCP are closed. Those endpoints
return HTTP 404. Guest MCP needs a local
wrangler dev with MCP_GUEST_MODE=loopback.
The local endpoint has no authentication. Any process on your
computer with a board_id can read geometry and write to
that board, so use synthetic content only. Guest boards do not
appear in the canvas, because the canvas keeps its own store in
IndexedDB in your browser.
Connect to a local Worker
The server uses Streamable HTTP. In a copy of this repository, add
MCP_GUEST_MODE=loopback to .dev.vars. Then
run pnpm db:migrate:local, pnpm build, and
pnpm dev. The URL is:
http://localhost:8787/api/mcp
For example, in Claude Code:
claude mcp add --transport http barrio-notes \
http://localhost:8787/api/mcpFour tools
| Tool | What it does |
|---|---|
suggest_positions |
Plans where new boxes can go. It changes nothing. |
check_collisions |
Reports overlaps, blocked IDs, and warnings. It changes nothing. |
layout_canvas |
Previews a new arrangement. With apply: true it
writes the positions.
|
create_objects |
Creates a batch of objects, all or nothing, at automatic or exact positions. |
Safe to retry
Each write takes an expected_revision and a
request_id. An identical retry returns the first result,
and a stale revision fails with no write.
{
"board_id": "use-a-random-uuid-here",
"expected_revision": 0,
"request_id": "first-batch",
"items": [
{ "id": "a", "kind": "note", "bbox": { "width": 200, "height": 100 } },
{ "id": "b", "kind": "note", "bbox": { "width": 200, "height": 100 } },
{ "id": "a-b", "kind": "connector", "source": "a", "target": "b" }
]
}