Canvas Relay

English | 繁體中文 | 日本語

Canvas Relay is a persistent local whiteboard shared by people and MCP-capable AI assistants. A person can draw in the browser while an agent reads the same scene, adds structured elements, records authorship, and continues the work in a later conversation.

The project is intentionally small: it uses Node.js built-ins, plain HTML, CSS, and JavaScript, with no runtime dependencies.

Features

• Browser-based infinite-style canvas with pan, zoom, selection, drawing, text, notes, frames, and erasing.
• MCP server over standard input/output for AI clients.
• Persistent JSON scene and history storage.
• Human and AI provenance on every element and edit.
• Non-destructive update and erase effects with undo and redo.
• Independent visibility filters for human-created and AI-created elements.
• SVG and JSON export.
• Traditional Chinese, English, and Japanese interface translations.
• Local-only HTTP server with same-origin checks and a restrictive content security policy.

Install

Canvas Relay requires Node.js 20 or newer and a desktop browser.

node --version
git clone https://github.com/rncchen/canvas-relay.git
Set-Location canvas-relay

The project has no external runtime packages, so npm install is not required. Once configured, the MCP client starts mcp.mjs, which automatically starts the browser server at http://127.0.0.1:4173.

You do not normally need to run npm start. Use it only to run the browser canvas without an MCP client or to troubleshoot automatic startup. A second MCP process reuses an existing healthy Canvas Relay server on the same port.

Add the MCP server to Codex

Run these commands from the repository root, replacing the example with the absolute path on your computer:

codex mcp add canvas-relay -- node "C:\absolute\path\to\canvas-relay\mcp.mjs"
codex mcp list

Restart Codex or open a new session after adding the server. In the Codex IDE extension, add an STDIO server from MCP servers, use node as the command and the absolute mcp.mjs path as its argument, then restart the extension.

Project-scoped .codex/config.toml configuration is also supported:

[mcp_servers.canvas-relay]
command = "node"
args = ["C:\\absolute\\path\\to\\canvas-relay\\mcp.mjs"]
cwd = "C:\\absolute\\path\\to\\canvas-relay"

Add the MCP server to Claude Code

Use --scope user to make Canvas Relay available across projects, or replace it with local for the current project only:

claude mcp add --transport stdio --scope user canvas-relay -- node 'C:\absolute\path\to\canvas-relay\mcp.mjs'
claude mcp list

Open a new Claude Code session and run /mcp to verify the connection. See the official Claude Code MCP documentation for scope and STDIO details.

Claude Code discovers the bundled skill at .claude/skills/use-canvas-relay/SKILL.md. It opens the session-specific canvas URL after editing. See the official Claude Code Skills documentation for discovery rules.

Add the MCP server to Claude Desktop

Open Settings → Developer → Edit Config. On Windows, edit %APPDATA%\Claude\claude_desktop_config.json and replace the example path below:

{
  "mcpServers": {
    "canvas-relay": {
      "type": "stdio",
      "command": "node",
      "args": [
        "C:\\absolute\\path\\to\\canvas-relay\\mcp.mjs"
      ]
    }
  }
}

Save the file, fully quit Claude Desktop, and launch it again. Claude Desktop does not load project-scoped Claude Code skills, but the MCP process still starts the browser server automatically.

See the official MCP Claude Desktop tutorial for the settings screen and platform-specific configuration paths.

The repository-local .mcp.json is ignored because it contains a machine-specific absolute path.

Use the bundled skill and browser verification

The repository includes .agents/skills/use-canvas-relay/SKILL.md for Codex and .claude/skills/use-canvas-relay/SKILL.md for Claude Code. Restart the client if its skill does not appear.

Use $use-canvas-relay to draw a three-bedroom floor plan.

The skill assigns a unique canvasId to the current conversation, edits that canvas, then uses browser control to open http://127.0.0.1:4173/?canvas=<canvasId> for visual verification. Install or enable the bundled Browser plugin in the ChatGPT / Codex Browser settings to allow local browser inspection.

Sessions and author labels

Use a different canvasId for each conversation and keep that value unchanged across all tool calls in the same conversation. The browser URL must use the same value in its canvas query parameter.

Author labels are hidden by default without removing author metadata. Enable Author labels in the top-left display controls when provenance is needed. For a clean MCP preview, call canvas_get_view with includeAuthors: false.

Recommended agent workflow

1. Choose a unique canvasId for the conversation and reuse it for every tool call.
2. Call canvas_get_scene before changing the canvas.
3. Call canvas_get_view when layout, overlap, density, or freehand content must be understood visually.
4. Add or update elements in batches.
5. Preserve existing content unless the user explicitly asks to erase or clear it.
6. Use canvas_undo when a canvas operation needs to be reverted.
7. Open the matching browser URL, hide author labels, and inspect the actual layout before delivery.

MCP tools

Tool	Purpose
canvas_get_scene	Read source elements, effects, provenance, layers, activity, and the current composite scene.
canvas_get_view	Render the current composite scene as SVG.
canvas_add_elements	Add text, notes, rectangles, ellipses, lines, arrows, freehand strokes, or frames.
canvas_update_elements	Add non-destructive move, resize, text, and style changes.
canvas_delete_elements	Add reversible erase effects for selected elements.
canvas_undo	Restore the scene before the latest human or AI operation.
canvas_redo	Reapply the latest undone operation.
canvas_clear	Reversibly erase all currently visible elements. Use only after explicit user confirmation.

The MCP server also exposes these resources:

• canvas://scene/current
• canvas://view/current.svg

Data and configuration

The unnamed default canvas is stored in data/scene.json and data/history.json. Named sessions are stored under data/canvases/<canvasId>/scene.json and history.json. All runtime data is ignored by Git.

Variable	Default	Purpose
PORT	4173	HTTP port for the browser application.
CANVAS_RELAY_DATA_DIR	<repository>/data	Alternate directory for scene, history, and lock files.

The HTTP server binds to 127.0.0.1. It is designed for local use and has no authentication layer. Do not expose it directly to a network.

Tests

npm test

The test suite covers MCP negotiation, persistent scene changes, authorship, non-destructive effects, layer composition, undo, and redo.

Documentation

• Architecture
• Development guide
• Research notes
• 繁體中文 README
• 日本語 README