AI agent (MCP)

Canvas can be driven by an AI agent — Claude Code, or anything else that speaks the Model Context Protocol. The agent edits the project open in your browser, and everything it does lands in the normal undo history, so anything it gets wrong is one Ctrl+Z away.

Setting it up

1. Download and run the bridge.

curl -fsSL https://canvas.refrag.com/canvas-mcp.mjs -o canvas-mcp.mjs
node canvas-mcp.mjs

It's a single self-contained file — no checkout, no npm install. It prints a pairing token:

[canvas-mcp] listening on ws://127.0.0.1:7333

  Pairing token:  3f9a1c2b

  Open Canvas, click the menu → MCP, and paste that token.

2. Connect the editor. In Canvas, open the menu and choose Connect an AI agent (MCP). Paste the token and press Connect. The dot turns green.

3. Point your agent at the bridge. For Claude Code, add it to your MCP config:

{
  "mcpServers": {
    "canvas": { "command": "node", "args": ["/absolute/path/to/canvas-mcp.mjs"] }
  }
}

How it fits together

The browser is always the party that connects — a web page can't accept incoming connections — so the bridge listens and the tab dials out to it.

agent  ──stdio──▶  canvas-mcp.mjs  ──websocket──▶  your browser tab

Nothing is stored in the bridge. It's a wire: the project only ever exists in your browser, and closing the tab ends the session.

The bridge listens on 127.0.0.1 only, and the pairing token is what stops any other page you happen to have open from connecting to it by guessing the port.

What the agent can do

Tool
`get_overview`	The whole project: forms, kinds, links between them, validation summary
`get_form`	One form in full, with every element and its actions
`create_form` / `update_form` / `delete_form`	Manage forms
`set_root_form`	Choose which form players see first
`add_element` / `update_element` / `delete_element` / `move_element`	Manage elements
`set_actions`	Say what a button or a submit does
`set_project_settings`	Name, namespace, target version, open triggers
`validate_project`	Check for problems that would misbehave in game
`list_templates` / `apply_template`	Start from a built-in project
`preview_export`	Build the packs and return the file list plus generated `ui.js`
`undo`	Undo the last edit

Forms and elements are addressable by name as well as by id, so an agent told "add a button to the Shop form" can act on that directly.

get_form reports each button's selectionIndex — the index the game will actually report when it's pressed. Headers, labels and dividers don't consume one, so counting elements gives the wrong answer.

Things worth telling your agent

Run validate_project before declaring the work finished. It catches dead-end buttons and broken links, which are the two most common things to get wrong.
openForm and close end an action sequence. Anything after them never runs.
Value placeholders only work within one form. A command in form A can't read a field from form B.
A message form has exactly two buttons. Not one, not three.

Options

Variable	Default
`CANVAS_MCP_PORT`	`7333`	Quarry uses 7331 and Orbit 7332, so all three can run at once
`CANVAS_MCP_TOKEN`	random	Fix the token for scripted setups
`CANVAS_MCP_TIMEOUT`	`20000`	How long a call may wait for the tab, in ms

If it doesn't connect

"No Canvas tab is connected." The editor isn't paired. Open the MCP panel and connect.
The dot stays red. The bridge isn't running, or it's on a different port. Check the port in the panel matches what the bridge printed.
"That pairing token is not right." Restarting the bridge generates a new token unless you set CANVAS_MCP_TOKEN.
It disconnects when you reload. Expected — the tab is the connecting party. The panel remembers your token, so reconnecting is one click.