Xcode MCP 도구가 안 보일 때: mcpbridge 권한과 27.2 GetCodeCoverage

Xcode 27.2 RC(27B48)에 테스트 커버리지를 읽는 GetCodeCoverage가 추가됐습니다. Claude Code나 Codex에 Xcode 도구가 안 보이면 모델보다 mcpbridge 권한과 헤드리스 상태부터 확인해야 합니다. 27.1에서 실행한 명령으로 원인을 가립니다.

Xcode MCP가 노출하는 것

Xcode 27 릴리스 노트는 MCP 서버에 디버거 콘솔 읽기, 활성 런 상태 조작, 스킴과 런 대상 전환, 빌드 설정·컴파일러 플래그·엔타이틀먼트·Info.plist 키 조회와 수정 도구가 추가됐다고 적습니다(176935844). Xcode 27.2 RC(27B48, 2026-10-19 PDT)에는 가장 최근 테스트 결과의 코드 커버리지를 target이나 file로 걸러 보고하는 GetCodeCoverage가 들어갔고(181141715), RenderPreview는 사용 가능한 렌더 대상을 돌려주고 호출자가 대상을 고를 수 있게 바뀌었습니다(186442676).

Xcode 27의 에이전트 기능에는 시뮬레이터 부팅, 앱 설치와 실행, 터치 이벤트 생성, 스크린샷 촬영도 포함됩니다(175179787). 다만 외부 MCP 클라이언트가 실제로 보는 도구 목록은 Xcode 버전과 권한에 따라 달라집니다. 무엇이 보여야 하는지는 tools/list 결과나 Xcode 설정의 도구 목록으로 확인해야 합니다. Xcode 27.2의 .xcproj는 에이전트가 프로젝트 파일을 편집하기 쉽게 만든 포맷입니다. 전환 판단은 /248 글에서 다룹니다.

설정 세 단계

1. Xcode > Settings > Intelligence > Model Context Protocol에서 "Allow external agents to use Xcode tools."를 켭니다.
2. 터미널에서 에이전트에 Xcode 브리지를 등록합니다.
3. 프롬프트를 보내기 전에 Xcode에서 프로젝트나 워크스페이스를 엽니다. Apple 문서도 이 순서를 명시합니다.

claude mcp add --transport stdio xcode -- xcrun mcpbridge
# 또는
codex mcp add xcode -- xcrun mcpbridge

Claude Code의 claude mcp add는 기본으로 local scope에 등록합니다. 명령을 실행한 디렉터리에서만 xcode 서버가 보이므로 여러 프로젝트에서 쓰려면 같은 명령에 --scope user를 붙입니다. 등록은 claude mcp list나 codex mcp list로 확인합니다. Xcode는 외부 에이전트가 연결될 때와 활동할 때 알림을 보여줍니다. 여기까지 했는데 도구가 안 보이면 다음 단계로 갑니다.

먼저 상태 JSON 확인

xcrun mcp-server status는 권한과 실행 상태를 가장 빨리 보여줍니다. --format json을 붙이면 스크립트로 처리하기 쉽습니다.

xcrun mcp-server status --format json

권한이 꺼진 Xcode 27.1에서 실행한 결과는 아래와 같습니다.

{
  "openWorkspaces" : [],
  "permission" : {
    "enabled" : false,
    "unsafeAlwaysAllowAllAgents" : false
  },
  "running" : false
}

permission.enabled가 false면 Xcode 설정의 토글이 꺼졌거나 헤드리스 모드를 켜지 않은 상태입니다. running이 false이고 openWorkspaces가 비어 있으면 Xcode에 프로젝트가 열려 있지 않거나 XcodeService가 떠 있지 않습니다. unsafeAlwaysAllowAllAgents가 true면 모든 에이전트를 무조건 허용한 상태이므로, 개인 맥에서는 바로 끄는 편이 안전합니다.

브리지 핸드셰이크로 원인 확인

에이전트가 "Xcode 도구를 못 찾겠다"고 할 때, 같은 stdio 브리지에 initialize 요청을 직접 보내면 원인이 그대로 나옵니다.

printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"xcode-mcp-check","version":"1.0"}}}' | xcrun mcpbridge

권한이 꺼진 환경에서 돌려본 결과입니다.

{"error":{"code":-32603,"message":"MCP_XCODE_PID is not set and no Xcode tool service could be reached: Xcode MCP access is disabled; turn it on in Xcode Settings > Intelligence > Model Context Protocol, or run `sudo xcrun mcp-server enable`, then retry."},"id":null,"jsonrpc":"2.0"}

MCP_XCODE_PID가 없다는 문구만 보고 PID부터 찾는 경우가 많습니다. 권한이 꺼져 있어도 같은 문장이 나오므로 PID는 Xcode가 여러 개일 때만 설정하고 먼저 권한과 워크스페이스를 확인합니다. 메시지에 원인과 조치가 같이 들어 있습니다. MCP_XCODE_PID가 설정되지 않았고 Xcode 도구 서비스에 닿지 못했다는 뜻이며, 이어지는 문장은 Xcode 설정의 토글 또는 sudo xcrun mcp-server enable을 가리킵니다. 에이전트 로그에서 "도구가 없다"는 말만 보고 모델이나 프롬프트를 바꾸면 이 게이트를 놓치기 쉽습니다.

이 글에서 다루는 연결 실패는 모델 성능 문제가 아니라 권한 게이트인 경우가 많습니다. 에이전트를 바꾸기 전에 이 한 줄을 먼저 돌리는 편이 빠릅니다.

실패 원인별 조치

• 권한 꺼짐: Xcode 설정의 Intelligence에서 외부 에이전트 도구 허용을 켭니다. 헤드리스만 쓸 때는 관리자 권한으로 mcp-server enable을 실행합니다.
• 프로젝트 없음: Xcode에 프로젝트를 엽니다. 헤드리스라면 mcp-server open으로 엽니다.
• PID 불일치: Xcode가 여러 개면 MCP_XCODE_PID를 지정합니다. 하나면 비웁니다.
• 헤드리스 거부: 관리자 권한으로 mcp-server enable을 실행합니다.
• 승인 대기: mcp-server status의 요청 ID로 approve를 실행합니다.
• 폴더 권한 없음: mcp-server allow-folder로 허용합니다.
• 첫 실행 미완료: Xcode를 일반 앱으로 한 번 실행합니다.
• GetCodeCoverage 없음: 27.2 RC 이상인지 확인합니다. 27.1에는 없습니다.
• 그래도 실패: mcp-server show-logs가 가리키는 로그를 봅니다.

목록의 메시지는 Xcode 27.1의 mcp-server와 mcpbridge 도움말, 그리고 직접 재현한 출력에서 가져왔습니다. 헤드리스 실행이 거부되면 Refusing to launch XcodeService: headless MCP access is disabled.가, 첫 실행이 끝나지 않았으면 Refusing to launch XcodeService: the user has not yet completed the Xcode first-launch experience가 로그에 남습니다. 27.2 RC 이후에는 문구가 바뀔 수 있으므로 xcrun mcp-server --help와 xcrun mcpbridge --help를 다시 확인합니다.

헤드리스 모드를 켜는 기준

Xcode를 띄워 두는 대화형 모드는 설정이 단순합니다. 프로젝트를 열고 에이전트가 연결되면 Xcode가 권한을 묻고 승인 뒤에는 같은 창에서 빌드와 디버깅을 합니다. 개인 맥에서 대부분의 작업은 이 모드로 충분합니다.

헤드리스 모드는 Xcode 창 없이 XcodeService를 띄웁니다. 대화형 모드에서 Xcode를 종료하면 브리지 연결도 끊깁니다. 헤드리스 모드는 Xcode 창과 별개로 XcodeService가 남습니다. sudo xcrun mcp-server enable로 켜고 xcrun mcp-server status로 상태를 봅니다. xcrun mcp-server open <경로>로 워크스페이스를 열고 xcrun mcp-server stop으로 멈춥니다. 권한은 에이전트의 코드 서명과 폴더 트리 단위로 적용됩니다. 서명된 에이전트와 폴더만 --always로 오래 유지할 수 있습니다. 서명되지 않은 에이전트에는 --always를 쓸 수 없으므로 --for-24-hours로 승인합니다.

sudo xcrun mcp-server enable --unsafe-always-allow-all-agents는 모든 에이전트를 사전 승인합니다. 이름부터 unsafe입니다. 상시 사용 환경에 쓸 옵션이 아니며 CI처럼 사람이 매번 승인할 수 없는 곳에서만 쓰고 끝나면 sudo xcrun mcp-server disable과 sudo xcrun mcp-server clear-permissions로 되돌립니다.

GetCodeCoverage보다 테스트 실행이 먼저

GetCodeCoverage는 "가장 최근 테스트 결과"의 커버리지를 읽습니다. 테스트를 돌리지 않았거나 커버리지 수집을 꺼 두면 도구가 연결돼 있어도 보여줄 값이 없습니다. Xcode 스킴의 Test 액션에서 Code Coverage의 "Gather coverage for"를 켜거나 터미널에서 xcodebuild test -enableCodeCoverage YES로 실행합니다.

커버리지가 0%로 보이면 도구 연결이 아니라 테스트가 해당 타깃을 실행했는지 먼저 확인합니다. 테스트가 끝난 뒤 에이전트에 "GetCodeCoverage로 App 타겟의 커버리지를 보여줘"처럼 요청합니다. target이나 file로 범위를 좁힐 수 있다는 것이 27.2 RC 릴리스 노트의 설명입니다. 27.1에는 이 도구가 없으므로 tools/list에 안 보이는 것이 정상입니다.

연결 확인과 되돌리기

확인 순서는 네 가지입니다. xcrun mcp-server status --format json에서 권한과 실행 상태를 보고 claude mcp list나 codex mcp list에서 xcode 서버가 enabled로 보이는지 확인합니다. 그다음 에이전트에 빌드나 테스트를 시켜 Xcode가 실제로 반응하는지 봅니다. 마지막으로 xcrun mcp-server show-logs가 가리키는 로그에서 거부 메시지를 찾습니다.

Claude Code에서 등록을 지울 때는 claude mcp remove xcode를 씁니다. 헤드리스 서비스를 끄려면 xcrun mcp-server stop을 실행하고 권한을 모두 지우려면 sudo xcrun mcp-server clear-permissions를 씁니다. Xcode 설정의 토글도 함께 끕니다. Codex의 제거 명령은 codex mcp --help에서 확인합니다.

지금 할 일

개인 맥에서는 Xcode를 열어 두는 대화형 모드로 시작합니다. 에이전트가 Xcode 도구를 못 찾으면 mcp-server status --format json과 mcpbridge 핸드셰이크를 먼저 보고 권한·헤드리스·PID를 차례로 확인합니다. 27.2 RC에서 커버리지를 보려면 테스트를 커버리지 수집과 함께 먼저 돌립니다.

이 글의 명령 출력은 macOS 27.0.1(26A434), Xcode 27.1(27A9275)에서 2026-10-23에 확인한 것입니다.