Figpea MCP

What figpea-mcp MCP server does

The figpea-mcp MCP server connects an AI agent to a live Figpea editor running in a browser. It supports viewing, inspecting, and exporting PSD, Adobe XD, Figma, SVG, and PDF files. The bridge runs on the local machine, and the documented flow keeps design files from leaving that machine.

The server exposes a small fixed set of MCP tools plus a universal dispatcher for the editor's contract surface:

• open_editor returns a port, token, and pairing URL.
• status reports bridge details, pairing state, connected-tab metadata, and available connection slots.
• figpea_skill returns the agent guidance fetched from the paired editor origin, and can work without a paired tab.
• figpea_describe exposes documentation for editor groups and methods.
• figpea_call invokes a selected editor method with its group, method name, and arguments.
• select_tab switches the target tab when multi-slot mode is enabled.

How it works

At startup, the bridge binds to loopback at 127.0.0.1 and creates a per-run pairing token. The server prints a pairing URL to stderr. Opening that URL in a browser causes the Figpea editor tab to connect back to the bridge over a local WebSocket. An agent can also call open_editor to obtain the URL programmatically.

The default bridge accepts one editor tab. If a contract call arrives before pairing, the response includes a no_tab error and a pairing URL. Connection status includes details such as the last connection event, the tab's contract version, and the observed origin.

For multiple tabs, start the bridge with --bridge-slots=multi or set FIGPEA_BRIDGE_SLOTS=multi. Each tab receives a separate connection ID, and select_tab determines which tab receives later calls. The tabs represent separate documents; this mode is not collaborative editing.

Setup and configuration

A standard stdio configuration starts the package with npx:

{
  "mcpServers": {
    "figpea": {
      "command": "npx",
      "args": ["-y", "figpea-mcp"]
    }
  }
}

The -y option suppresses the installation prompt for a non-interactive client process. After startup, open the printed pairing URL, or ask the agent to call open_editor.

The optional FIGPEA_EDITOR_URL variable changes the editor origin, which is useful for pointing at a local development editor. The --port=<n> option selects a port in the applicable mode. Running npx figpea-mcp --http provides a second MCP entry point over a loopback HTTP endpoint; it uses the same tools and requires the per-run token in the x-figpea-token header.

Tools and capabilities

figpea_call is the main execution interface. It accepts an editor group, method, and argument list, and can also read a JSON file for a method's top-level array argument through _opsFile. figpea_describe can return the complete group index, one group's methods, or a single method's parameters and result documentation.

status identifies the connected tab and lists available connections. In multi-slot mode, select_tab({connectionId}) directs later calls to a chosen connection. The figpea_skill response identifies the editor-origin URL from which its skill reference was loaded.

Limitations and notes

The figpea-mcp MCP server is local-only in its documented bridge setup: the bridge binds to loopback and does not widen its listener to a public interface. A token belongs to one server run, so an older pairing URL becomes stale after restarting the server.

The default configuration permits one tab and refuses a second connection without displacing the existing tab. Multi-slot mode must be enabled before select_tab is registered. HTTP mode is an alternate transport to the same server surface, not an additional set of editor capabilities.