Overlay MCP

MCP, short for Model Context Protocol, is a standard way for AI tools to connect to external apps and data sources. An MCP server gives an agent a structured set of tools and resources it can use while working.

Overlay exposes the active editor canvas through a local MCP server. Connect an MCP client to the server to let an agent inspect the current design, read your design system, update nodes, verify changes with screenshots, and register components in your registry.

IMPORTANT

The MCP server runs from the Overlay Studio VS Code extension. Open Overlay in your editor first; the endpoint is only available while the extension is active.

Connect automatically

Open the Overlay side panel (the welcome screen shown before you open the editor, or while it's collapsed) and expand Connect your agent. Overlay detects supported AI coding agents installed on your machine and lets you connect with one click:

Client	How it connects
Claude Code	Click Connect. Overlay runs claude mcp add for you, scoped to your user config.
Codex	Click Connect. Overlay runs codex mcp add for you.
Cursor	Click Add to Cursor. Overlay opens a cursor:// install link — approve it in Cursor, then restart Cursor to apply. Only shown when Overlay is running inside Cursor.

The panel also shows which agents are already connected. If your client isn't listed, expand Using another agent? for a copyable command and config snippet — this is the same information as the manual setup steps below.

TIP

The server must be running for a client to connect to it — open the Overlay editor first, then use the panel.

Connect manually

Follow the steps below to connect the MCP server to your AI app. For help, contact [email protected].

Claude Code

claude mcp add --transport http --scope user overlay http://127.0.0.1:19521/mcp

Codex

codex mcp add overlay --url http://127.0.0.1:19521/mcp

This writes a streamable_http entry to ~/.codex/config.toml:

[mcp_servers.overlay]
url = "http://127.0.0.1:19521/mcp"

Cursor

Add an MCP server entry to your client using the default endpoint:

{
  "mcpServers": {
    "overlay": {
      "type": "streamableHttp",
      "url": "http://127.0.0.1:19521/mcp"
    }
  }
}

Other platforms

Setup instructions for other platforms will be added shortly. If you have questions, contact [email protected].

Use the MCP server

Once set up, you should be able to ask AI assistants to complete tasks in the editor.

Most MCP clients expose Overlay's prompts as slash commands, namespaced under the server name: /overlay/design, /overlay/handoff-selection, /overlay/register-component, /overlay/import-component. Starting your message with /overlay/design tells the agent it's working in Overlay, so you don't need to spell that out yourself:

/overlay/design Create a hero component for a Stripe-like SaaS website.

If your client doesn't support slash commands for MCP prompts, plain language works too — just be explicit that the change should happen in Overlay:

Create a hero component for a Stripe-like SaaS website in Overlay.

IMPORTANT

Without a prompt, AI assistants may not know that you are working in Overlay. For a plain-language request, explicitly ask them to make the change "in Overlay." For example:

❌ "Create a hero component"

✅ "Create a hero component in Overlay"

Available tools

Overlay registers editor tools for common canvas operations:

Tool	Purpose
get_artboards	List top-level artboards on the canvas
get_component	Read a component subtree as JSX
get_selected_components	Read the current selection as JSX
get_node_context	Inspect a node's parent chain, sibling position, and child count
find_nodes	Search nodes by name, text, type, component key, or parent
upsert_component	Create or replace JSX in the active document
update_node_style	Apply a style patch to a node
take_screenshot	Capture a node screenshot for visual verification
get_annotations	Read the user's hand-drawn canvas annotations as an image
init_overlay_config	Create any missing .overlay config files (see below)
get_design_system	Return the registered components (keys, source files, prop schemas) and icon libraries
get_jsx_authoring_guide	Return the full ruleset for producing valid canvas JSX — allowed elements, supported Tailwind, and rules for importing existing code (see below)

init_overlay_config

Unlike the other tools, init_overlay_config doesn't need an open editor document — it writes directly to the workspace. It creates .overlay/components.jsonc and/or .overlay/config.jsonc when they're missing, and never overwrites or edits an existing config. Agents call this before registering a component for the first time in a workspace. See Importing components for the full registration flow.

get_jsx_authoring_guide and get_design_system

Agents call get_jsx_authoring_guide once per session, before generating or importing any JSX, and get_design_system before emitting or importing components, so they reuse your real design system instead of guessing at it. Both are plain fetch tools with no side effects. get_design_system replaced an earlier overlay://design-system MCP resource — resources are surfaced inconsistently across clients, so this data is now served as a tool instead, which every client can call reliably.

Prompts

Overlay also registers MCP prompts your client can surface as quick-start actions. Clients that support MCP prompts as slash commands namespace them under the server name, so they show up as /overlay/<prompt>:

Prompt	Purpose
/overlay/design	Carries out whatever task is currently set up in the Overlay editor. Follow it with your request, e.g. /overlay/design build a pricing table — no need to say "in Overlay"
/overlay/handoff-selection	Implements the currently selected canvas components/pages into your codebase
/overlay/register-component	Registers a React component in .overlay/components.jsonc — see Importing components
/overlay/import-component	Brings a component or page from your codebase onto the canvas as editable nodes — see Importing components

Change the port

If port 19521 is already in use, change the Overlay extension setting:

{
  "overlay.mcpPort": 19522
}

Then update the MCP client URL to match:

{
  "mcpServers": {
    "overlay": {
      "type": "streamableHttp",
      "url": "http://127.0.0.1:19522/mcp"
    }
  }
}

Set overlay.mcpPort to 0 only if you want Overlay to choose a random available port. Random ports are best for development because your MCP client config must use the actual port printed by the extension.

Troubleshooting

If the MCP client cannot connect:

• Make sure the Overlay Studio extension is running.
• If using Cursor MCP and it doesn't find the Overlay server, go to the Cursor Settings page and click "reload" on the Overlay MCP.
• Open the Overlay editor for the workspace you want to control.
• Check that the MCP client URL uses the same port as overlay.mcpPort.
• Use http://127.0.0.1:<port>/mcp, not the workspace folder path.
• If you changed extension settings, reload the editor window and reconnect the MCP client.

For more information or issues, please contact [email protected].