5. The MCP server

5.1 Registration#

ud mcp runs a Model Context Protocol server (protocol 2025-06-18) over stdio, named ui-designer (CMD-7). ud mcp install adds it to the workspace’s .mcp.json, creating the file if needed and keeping other servers:

{
  "mcpServers": {
    "ui-designer": {
      "command": "ud",
      "args": ["mcp"]
    }
  }
}

When ud is not on the PATH outside VS Code terminals, install writes the absolute path of the stable ud launcher that the extension keeps up to date (CLI-001) instead of "ud". Options:

Claude Code shows the tools as mcp__ui-designer__<tool>. Other clients (Claude Desktop, Cursor, VS Code’s own MCP support) use the same command.

5.2 Tools#

tools/list returns the supported Figma tools with their input schemas, property for property (CMD-1, CMD-8), followed by the native tools. Two deliberate relaxations of Figma’s schemas: fileKey has no ^[0-9a-zA-Z]{22,128}$ pattern and is optional (CMD-2), and nodeId accepts the forms of CMD-3. Extra optional parameters are allowed by CMD-8 and are marked "x-ud": true in the schema.

A tool that the installed milestone does not have yet is not listed. A Figma tool that UI Designer cannot serve is never listed (CMD-6). Under --proposal, tools that are always refused (create_new_file, download_assets, generate_figma_design) are not listed either, and the schema of upload_assets drops its URL form; under --allow, only the listed tools appear.

5.3 Resources#

resources/list lists one ?resource=system entry per .design file in the workspace (up to 50). Resource subscriptions are supported for ?resource=system: a change to the design system sends notifications/resources/updated.

Clients that cannot read resources reach the same content through tools: ud_run system.digest, ud_help plugin-api, and ud_help skill:ui-designer.

5.4 Prompts#

5.5 Finding the live editor#

ud mcp is a long-lived process; it does not hold the document. For every call it resolves the file and then the bridge, the same way every ud command does (CMD-27):

1. Resolve fileKey (path, doc-… id searched among the workspace’s .design files, ud:// link, or the --file default, or the only open design).
2. Look in the bridge folder — $XDG_RUNTIME_DIR/ui-designer, or ui-designer-<uid> in the temporary folder; UD_BRIDGE_DIR overrides — readable only by the user. Each running VS Code window with the extension leaves a file there with the address of its local socket (a Unix socket or a named pipe), a random token, and the paths of the designs it has open. Nothing listens beyond the loopback interface: the only TCP listener is the asset and screenshot server of §5.9, bound to 127.0.0.1 (NFR-4).
3. If a window has the file open, send the command over that socket with the token. The editor queues it with the user’s own edits, applies it, flashes the changed nodes (UI-7) and answers. Reads see unsaved state.
4. Otherwise run headless: load the file with the same document core, take the file lock, apply, write, and release the lock.

The bridge is re-resolved per call, so opening or closing the editor during an agent session just switches mode. ud_run where reports which mode the last call used. ARC-001 specifies the bridge protocol.

5.6 Authentication and licence#

• No login for the MCP server. It is a local process of the user, reached over stdio by the user’s client. The bridge token protects the editor’s socket from other local users.
• Licence. The plan is the one of the extension on this machine (LIC-2). ud mcp is gated exactly like ud, command for command: every read tool — get_metadata, get_screenshot, get_design_context, get_variable_defs, search_design_system, get_libraries, get_motion_context, the get_*/list_* code-map tools, ud_render, ud_lint, ud_help, download_assets, whoami and every read command through ud_run — is free (LIC-5). Mutating calls need the trial or a paid plan; on the Free plan they return isError with code licence (exit 4 from ud) and a hint (“UI Designer Pro unlocks editing; run ‘UI Designer: Sign In’”). whoami reports seat: "view" on Free, so a skill can tell before it starts. Neither ud mcp nor the language model tools of §10 are “AI features” in the sense of LIC-2: that term means the AI panel and the quick actions only, and those need the paid plan or the trial as a whole (§6.7). Agents the user runs through ud mcp or VS Code chat pay nothing beyond what ud itself charges for the same mutation.
• Live editor decides. When the change goes through the bridge, the editor checks the licence; headless, ud checks the same cached licence signature (offline grace, LIC-4).

5.7 Limits#

5.8 Errors#

Errors are tool results with isError: true (CMD-30). The text starts with a code, then a message and a hint; structuredContent carries the same as JSON:

{
  "code": "command",
  "exit": 1,
  "message": "layoutSizingHorizontal: FILL can only be set on children of auto-layout frames",
  "hint": "Append the node to an auto-layout frame first, then set FILL.",
  "script": { "line": 14, "column": 3, "name": "Error" },
  "safeToRetryWithoutCanvasRead": true,
  "documentVersion": 4182
}

5.9 Asset and screenshot results#

get_screenshot, ud_render, download_assets and upload_assets deal in files. Their results name the file and, when something can serve it, a URL; there is no file:// URL anywhere in the interface.

Rules that hold for every URL: loopback only (127.0.0.1, never 0.0.0.0), a 128-bit single-use token in the path, a 10-minute lifetime, a Host header that must match, requests with an Origin header rejected, 10 MB per asset. The server is specified in ARC-001 §9.6 and the hardening in SRS NFR-4. Figma’s skills, which curl the screenshot URL or POST to the upload URL, therefore work unchanged while a server runs; our skills tell the agent to prefer path (or the inline image) and to treat url: null as “read the file”. In the AI panel enableBase64Response is forced on, so the agent never needs the URL at all.