Shot Canvas MCP
Let Claude, Cursor, Codex or any app that speaks MCP design with you on the canvas. Your agent gets one tool per canvas command, and you watch every change land live and edit the same layers by hand.
Two ways in
Both give your agent the same tools. On a computer, the local MCP is all you need: it works in your shared canvases too, once you sign in. The cloud connector is for apps that can't run it.
| Cloud connector | Local MCP | |
|---|---|---|
| Reaches | Your shared canvases, and new ones it starts | Canvases saved on this computer, and your shared canvases |
| Account | Yes. The app signs in once and stays connected | Only for shared canvases: the first time, your agent gives you a link to sign in |
| Works from | Any app, on any device | Apps on this computer. Needs Node.js 20 or later |
| Address | https://mcp.shotcanvas.io/mcp | npx -y shot-canvas mcp |
Got a shared canvas link (shotcanvas.io/canvas/…)? Either works: the local MCP sends its calls through the cloud. A canvas on this machine (…?local=true or localhost)? The local MCP. If you have both installed, your agent should use the local one.
Cloud connector shared canvases
A remote MCP server (streamable HTTP) at https://mcp.shotcanvas.io/mcp. The first time, your app opens a browser to sign in to Shot Canvas and Allow. New canvases it creates are restricted: only you can open them until you invite someone or turn on link access.
Claude (claude.ai or the desktop app)
- Open Settings → Connectors and choose Add custom connector.
- Name it Shot Canvas and give it this address:
https://mcp.shotcanvas.io/mcp
- Press Connect, sign in and Allow. It shows up in Claude Code too.
Claude Code
- Add it for all your projects:
claude mcp add --scope user --transport http shot-canvas-cloud https://mcp.shotcanvas.io/mcp
- In Claude Code, run
/mcp, pick shot-canvas-cloud and Authenticate.
Cursor and VS Code
Use the one-click buttons on shotcanvas.io/agents, then press Connect (Cursor) or start the server when asked (VS Code), and sign in.
Codex
- Add it to
~/.codex/config.toml:[mcp_servers.shot-canvas-cloud] url = "https://mcp.shotcanvas.io/mcp"
- Sign in:
codex mcp login shot-canvas-cloud
Any other app
Add https://mcp.shotcanvas.io/mcp as a remote MCP server (streamable HTTP) and sign in when it asks.
Local MCP canvases on this computer
No account. Your agent starts Shot Canvas on this computer, and your canvases are files in ~/.shot-canvas/files until you share them.
Claude Code and Codex, with the skill
npx -y shot-canvas install
This adds the shot-canvas MCP server to both apps for every project, and installs the Shot Canvas skill, which teaches the agent when and how to design on the canvas. On a Mac it also starts the local helper when you log in.
Any other app
claude mcp add --scope user shot-canvas -- npx -y shot-canvas mcp
Or, in an app's JSON config:
{
"mcpServers": {
"shot-canvas": { "command": "npx", "args": ["-y", "shot-canvas", "mcp"] }
}
}Options and how it runs
The local helper is a small server on 127.0.0.1:5180 that answers only to this machine. It keeps the files, routes agents, and serves the canvas at http://localhost:5180. The MCP server starts it when nothing answers.
--name "My agent"sets how the agent shows to you on the canvas.--canvas <space>makes it prefer one canvas.SHOT_CANVAS_BROWSER=systemletsopenCanvasopen your default browser. The default isnone: the agent opens the canvas in its own in-app browser.
Your first design
Just ask for something visual: “mock up a sign-up flow and make it clickable”. A well-behaved agent will:
- Start a canvas.
createDocument({ name })makes a new canvas with one empty page and binds the agent's calls to it. To continue an existing one,listDocumentsthenopenCanvas. - Open it where you can see it. The agent opens the returned address in its own in-app browser (Claude Code's Browser pane, Codex's in-app browser), beside the chat. It shouldn't launch your default browser unless you ask.
- Build.
write({ html })turns HTML and CSS into editable native layers with auto layout, a whole screen in one call. Repeated UI becomes one component with instances. - Check its work.
renderFramePngrenders a frame exactly as it exports, so the agent can look before it tells you it's done. - Hand back a link.
linkTogives a link to the frame or page it made.
Working together
- Every answer ends with your context: your page, your selection, what's on your screen. So “make this bigger” works on what you selected.
getContextreads it any time. - Undo is per person. ⌘Z takes back only your changes. An agent's
undotakes back only its own. - Tasks.
startTask({ label })groups an agent's changes under a name. History shows the task as one line, with one Undo for all of it. - One undo step.
batchandrunapply many commands as one all-or-nothing change. - Your edits win. In a frame an agent is working on, what you change stands. Its out-of-date edits are refused, and it's told what you changed.
- Several agents at once.
usePagelets an agent work on another page while you stay on yours. Each agent has an avatar and a name tag where it works. - Your selection is yours. Commands never change it unless the agent passes
select: true.
Links and “this”
Copy link (beside History) copies a link to what's selected, or to the page. Paste it to an agent in any app: openLink points its calls at that canvas and page, and tells it which frame and layers the link means. That's what “this” is.
- Shared canvas:
https://www.shotcanvas.io/canvas/<id>/<page>?frame=… - Local canvas:
…/canvas/<id>/<page>?local=true&frame=…
To move a local canvas to the cloud, use Share in the canvas, or have the local agent call shareDocument. From then on, the local agent's calls for it go through the cloud.
Tool reference
Each canvas command is a typed MCP tool with a description and a JSON Schema for its arguments. describeCommands lists them all from inside a session. Grouped here by what they're for.
Canvases and pages
createDocument | Start a new canvas with one empty page, and bind calls to it |
listDocuments | Your canvases (local: saved on this machine; cloud: owned, invited to or opened by link) |
openCanvas | Open or resume a canvas and bind later calls to it |
openLink · linkTo · describeLink | Follow a link you were given; hand one back |
listCanvases · useCanvas | Local: the windows open now, and which one calls go to |
shareDocument · shareFolder | Local: move a canvas or folder to the cloud |
renameDocument | Rename the canvas |
listPages · addPage · switchPage · usePage | Pages within the canvas |
renamePage · duplicatePage · deletePage · reorderPages · clearPage | Manage pages |
startTask · endTask | Group changes under a name in History |
Reading the canvas
getContext | Your page, selection and view, and who is working where |
getState | The page's layers: whole for a small page, an outline in parts for a big one |
findLayers · listFrames · getWeight | Find layers; list frames; how heavy a page is |
listComponents · listStyles · listVariables · listFonts | What the canvas has to reuse |
getHistory · getCapabilities · describeCommands | Recent changes; layer types, tools and presets the canvas offers; every command |
Building
write | Build a whole screen from HTML/CSS as editable layers with auto layout, in one call |
run · batch | A script, or several commands, as one all-or-nothing change |
addFrame · setFrameSize · removeFrame · setGap · setOutputSize | Frames (artboards) |
addText · setTextStyle · createLayer · addImageFromDataUrl · addFile · importSvg | Text, shapes, images, files and SVG |
updateElement · updateElements · deleteElement · duplicateElement | Change or remove layers |
moveLayers · groupLayers · alignLayers · distributeLayers · addAutoLayout | Arrange and lay out |
setEffects · setMask · booleanLayers · setVectorNetwork · drawFreehand | Effects, masks and vectors |
importClaudeDesign | Bring in a Claude Design canvas as editable frames |
Design systems
createComponent · createInstance · combineAsVariants · setVariant · swapInstance | Components and variants |
createStyle · applyStyle · updateStyle | Fill, text, effect and grid styles |
createVariableCollection · createVariable · bindVariable · setVariableMode | Variables and modes, like Light and Dark |
setControls · setControlValue | Controls: settings you adjust in the inspector |
listSkills · runSkill · saveSkill · connectLibrary | Skills: reusable recipes, with a button each |
Seeing, prototyping and exporting
renderFramePng · renderLayersPng · renderViewPng · renderLayersSvg | Renders for the agent to look at |
addInteraction · setFlowStart · getPrototype · play · stopPlay | Clickable prototypes and Play |
exportDocument · exportFrame · exportFramesPdf · exportAllZip · copyAs | PNG, JPG, SVG, PDF and CSS, to your downloads or clipboard |
fitView · zoomToLayers · select | Show you something on screen |
Comments and history
listComments · addComment · reply · reactToComment · resolveComment | Comment threads, as the agent itself |
undo · redo | The agent's own changes only |
moveToArchive · archivePage · restoreFromArchive · freezeFrames | Keep heavy canvases fast |
Tools (extending the canvas)
installTool · installToolFromUrl · describeToolFormat | Add a new way to draw: one sealed script that calls defineTool |
listTools · setToolHidden · moveTool · removeTool | Manage the toolbar |
Shared canvases respect roles. Through a viewer's access, an agent gets only reading, the view, Play and exports. Commenters can comment and react.
Connected apps
Signed in at shotcanvas.io/agents, you'll see every app connected to your account. Disconnect signs that app out: it has to sign in again to work in your canvases.
Troubleshooting
- The agent opened my default browser. Ask it to open the address in its in-app browser instead. Only
browser: "system"orSHOT_CANVAS_BROWSER=systemopens yours. - It can't find my shared canvas. The local MCP lists shared canvases only once this computer is signed in. Paste the canvas link:
openLinkgives the sign-in link if it is needed. - The local canvas won't open. Check that Node.js 20 or later is installed and that nothing else is using port 5180.
- The cloud connector asks me to sign in again. It was disconnected, or its sign-in expired. Authenticate again from your app's MCP settings.
Need a hand? See Help or email support@shotcanvas.io.