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.
The servers
Section titled “The servers”| 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:
make run # boots the harness on :5050There 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.
Claude Code
Section titled “Claude Code”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.
claude mcp add annealage-canvas --transport http http://localhost:5050/mcpFor Pod, register the stdio command:
claude mcp add pod -- pod-mcpConfirm the server registered and is reachable:
claude mcp listClaude 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
Section titled “Claude Desktop”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
Section titled “Codex CLI”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.
What the agent gets
Section titled “What the agent gets”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.
Troubleshooting
Section titled “Troubleshooting”- 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-mcpnot found. The host tooling isn’t on the client’s PATH. Install it as in Install, or give the client the full path topod-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.