Skip to content

XCODE_IDE_MCPBRIDGE.md

Latest commit

 

History

History
60 lines (36 loc) · 2.44 KB

XCODE_IDE_MCPBRIDGE.md

File metadata and controls

60 lines (36 loc) · 2.44 KB

Xcode IDE MCP Bridge (xcrun mcpbridge)

XcodeBuildMCP can optionally proxy Xcode’s built-in “Xcode Tools” MCP service via Xcode 26’s xcrun mcpbridge.

This enables IDE-only tools (e.g. Preview rendering, Issue Navigator queries, documentation search, project navigator operations) that are not available via xcodebuild.

Enable

Add xcode-ide to enabledWorkflows in .xcodebuildmcp/config.yaml:

schemaVersion: 1
enabledWorkflows: ["simulator", "debugging", "xcode-ide"]

If the workflow is not enabled, XcodeBuildMCP does not start the bridge.

MCP tools in xcode-ide workflow

When xcode-ide is enabled and mcpbridge is available, XcodeBuildMCP exposes two gateway tools:

  • xcode_ide_list_tools: Lists remote tools from Xcode's MCP server (name, description, schemas).
  • xcode_ide_call_tool: Calls a remote Xcode tool by name with a JSON argument payload.

These tools are stable and manifest-managed. They are shown when the xcode-ide workflow is enabled in MCP runtime; calls will fail until mcpbridge is available.

CLI behavior is unchanged and continues to use dynamic xcode_tools_* proxy naming.

Bridge debug tools

These tools are stable and do not depend on Xcode’s tool catalog, but they are intentionally hidden unless you enable debugging (debug: true) because they are primarily for troubleshooting:

  • xcode_tools_bridge_status: Shows mcpbridge availability, connection state, last error, and proxied tool count.
  • xcode_tools_bridge_sync: One-shot connect + re-sync (use this if Xcode prompts blocked startup sync).
  • xcode_tools_bridge_disconnect: Disconnect and unregister proxied xcode_tools_* tools.

Trust prompts / troubleshooting

Xcode may show trust/allow prompts when the bridge connects and/or when tools are invoked.

Recommended flow:

  1. Launch Xcode.
  2. Start XcodeBuildMCP with xcode-ide enabled.
  3. If xcode_ide_list_tools fails, temporarily set debug: true and call xcode_tools_bridge_status to inspect bridge health, then retry after approving prompts.

Targeting a specific Xcode instance (optional)

If you need to scope the bridge to a specific Xcode instance, XcodeBuildMCP forwards these environment variables to the bridge:

  • XCODEBUILDMCP_XCODE_PID → MCP_XCODE_PID
  • XCODEBUILDMCP_XCODE_SESSION_ID → MCP_XCODE_SESSION_ID

Dev probe script

For manual verification against a real Xcode install:

npx tsx scripts/probe-xcode-mcpbridge.ts