Skip to content

Connect your agent over MCP

Canvas and Pod each run an MCP server you point an agent at. The agent then drives the same surface you watch: screenshot the canvas, tap a widget, flash a target, capture a logic trace. It uses the same protocol as any other tool. Mesh brings its own agent in its chat pane; see Mesh for running an agent against it from outside.

This page covers the local case: the agent and the tool run on the same machine (or the same LAN). No relay, no tunnel, no cloud round-trip.

Tool Transport How you connect
Canvas MCP over Streamable HTTP http://localhost:5050/mcp, served by the running harness. Override the port with PORT=… when you start it.
Pod MCP over stdio The pod-mcp console script from the host tooling. It reaches registered pods over the network itself.

Canvas’s server runs in the harness process, so start the harness before you register it:

Terminal window
make run # boots the harness on :5050

There is no authentication on Canvas’s local endpoint; the posture matches the harness’s other HTTP routes and assumes loopback or a trusted LAN.

Pod’s server is launched by the client as a command. Register your pods first with pod discover and pod register <label> --address <ip> (see Set up Pod), and the MCP tools address them by label.

Register the running server with the claude mcp add command. The --transport http flag is required. Without it the CLI assumes a stdio command, not a URL.

Terminal window
claude mcp add annealage-canvas --transport http http://localhost:5050/mcp

For Pod, register the stdio command:

Terminal window
claude mcp add pod -- pod-mcp

Confirm the server registered and is reachable:

Terminal window
claude mcp list

Claude Code stores this in its MCP config. To scope the server to the current project instead of your user profile, add --scope project, which writes the entry to .mcp.json in the working directory:

{
"mcpServers": {
"annealage-canvas": {
"type": "http",
"url": "http://localhost:5050/mcp"
}
}
}

Claude Desktop reads its servers from claude_desktop_config.json. Open Settings → Developer → Edit Config, or edit the file directly:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the tools under mcpServers:

{
"mcpServers": {
"annealage-canvas": {
"type": "http",
"url": "http://localhost:5050/mcp"
},
"pod": {
"command": "pod-mcp"
}
}
}

Restart Claude Desktop. The tool appears in the MCP connection list, and its core actions become available to the agent.

Codex CLI configures MCP servers in ~/.codex/config.toml under [mcp_servers.<name>]. Set the URL for Canvas’s Streamable-HTTP endpoint:

[mcp_servers.annealage-canvas]
url = "http://localhost:5050/mcp"

For Pod, set the stdio command:

[mcp_servers.pod]
command = "pod-mcp"

Restart Codex (or start a new session) so it picks up the config.

Once connected, the client sees the server’s tools. Pod exposes 28, grouped as pod_*, sessions, dut_* and bench_*, listed in Set up Pod. Canvas exposes core tools plus a search-and-execute gateway to the rest of its catalog. For Canvas the core surface is:

Tool Purpose
screenshot Capture the current canvas as PNG (calls lv.refr_now() first, so the frame is current).
get_source / set_source Read and write the active app source; set_source reloads by default.
tap Single touch at (x, y).
find_widget Locate a widget by text, type, or area; returns its bounding box.
search_actions / execute_action Discover and run the wider catalog (drag, keyboard input, widget-tree inspection, timing) without loading every schema into context up front.
get_pause_status Report whether the agent is paused ({paused, since, reason}), so it knows write-class calls will be refused.

The split keeps the always-loaded surface small: eight core tools, with the remaining catalog actions fetched on demand through search_actions. See Install Canvas for the full action list and the typical edit loop.

  • Connection refused (Canvas). The harness is not running, or it is on a different port. Start it first and check the port matches the URL.
  • Client expects a command, not a URL. For Canvas you omitted the HTTP transport. In Claude Code pass --transport http; in the config files set "type": "http".
  • pod-mcp not found. The host tooling isn’t on the client’s PATH. Install it as in Install, or give the client the full path to pod-mcp.
  • Pod not found. mDNS may not resolve on your network. Register the pod by its LAN IP with pod register <label> --address <ip>.
  • Tools appear but every write fails. Canvas is paused. Unpause it from Studio’s header to re-enable write-class tools.