MCP

vDesign speaks the Model Context Protocol. An assistant connected over MCP can list the documents you have open, read them, change them, create new ones and show you the result. It works on what is open in vDesign, never on files on your disk: it cannot read a document you did not open, and saving stays something you do.

There are two ways to connect, and the desktop app uses one at a time. Choose in Settings → Connect.

Remote MCP

Recommended. Claude, ChatGPT and other assistants that take a connector URL reach vDesign through one address:

https://mcp.getv.design/mcp

Add it as a connector in your assistant. The first time, it sends you to a vDesign page that asks you to sign in and allow the connection. After that, the assistant works on the documents open in vDesign, in the desktop app or in the web app at getv.design/app, on any device where you are signed in. You can see and remove the assistants you have allowed in Settings → Connect.

The web app offers remote MCP only.

Local MCP

For Claude Desktop, Cursor and other apps on the same computer as the desktop app. Turn on local MCP in Settings → Connect and the app runs a server only that computer can reach:

http://127.0.0.1:7823/mcp

The port stays the same across restarts, so the address is set up once.

• Claude Desktop: Settings → Connect can write the entry into Claude Desktop’s own configuration for you, and shows when Claude Desktop has connected.
• Apps that start a server from a command, such as Cursor or Claude Code: the app keeps a small launcher script for them, at ~/.vdesign/bin/vdesign-mcp on macOS, and Settings → Connect copies its path.
• Apps that take a URL: give them the address above.

Nothing outside your computer can connect to the local server.

The tools

An assistant needs no instructions from you to use them: the server tells it to learn the format first, by loading the vdesign skill, and to build anything large a region at a time, so you watch the design arrive rather than wait for it. An app that supports the MCP Skills extension loads the skill itself; any other assistant gets it from vd_skill. See Agents.

Some tools depend on where the server runs. Exporting a file (vd_export) needs your click to save it, so the desktop app offers it and remote MCP does not yet; remote MCP adds vd_open, which gives you a link to a document the assistant made while vDesign was closed. The reference below is generated from the servers themselves, and says where each tool is offered.

Tool reference

Every tool a vDesign MCP server can offer, read from the servers themselves. Which ones a server lists depends on where it runs: desktop is local MCP in the desktop app, remote is https://mcp.getv.design/mcp, and CLI is the vdesign-mcp command for developers. A tool a server does not offer is absent from its list, not present and failing.

Picture search is switched off in the desktop app and on remote MCP for now, whatever keys are stored. A picture still reaches a document by URL, through vd_add_asset.

vd_add_asset

Add an image to a document. Offered: always.

Register an image under a name, and optionally place it. The source is one of: {“url”: “https://…”} (public https only); {“data”: “<base64>”, “type”: “image/png”} for bytes you actually have. A picture the person gave you or has on their machine is neither — you cannot pass on an image you can see, and no tool reads file paths. For that, do not call this tool: write the image with a src nothing supplies yet and a name saying what goes there (image nav.logo … src=logo name="Your logo"). The canvas shows it as a slot the person drops the file into; carry on, and tell them it is there. Never write an asset line yourself: place the image with image <id> src=<name>.

vd_add_icon

Place icons in a document. Offered: always.

Place Lucide icons as vector nodes, by name — a name from vd_search_icon, or one you know (old names like “home” or “alert-circle” still work). Up to 20 in one call, one undo step; all land or none do. x, y and size take a number or an expression such as ”(@cta.left + 16)”. The stroke scales with the size as Lucide’s does; color defaults to the document’s ink token, or the text colour.

vd_add_image

Add a found image to a document. Offered: CLI only, when an image key is configured.

Download a candidate from vd_search_image into a document, registering it under a name with its attribution. Optionally place it as a node. Adding the same image twice is harmless: assets are keyed by content.

vd_assets

List a document’s images. Offered: always.

Every image registered in a document: its name (what image … src= refers to), type, pixel size, bytes, attribution, and which nodes use it — then the slots still waiting for the person to drop a picture into.

vd_create

Create a document. Offered: always.

Start a new .vd document. Leave “dsl” out for an empty canvas with no page — insert the frame you need (vd_patch: insert frame page x=0 y=0 w=1280 h=720) — or pass a skeleton: title, tokens, fonts and the frames. Then add each region with its own vd_patch rather than writing the whole design here: the person sees each call land, and one large call is a long wait on an empty canvas. Load the vdesign skill first if you do not know the DSL (vd_skill). Nothing is created if the DSL would not parse. You cannot save it. Against a running app the new document lives in a window until the person using it saves — vd_list shows which documents that applies to.

vd_export

Export a document. Offered: desktop and CLI only.

Export a document as png, jpg, webp, svg, pdf, ai (Adobe Illustrator) or html. The export is exactly what the canvas shows. Rasters come back as images you can look at — use png with save:false to check your own layout. save:true puts the files where the person can find them — beside the document. Only save when the person asked for a file. Every frame is exported unless you name frames or nodes.

vd_list

List documents. Offered: always.

The documents available here, with the handle every other tool needs. Call this first: a handle you guessed is how a session starts by editing the wrong document, and there is no other way to learn one.

Takes no arguments.

vd_open

Open a document in vDesign. Offered: remote only.

A link that opens a document vd_list marks “not open” in vDesign, on the web or the desktop app. Give it to the person: such a document was made while vDesign was not open, and is kept for a week until they open it. Its handle keeps working afterwards.

vd_patch

Edit a document. Offered: always.

Apply mutation statements (set / insert / delete / move / motion) to a .vd document. The dialect is the skill’s reference/edits.md (vd_skill path “reference/edits.md”). Nothing is written if any statement fails to parse.

vd_problems

Check a document. Offered: always.

Everything wrong with a .vd document: what would not parse, and what would not draw. Worth calling after any edit you are not certain about.

vd_read

Read a document. Offered: always.

The current state of a .vd document. Defaults to an outline — every node with its id, type and box — which is what most edits need. Ask for a node id to see one subtree in full, or mode “full” for the whole design. Never returns image bytes.

vd_remove_asset

Remove an image from a document. Offered: always.

Unregister an image. Refused while nodes still draw it, unless force is true, which deletes those image nodes too.

vd_search_icon

Search for an icon. Offered: always.

Find icons in the Lucide set (1,900 line icons) by name or by what they show: “settings”, “notification”, “arrow right”. One line per icon, its name then its tags. Place one with vd_add_icon — never write an icon’s path data yourself. Lucide has no brand logos (GitHub, X, YouTube): leave a logo as an image slot.

vd_search_image

Search for an image. Offered: CLI only, when an image key is configured.

Find a freely licensed photograph. Providers: unsplash, pexels. Returns candidates with their attribution; pass one whole candidate to vd_add_image.

vd_show

Show the design. Offered: always.

Show the person a document in the chat, as a preview of its pages. Call it once, when a piece of work is done, never after each vd_create or vd_patch: every call draws another preview. Pictures show as placeholders.

vd_skill

Learn the vDesign format. Offered: always.

Loads the vdesign skill. Author and edit vDesign documents — posters, slides, hero sections, card grids, any laid-out visual document — in the .vd DSL. Use when asked to create, change, or read a vDesign document, a .vd file, or when a task involves designing a layout that should stay editable and relational rather than being flattened to fixed coordinates. Returns SKILL.md unless asked for another file; ask for one only when you need it, which is what keeps this cheap.