Developers

Claude Code walkthrough

One real session, start to finish: connect Claude Code to Vmotif, ask for a brand mark in plain language, and watch it create the canvas, set the design guide, run the generation, hit a validation error, fix it and hand back the link. Every tool call and response on this page is what the server actually sent.

Connect and authenticate#

01
Add the server
Terminal
```
claude mcp add --transport http vmotif https://vmotif.com/api/mcp
```
Once per machine. Add --scope project to write it into the repository’s .mcp.json instead, so teammates who clone the project get it too.
Authenticate
Start claude, type /mcp, pick vmotif and choose Authenticate. A browser tab opens Vmotif’s sign-in, then a consent page naming the client. Approve it and return to the terminal; /mcp now shows the server connected with its tools listed.
Start a fresh session
Tools are discovered when a session starts, so if you added the server from inside a running session, exit and start claude again before asking it to use them.

Ask for the work#

You talk to Claude Code as you would about anything else:

You

Make me a Vmotif canvas called "Northwind launch" for a home coffee
subscription. Set a short DESIGN.md — warm and plain, roast brown on
cream, one ember accent — then generate a single-colour logo mark: a
compass needle that reads as a coffee bean. Leave me a note on the canvas
to iterate on the mark before the hero. Give me the link when it's done.

Claude Code plans the calls itself. What follows is the sequence it made, with the server’s responses.

1 · Create the canvas#

create_canvas

{ "name": "Northwind launch" }

Response

{
  "id": "ddfcff4f-659d-48fd-97fb-56bc4d82f51a",
  "name": "Northwind launch",
  "url": "https://vmotif.com/app/w/ddfcff4f-659d-48fd-97fb-56bc4d82f51a",
  "workspaceId": null,
  "nodeCount": 0,
  "edgeCount": 0,
  "createdBy": { "source": "mcp", "actorName": "Claude Code (vmotif)" },
  "createdAt": "2026-09-22T02:37:39.410346+00:00"
}

The canvas exists and has a link before anything is on it. Open the URL now and you can watch the rest arrive live. createdBy.actorName is what the canvas will show as provenance on anything this client creates.

2 · Add the guide, the prompt and a note#

One call adds three nodes. The prompt node’s output node is created and wired automatically — you never add an image node for a generation by hand.

add_canvas_nodes

{
  "canvas_id": "ddfcff4f-659d-48fd-97fb-56bc4d82f51a",
  "nodes": [
    {
      "type": "style_guide_input",
      "value": "# Northwind\n\nCoffee subscription for people who brew at home.\n\n## Voice\nWarm, plain, unhurried. No exclamation marks.\n\n## Colors\n- Roast: #3B2A20 (primary ink)\n- Cream: #F4EDE4 (ground)\n- Ember: #D9642B (one accent, sparingly)\n\n## Visual style\nSoft daylight, matte paper textures, no gloss."
    },
    {
      "type": "prompt",
      "output_type": "image",
      "title": "Logo mark",
      "model": "meta/muse-image-1.0",
      "aspect_ratio": "1:1",
      "prompt": "A single-colour logo mark for Northwind, a home coffee subscription: a compass needle that reads as a coffee bean, centred on cream, Roast ink, generous margins, no text."
    },
    {
      "type": "sticky_note",
      "color": "orange",
      "content": "First pass from Claude Code — run it, then iterate on the mark before touching the hero."
    }
  ]
}

Response

{
  "canvasId": "ddfcff4f-659d-48fd-97fb-56bc4d82f51a",
  "url": "https://vmotif.com/app/w/ddfcff4f-659d-48fd-97fb-56bc4d82f51a",
  "nodeCount": 4,
  "nodes": [
    { "id": "442fdd01-fb65-45dd-9a62-95450a3c49dd", "type": "textInputNode",  "x": 400, "y": 320 },
    { "id": "5c24c9d2-6a58-4f9c-a5f9-f5067e18ec0c", "type": "promptNode",     "x": 400, "y": 640 },
    { "id": "05a4857d-8efd-46ee-980b-46073313f338", "type": "imageNode",      "x": 880, "y": 640 },
    { "id": "ca9382c7-1ac4-4c35-847a-f11e8e1c21f6", "type": "stickyNoteNode", "x": 400, "y": 1120 }
  ],
  "edges": [
    { "id": "0465dc71-3a5e-4729-8597-776c698f9bd0", "source": "5c24c9d2-6a58-4f9c-a5f9-f5067e18ec0c", "target": "05a4857d-8efd-46ee-980b-46073313f338" }
  ],
  "createdBy": { "source": "mcp", "actorName": "Claude Code (vmotif)" }
}

Three nodes asked for, four created: the prompt brought its image node and the edge between them. No coordinates were given, so they stacked below one another; read_canvas and update_canvas rearrange later if it matters. The DESIGN.md is canvas-wide, so the prompt does not need to be connected to it.

3 · Run it#

run_workflow

{ "workflow_id": "ddfcff4f-659d-48fd-97fb-56bc4d82f51a" }

Response

{
  "id": "049b6f0e-81b1-4edc-b7a8-05bca7315eb3",
  "workflowId": "ddfcff4f-659d-48fd-97fb-56bc4d82f51a",
  "status": "pending",
  "progress": { "total": 1, "completed": 0 },
  "results": [],
  "error": null
}

The run is queued and the call returns. Claude Code polls get_workflow_run — and eight seconds later gets this:

get_workflow_run

{
  "id": "049b6f0e-81b1-4edc-b7a8-05bca7315eb3",
  "status": "failed",
  "progress": { "total": 1, "completed": 1 },
  "results": [
    {
      "type": "image",
      "status": "failed",
      "outputNodeId": "05a4857d-8efd-46ee-980b-46073313f338",
      "promptNodeId": "5c24c9d2-6a58-4f9c-a5f9-f5067e18ec0c",
      "error": "meta/muse-image-1.0 does not support the 1:1 aspect ratio. Use AUTO or choose a supported ratio."
    }
  ],
  "error": "meta/muse-image-1.0 does not support the 1:1 aspect ratio. Use AUTO or choose a supported ratio.",
  "completedAt": "2026-09-22T02:38:01.604+00:00"
}

This is the part worth showing. The model chosen for its price does not offer a square output, so the run failed at validation — nothing was charged — and the error names the node and says what to change. An agent does not need to guess.

4 · Fix and re-run#

Claude Code called list_models, picked Nano Banana 2 Lite — a similar price, and it takes the square ratio — switched the prompt node’s model in place, and ran again. A patch touches only the fields it names; the prompt text and the ratio stayed.

update_canvas

{
  "canvas_id": "ddfcff4f-659d-48fd-97fb-56bc4d82f51a",
  "updates": [
    { "node_id": "5c24c9d2-6a58-4f9c-a5f9-f5067e18ec0c", "data": { "model": "google/gemini-3.1-flash-lite-image" } }
  ]
}

Response

{
  "canvasId": "ddfcff4f-659d-48fd-97fb-56bc4d82f51a",
  "movedCount": 0,
  "removedNodeCount": 0,
  "removedEdgeCount": 0,
  "updatedNodeCount": 1,
  "addedEdges": []
}

run_workflow → get_workflow_run, 40 s later

{
  "id": "8551142b-7557-4fd9-b077-678f5d8a0087",
  "status": "completed",
  "progress": { "total": 1, "completed": 1 },
  "results": [
    {
      "type": "image",
      "status": "completed",
      "url": "https://auth.vmotif.com/storage/v1/object/public/workflow-images/…/1790044890881-49ff7564.jpg",
      "mediaType": "image/jpeg",
      "costMicros": 62638,
      "outputNodeId": "05a4857d-8efd-46ee-980b-46073313f338",
      "promptNodeId": "5c24c9d2-6a58-4f9c-a5f9-f5067e18ec0c"
    }
  ],
  "error": null,
  "completedAt": "2026-09-22T02:41:31.978+00:00"
}

costMicros: 62638 is $0.063 — the same metered price the canvas would have shown. The image is already on the canvas’s image node; the URL is a bonus for anything the agent wants to do with it next, such as transform_image to make a 200 KB WebP for a README.

5 · Hand back the link#

Claude Code

Done. Northwind launch is at
https://vmotif.com/app/w/ddfcff4f-659d-48fd-97fb-56bc4d82f51a

- DESIGN.md set (Roast / Cream / Ember, warm and plain)
- Logo mark generated: a compass needle drawn as a bean, Roast on cream — $0.06
- Sticky note left on the canvas about iterating the mark first

Muse Image 1.0 turned out not to offer square output, so I switched the
prompt to Nano Banana 2 Lite before the second run.

Open the link and the canvas has four nodes, the mark on its image node with the cost badge, and an orange sticky. Nodes this client creates carry Claude Code (vmotif) as their provenance. From here the work is ordinary canvas work: tweak the prompt in the browser, press Run, or go back to the terminal and ask for the hero.

Getting more out of it#

Tell it which canvas. “On my Northwind canvas…” is enough — it will list_projects and match the name. To pin it, paste the canvas URL; the id is in it.
Bring the codebase along. Claude Code can read your repo and the canvas in one turn: “use the palette from tokens.css as the DESIGN.md colours” works, and so does writing generated SVG straight into public/.
Prebuilt workflows are one call. “Seed it with the Brand Kit workflow” becomes create_canvas with a premade_workflow_id; “add a Press Kit to this canvas” becomes add_premade_workflow.
Team wallets. If you generate for a client workspace, say so: “bill this to the Acme workspace” passes workspace_id to the spending tools.
Put it in CLAUDE.md. A line such as “Brand assets live on the Vmotif canvas Northwind launch; read it before generating anything visual” means every future session starts by calling read_canvas.

Tool reference REST API