Studio MCP 설치 및 설정

Step 1 — Studio에서 MCP Server 켜기

1. ProtoPie Studio에서 Preferences → Labs로 이동합니다.

2. MCP Server 토글을 켭니다. 서버는 즉시 시작되고, 별도의 저장이나 앱 재시작이 필요하지 않습니다.

3. 토글 아래에서 서버 상태 및 클라이언트별 연결 상세 정보를 확인할 수 있습니다. 각 복사 버튼을 눌러 정확한 명령어 또는 설정(config)을 복사해 보세요.

🔢 포트 안내 — 기본 포트는9982이지만, 이미 사용 중인 경우 다른 포트가 자동으로 할당됩니다. 항상 Labs 화면에 표시된 실제 명령어/URL을 복사해 사용하세요.

Step 2 — AI 클라이언트에서 연결하기

사용 중인 환경에 맞는 클라이언트를 선택하세요. 코드와 터미널이 번거롭게 느껴진다면, 2-1(Claude Desktop 원클릭)이 가장 쉽습니다. 2-2부터 2-5까지의 옵션은 모두 동일한 주소인 http://127.0.0.1:<PORT>/mcp로 연결되며, 여기서 <PORT>는 Labs에 표시된 실제 포트 번호(기본값 9982)입니다.

2-1. Claude Desktop (Chat) — 원클릭 (추천, 가장 쉬운 방법)

코드나 설정 파일 없이, 버튼 하나로 연결할 수 있습니다.

1. Studio에서 Preferences → Labs → MCP Server를 켭니다.

2. 동일한 화면에서 Open in Claude Desktop을 클릭합니다.

3. Claude Desktop에 ProtoPie Studio MCP 확장 프로그램(.mcpb) 설치 팝업이 자동으로 표시되면 설치를 진행합니다. (최초 1회만 진행하면 됩니다.)

   1. 확장 프로그램이 현재 Studio 포트를 자동으로 감지하여 연결하므로 별도의 추가 설정이 필요 없습니다.

   
   

   

4. Claude Desktop chat에서 바로 사용해 보세요. 최초 사용 시 Studio에 나타나는 Allow 대화상자를 승인해야 합니다.

   
   

   

⚠️ Claude Desktop의 Chat 모드와 Code 탭은 별도의 MCP 목록을 유지합니다. 이 원클릭 확장 프로그램은 Chat 모드용이며, Code 탭을 사용하려면 2-2 항목을 참고하세요.

• 수동 설정 방법 (버튼을 사용할 수 없는 경우)

  Chat 모드의 claude_desktop_config.json은 stdio 방식만 지원하므로, HTTP 서버 연결에는 mcp-remote 브릿지(Node.js / npx 필요)가 사용됩니다.

  1. Settings → Developer → Edit Config 경로를 통해 claude_desktop_config.json을 열어줍니다:

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

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

  2. 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. 저장 후 Claude Desktop을 완전히 종료하고 다시 시작합니다. 최초 사용 시 Allow를 승인해 주세요.

2-2. Claude Code (터미널 CLI 또는 Claude Desktop의 Code 탭)

동일한 명령어를 사용하여 터미널 또는 Claude Desktop의 Code 탭(Claude Code 내장)에서 연결합니다.

🗂️ Code 탭에서 작업 시 참고 — Code 탭에서는 먼저 작업 디렉토리(폴더)를 선택해야 합니다. 해당 폴더가 워크스페이스가 되며 MCP 서버는 해당 범위(local scope)에 등록됩니다. 다른 폴더로 전환할 경우 서버가 표시되지 않을 수 있으니, 모든 환경에서 사용할 수 있도록 --scope user (아래 참고) 옵션을 활용해 보세요.

1. 프로젝트 폴더(작업 디렉토리)로 이동한 후 다음 명령어를 실행합니다:

   claude mcp add --transport

   claude mcp add --transport

   claude mcp add --transport

   claude mcp add --transport

   claude mcp add --transport

   위 명령어는 현재 프로젝트(local scope)에만 등록합니다. 모든 프로젝트에서 사용하려면 --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. Claude Code를 새로고침한 뒤 /mcp를 실행하고 protopie-studio-mcp를 선택합니다.

3. Studio에 Allow / Deny 대화상자가 나타나면 Allow를 클릭합니다.

   
   

   

4. 도구 목록에서 protopie-studio-mcp가 connected로 표시되면 완료입니다.

2-3. Codex

터미널에서 실행하거나 설정 파일에 JSON을 붙여넣습니다:

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 (또는 프로젝트의 .cursor/mcp.json 파일 직접 수정)로 이동합니다.

2. 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. 저장 → 연결 → 최초 사용 시 Studio에서 Allow 승인.

2-5. VS Code (Agent 모드)

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

2. URL에 http://127.0.0.1:9982/mcp를 입력하고 Server ID에 protopie-studio-mcp를 입력한 뒤 스코프를 선택합니다. 이렇게 하면 mcp.json 파일의 servers 항목에 type: "http" 및 url 정보가 저장됩니다.

3. 서버를 시작하고, Agent 모드에서 도구를 찾은 후, 최초 사용 시 Allow를 승인합니다.

ℹ️ VS Code 참고 사항 — MCP / Agent 모드를 사용하려면 계정에 GitHub Copilot이 활성화되어 있어야 합니다.

ℹ️ 기타 MCP 클라이언트 — Labs의 "Other MCP clients" 항목에서 다음 JSON을 복사하여 붙여넣습니다: { "mcpServers": { "protopie-studio-mcp": { "url": "http://127.0.0.1:9982/mcp" } } }

Step 3 — 연결 승인하기 (Allow / Deny)

• 클라이언트가 처음 연결될 때 Studio에 Allow / Deny 대화상자가 표시됩니다. Allow를 클릭하여 연결합니다.

• 승인하기 전까지는 연결이 임시로 거부됩니다 — 클라이언트에서 reconnect (retry)를 진행해 주세요.

Step 4 — Studio MCP 사용하기

Studio MCP는 Studio에서 열려 있고 활성화된(focused) 프로토타입을 대상으로 동작합니다. 붙여넣을 링크가 필요 없습니다! .pie 파일을 연 상태에서 AI에게 다음과 같이 요청해 보세요:

• "현재 프로토타입의 인터랙션을 분석해 줘."

• "이 버튼에 Tap 트리거를 추가해 줘."

• "탭했을 때 카드가 뒤집히는 화면을 만들어 줘."

• "현재 화면의 프리뷰를 캡처해 줘."

Troubleshooting & FAQ

• 연결이 안 돼요. → Studio에서 Allow 대화상자를 승인했는지 확인해 보세요. 승인 전까지는 연결이 임시로 거부됩니다. 클라이언트에 Authenticate 버튼이 표시되더라도 이는 적용되지 않으므로 Reconnect (retry)를 대신 사용해 주세요.

• 도구가 보이지 않거나 연결이 끊어져요. → Preferences → Labs에서 MCP Server 토글이 켜져 있는지, Studio가 실행 중인지, .pie 파일이 열려 있는지 확인해 보세요. 그래도 해결되지 않으면 Studio와 클라이언트를 재시작합니다. Claude Code에서는 claude mcp list 명령어로 등록 상태를 확인하고 claude mcp get protopie-studio-mcp로 상세 정보를 확인해 보세요. 필요시 claude mcp remove protopie-studio-mcp를 실행한 뒤 다시 추가합니다.

• Open in Claude Desktop 버튼이 안 보여요. → ProtoPie Studio 버전이 10.3.0 이상인지 확인하세요 (해당 버튼은 10.3.0 버전부터 제공됩니다). 이전 버전을 사용 중이라면 업데이트하거나, 2-1 항목의 수동 설정 방식(mcp-remote) 또는 다른 클라이언트를 이용해 주세요.

• Claude Desktop에 추가했는데 도구가 안 나타나요. → Chat 모드와 Code 탭은 별도의 MCP 목록을 관리합니다. Chat 모드는 Open in Claude Desktop 확장 프로그램(.mcpb)을 통해 추가하고, Code 탭은 claude mcp add 명령어로 추가해야 합니다. 현재 사용 중인 모드에 맞게 정상적으로 추가했는지 확인해 보세요.

• Claude Desktop (Chat)에 어떤 확장 프로그램(.mcpb)이 설치되어 있는지 확인하고 싶어요. → Claude Desktop에서 Cmd + , 단축키를 눌러 Preferences를 연 다음, Extensions를 클릭하면 설치된 .mcpb 확장 프로그램 목록을 확인할 수 있습니다.

• 포트/주소가 일치하지 않는 것 같아요. → 포트 번호가 항상 9982인 것은 아닙니다. Labs 화면에 표시된 실제 명령어/URL을 복사하세요. “port unavailable”(포트를 사용할 수 없음) 메시지가 뜨는 경우, 해당 포트를 점유 중인 앱을 종료한 후 Studio를 재시작해 보세요.

• 특정 프로젝트에서는 작동하지만 다른 프로젝트에서는 작동하지 않아요. (Claude Code / Code 탭) → 로컬 스코프(Local scope)는 명령어를 실행한 폴더에만 등록됩니다. 모든 위치에서 사용하려면 -scope user 옵션을 사용해 보세요.

Code MCP에 대해 더 알아보기