Xcode MCP

You MUST use this skill for ANY Xcode MCP interaction — setup, tool usage, workflow patterns, or troubleshooting.

Xcode ships an MCP server (xcrun mcpbridge, available since Xcode 26.3) that exposes 20 IDE tools to external AI clients. Xcode 27 adds an explicit "Allow external agents to use Xcode tools" gate, the run-agent launch path, and an agent-extension model (custom MCP servers, skills, plug-ins). This skill suite covers setup, tool reference, workflow patterns, and troubleshooting.

mcpbridge requires a running Xcode with a project open — if that's a liability (headless CI, or you don't want to keep Xcode up), the device/simulator half of these operations has a fully Xcode-independent CLI path: devicectl + simctl + Axiom's xcui/xclog/xcsym/xcprof. See axiom-tools (skills/device-control-ref.md). The IDE-authoring tools (build state, render previews, navigator diagnostics) are MCP-only; xcodebuild builds and tests but does not render previews.

When to Use

Use this skill when:

• Setting up Xcode MCP for the first time
• Configuring xcrun mcpbridge for any MCP client
• Using any Xcode MCP tool (file ops, build, test, preview)
• Building, testing, or previewing via MCP tools
• Troubleshooting mcpbridge connection issues
• Window/tab targeting questions
• Permission dialog confusion

Routing Logic

1. Setup/Connection → xcode-mcp-setup

Triggers:

• First-time Xcode MCP setup
• Client-specific config (Claude Code, Cursor, Codex, VS Code, Gemini CLI)
• Connection errors ("Connection refused", "No windows")
• Permission dialog confusion
• Multi-Xcode targeting (MCP_XCODE_PID)
• Schema compliance issues with strict clients
• Giving external agents access to Xcode (Intelligence settings gate)
• Launching an agent via Xcode config (xcrun mcpbridge run-agent)
• Exporting Xcode's skill bundles (run-agent skills export)
• Extending Xcode's agent (per-agent config files, MCP servers, plug-ins)

Read: skills/xcode-mcp-setup.md

2. Using Tools & Workflows → xcode-mcp-tools

Triggers:

• How to build/test/preview via MCP
• Workflow patterns (BuildFix loop, TestFix loop)
• Tool gotchas and anti-patterns
• Window/tab targeting strategy
• When to use MCP tools vs CLI (xcodebuild)
• Destructive operation safety (XcodeRM, XcodeMV)

Read: skills/xcode-mcp-tools.md

3. Tool API Reference → xcode-mcp-ref

Triggers:

• Specific tool parameters and schemas
• Input/output format for a tool
• "How does XcodeGrep work?"
• "What params does BuildProject take?"
• Tool category listing

Read: skills/xcode-mcp-ref.md

Decision Tree

digraph xcode_mcp_router {
    rankdir=TB;
    "User has Xcode MCP question" [shape=ellipse];
    "Setup or connection?" [shape=diamond];
    "Using tools or workflows?" [shape=diamond];
    "Need specific tool params?" [shape=diamond];

    "xcode-mcp-setup" [shape=box];
    "xcode-mcp-tools" [shape=box];
    "xcode-mcp-ref" [shape=box];

    "User has Xcode MCP question" -> "Setup or connection?";
    "Setup or connection?" -> "xcode-mcp-setup" [label="yes"];
    "Setup or connection?" -> "Using tools or workflows?" [label="no"];
    "Using tools or workflows?" -> "xcode-mcp-tools" [label="yes"];
    "Using tools or workflows?" -> "Need specific tool params?" [label="no"];
    "Need specific tool params?" -> "xcode-mcp-ref" [label="yes"];
    "Need specific tool params?" -> "xcode-mcp-tools" [label="general question"];
}

Anti-Rationalization

Conflict Resolution (vs Other Routers)

Example Invocations

User: "How do I set up Xcode MCP with Claude Code?" -> Read: skills/xcode-mcp-setup.md

User: "How do I build my project using MCP tools?" -> Read: skills/xcode-mcp-tools.md

User: "What parameters does BuildProject take?" -> Read: skills/xcode-mcp-ref.md

User: "My mcpbridge connection keeps failing" -> Read: skills/xcode-mcp-setup.md

User: "How do I target a specific Xcode window?" -> Read: skills/xcode-mcp-tools.md

User: "Can I render SwiftUI previews via MCP?" -> Read: skills/xcode-mcp-tools.md (workflow), then skills/xcode-mcp-ref.md (params)

User: "Cursor can't parse Xcode's MCP responses" -> Read: skills/xcode-mcp-setup.md (schema compliance section)

Resources

References: skills/xcode-mcp-setup.md, skills/xcode-mcp-tools.md, skills/xcode-mcp-ref.md, skills/axe-ref.md