Studio MCP Installation & Setup

Available with MCP Core.

Step 1 — Turn on the MCP Server in Studio

1. In ProtoPie Studio, open Preferences → Labs.

2. Turn on the MCP Server toggle. The server starts immediately — no save or app restart needed.

3. Below the toggle, you’ll see the server status and per-client connection details. Use each copy button to grab the exact command or config.

🔢 About the port — the default port is 9982, but if it’s already in use another port is assigned automatically. Always copy the actual command/URL shown in Labs.

Step 2 — Connect from your AI client

Pick the client that matches your setup. If code and the terminal feel like a hassle, 2-1 (Claude Desktop one-click) is the easiest. Options 2-2 through 2-5 all connect to the same address, http://127.0.0.1:<PORT>/mcp, where <PORT> is the actual port shown in Labs (default 9982).

2-1. Claude Desktop (Chat) — one-click (recommended, easiest)

Connect with a single button — no code or config files.

1. In Studio, turn on Preferences → Labs → MCP Server.

2. On the same screen, click Open in Claude Desktop.

3. Claude Desktop automatically shows a prompt to install the ProtoPie Studio MCP extension (.mcpb). Install it.

   1. The extension auto-detects and connects to the current Studio port — no extra setup.

   
   

   

4. Use it right away in the Claude Desktop chat. On first use, approve the Allow dialog in Studio.

   
   

   

⚠️ Claude Desktop’s Chat mode and Code tab keep separate MCP lists. This one-click extension is for Chat mode; for the Code tab, follow 2-2.

• Manual alternative (when the button isn’t available)

  Chat mode’s claude_desktop_config.json only supports stdio, so an HTTP server goes through the mcp-remote bridge (requires Node.js / npx).

  1. Open claude_desktop_config.json via Settings → Developer → Edit Config:

     • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

     • Windows: %APPDATA%\Claude\claude_desktop_config.json

  2. Add it under mcpServers:

     {
       "mcpServers": {
         "protopie-studio-mcp": {
           "command": "npx",
           "args": ["mcp-remote", "http://127.0.0.1:9982/mcp", "--transport", "http-only"]
         }
       }
     }

     {
       "mcpServers": {
         "protopie-studio-mcp": {
           "command": "npx",
           "args": ["mcp-remote", "http://127.0.0.1:9982/mcp", "--transport", "http-only"]
         }
       }
     }

     {
       "mcpServers": {
         "protopie-studio-mcp": {
           "command": "npx",
           "args": ["mcp-remote", "http://127.0.0.1:9982/mcp", "--transport", "http-only"]
         }
       }
     }

     {
       "mcpServers": {
         "protopie-studio-mcp": {
           "command": "npx",
           "args": ["mcp-remote", "http://127.0.0.1:9982/mcp", "--transport", "http-only"]
         }
       }
     }

     {
       "mcpServers": {
         "protopie-studio-mcp": {
           "command": "npx",
           "args": ["mcp-remote", "http://127.0.0.1:9982/mcp", "--transport", "http-only"]
         }
       }
     }

  3. Save, then fully quit and restart Claude Desktop. Approve Allow on first use.

2-2. Claude Code (terminal CLI, or the Code tab in Claude Desktop)

Connect from the terminal or from Claude Desktop’s Code tab (Claude Code built in) with the same command.

🗂️ Authoring in the Code tab — the Code tab asks you to choose a working directory (folder) first. That folder becomes your workspace, and the MCP server registers to it (local scope). If you switch folders the server may not appear there — use --scope user (below) to make it available everywhere.

1. Move into your project folder (working directory), then run:

   claude mcp add --transport

   claude mcp add --transport

   claude mcp add --transport

   claude mcp add --transport

   claude mcp add --transport

   This registers it for the current project (local scope) only. To use it across all projects, add --scope user:

   claude mcp add --scope user --transport

   claude mcp add --scope user --transport

   claude mcp add --scope user --transport

   claude mcp add --scope user --transport

   claude mcp add --scope user --transport

2. Reload Claude Code, run /mcp, and select protopie-studio-mcp.

3. When Studio shows the Allow / Deny dialog, click Allow.

   
   

   

4. You’re done when protopie-studio-mcp shows as connected in the tool list.

2-3. Codex

Run it in the terminal, or paste the JSON into your config:

codex mcp add protopie-studio-mcp --url

codex mcp add protopie-studio-mcp --url

codex mcp add protopie-studio-mcp --url

codex mcp add protopie-studio-mcp --url

codex mcp add protopie-studio-mcp --url

2-4. Cursor

1. Settings → MCP → + Add new MCP server (or edit your project’s .cursor/mcp.json directly).

2. Add the JSON:

   {
     "mcpServers": {
       "protopie-studio-mcp": {
         "url": "http://127.0.0.1:9982/mcp"
       }
     }
   }

   {
     "mcpServers": {
       "protopie-studio-mcp": {
         "url": "http://127.0.0.1:9982/mcp"
       }
     }
   }

   {
     "mcpServers": {
       "protopie-studio-mcp": {
         "url": "http://127.0.0.1:9982/mcp"
       }
     }
   }

   {
     "mcpServers": {
       "protopie-studio-mcp": {
         "url": "http://127.0.0.1:9982/mcp"
       }
     }
   }

   {
     "mcpServers": {
       "protopie-studio-mcp": {
         "url": "http://127.0.0.1:9982/mcp"
       }
     }
   }

3. Save → connect → approve Allow in Studio on first use.

2-5. VS Code (Agent mode)

1. Cmd/Ctrl + Shift + P → MCP: Add Server → choose HTTP.

2. Enter http://127.0.0.1:9982/mcp as the URL and protopie-studio-mcp as the Server ID, then pick a scope. This saves a servers entry in mcp.json with type: "http" and the url.

3. Start the server, find the tools in Agent mode, and approve Allow on first use.

ℹ️ VS Code note — MCP / Agent mode requires GitHub Copilot to be enabled on your account.

ℹ️ Other MCP clients — paste the JSON from the “Other MCP clients” item in Labs:

Step 3 — Approve the connection (Allow / Deny)

• The first time a client connects, Studio shows an Allow / Deny dialog. Click Allow to connect.

• Before you approve, the connection is temporarily refused — just reconnect (retry) from the client.

Step 4 — Use Studio MCP

Studio MCP acts on the prototype that is open and focused in Studio — there’s no link to paste. With a .pie file open, ask the AI things like:

• “Analyze the interactions in the current prototype.”

• “Add a Tap trigger to this button.”

• “Make a screen where tapping flips the card.”

• “Capture a preview of the current screen.”

Reconnecting the MCP server after updating ProtoPie

After updating the ProtoPie Studio version, you may need to remove and reconnect the existing MCP server so your AI client uses the latest connection and extension information. The exact port may change after an update, so always check the current address in Preferences → Labs before reconnecting.

Claude Desktop (Chat)

If the ProtoPie Studio MCP extension (.mcpb) needs to be updated, reinstall it from the version included with your current ProtoPie Studio app.

1. In Claude Desktop, remove the existing ProtoPie Studio MCP extension.

2. In ProtoPie Studio, go to Preferences → Labs.

3. Click Open in Claude Desktop and install the extension again.

4. Restart Claude Desktop if the updated tools do not appear right away.

5. On first use after reconnecting, approve the Allow dialog in Studio.

Studio updates do not automatically update an already installed Claude Desktop extension.

Claude Code

Remove the existing server, then add it again using the current URL shown in Labs. If you originally registered the server for a specific project, run the commands from that same project folder.

claude mcp remove protopie-studio-mcp
claude mcp add --transport

claude mcp remove protopie-studio-mcp
claude mcp add --transport

claude mcp remove protopie-studio-mcp
claude mcp add --transport

claude mcp remove protopie-studio-mcp
claude mcp add --transport

claude mcp remove protopie-studio-mcp
claude mcp add --transport

If you previously used --scope user or another scope, use the same scope when removing and adding the server again.

claude mcp remove --scope user protopie-studio-mcp
claude mcp add --scope user --transport

claude mcp remove --scope user protopie-studio-mcp
claude mcp add --scope user --transport

claude mcp remove --scope user protopie-studio-mcp
claude mcp add --scope user --transport

claude mcp remove --scope user protopie-studio-mcp
claude mcp add --scope user --transport

claude mcp remove --scope user protopie-studio-mcp
claude mcp add --scope user --transport

After reconnecting, restart Claude Code or reload the MCP connection, then approve the Allow dialog in Studio when prompted.

Codex

Remove the existing server, then add it again using the current URL shown in Labs.

codex mcp remove protopie-studio-mcp
codex mcp add protopie-studio-mcp --url

codex mcp remove protopie-studio-mcp
codex mcp add protopie-studio-mcp --url

codex mcp remove protopie-studio-mcp
codex mcp add protopie-studio-mcp --url

codex mcp remove protopie-studio-mcp
codex mcp add protopie-studio-mcp --url

codex mcp remove protopie-studio-mcp
codex mcp add protopie-studio-mcp --url

Restart Codex or start a new session after reconnecting.

Other MCP clients

Remove the existing protopie-studio-mcp configuration, then add it again using the same setup method for your client. Copy the latest URL or JSON from Preferences → Labs, because the actual port may not be 9982.

If you use both Claude Desktop Chat and Claude Code, reconnect them separately. The Claude Desktop Chat extension and Claude Code MCP registration are managed independently.

Troubleshooting & FAQs

• The AI client won’t connect to ProtoPie. → Make sure you approved the Allow dialog in ProtoPie Studio; before approval, connections are temporarily refused. Even if the client shows an Authenticate button, that doesn’t apply here — use Reconnect (retry) instead.

• Tools are missing or the connection drops. → Check that MCP Server is on under Preferences → Labs, that Studio is running, and that a.piefile is open. If this happened after updating ProtoPie Studio or Studio MCP, follow Reconnect after updating Studio MCP above.

• I don’t see the Open in Claude Desktop button. → Confirm ProtoPie Studio is 10.3.0 or later (the button ships from 10.3.0). On an older version, update, or use the manual alternative (mcp-remote) in 2-1 or another client.

• I added the ProtoPie MCP in Claude Desktop but the tools don’t show. → Chat mode and the Code tab keep separate MCP lists. Add Chat mode via the Open in Claude Desktop extension (.mcpb), and the Code tab via the claude mcp add command. Make sure you added it in the mode you’re using.

• How do I check which extensions (.mcpb) are installed in Claude Desktop (Chat)? → In Claude Desktop, press Cmd + , to open Preferences, then click Extensions to see the list of installed .mcpb extensions.

• The port/address doesn’t match. → The port isn’t always 9982 — copy the actual command/URL shown in Labs. If you see a “port unavailable” message, quit the app holding that port and restart Studio.

• ProtoPie MCP works in one project but not another (Claude Code / Code tab). → Local scope only registers in the folder where you ran the command. Use --scope user to make it available everywhere.

Learn more about Code MCP.