/axiom-xcode-mcp

name: axiom-xcode-mcp
description: Use when connecting to Xcode via MCP, using xcrun mcpbridge or the headless mcp-server, or working with ANY Xcode MCP tool (XcodeRead, BuildProject, RunSomeTests, RenderPreview). Covers setup, tool reference, workflows, troubleshooting.
license: MIT

Xcode MCP

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

Xcode ships an MCP server exposing IDE tools to external AI clients. `xcrun mcpbridge` is the stdio transport clients register, available since Xcode 26.3. Xcode 27 adds an explicit "Allow External Agents to Use Xcode Tools" setting, the `run-agent` launch path, an agent-extension model (custom MCP servers, skills, plug-ins), and a headless server. This skill suite covers setup, tool reference, workflow patterns, and troubleshooting.

**On Xcode 26.x, mcpbridge requires a running Xcode with a project open.** If that's a liability, 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)`.

**That constraint is gone on Xcode 27.** `xcrun mcp-server` runs the tool service with Xcode.app closed — `sudo xcrun mcp-server enable`, then `start` and `open <path>`. Clients still register `xcrun mcpbridge`; the bridge is the transport, `mcp-server` is the service. Apple's tool schemas describe `workspaceIdentifier` as "used in headless mode", so headless is a supported model rather than a workaround.

Choose between MCP and the CLI tools (`devicectl`, `simctl`, and Axiom's `xcui`/`xclog`/`xcsym`/`xcprof`) on **capability, not uptime**. `xcui` asserts, waits, toggles accessibility settings, and computes VoiceOver announcements, and none of them need `sudo` — which still matters in CI, where the headless server's sudo opt-in may not be available. The IDE-authoring tools (build state, render previews) remain 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
• Workspace targeting questions
• Permission dialog confusion
• Driving simulator input with AXe (`tap`/`type`/`swipe`) -> read `skills/axe-ref.md`

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 workspaces are currently open.")
• 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 (`xcrun 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
• Workspace targeting strategy; headless bootstrap (open or create a workspace)
• 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

| Thought | Reality | |---------|---------| | "I'll just use xcodebuild directly" | MCP gives IDE state, filtered compiler diagnostics, and rendered previews that CLI doesn't expose | | "I already know how to set up MCP" | Client configs differ. Permission dialog behavior is specific. Check setup skill. | | "I can figure out the tool params" | Tool schemas have required fields and gotchas. Check ref skill. | | "One workspace is open, so I can skip the identifier" | `workspaceIdentifier` is required anyway, despite being absent from every `required` list. | | "This is just file reading, I'll use Read tool" | XcodeRead sees Xcode's project view including generated files and resolved packages |

Conflict Resolution (vs Other Routers)

| Domain | Owner | Why | |--------|-------|-----| | MCP-specific interaction (mcpbridge, mcp-server, MCP tools, workspace identifiers) | **axiom-xcode-mcp** | MCP protocol and tool-specific | | Xcode environment (Derived Data, zombie processes, simulators) | **axiom-build** | Environment diagnostics, not MCP | | Apple's bundled documentation (for-LLM guides/diagnostics) | **axiom-apple-docs** | Bundled docs, not MCP tool | | `DocumentationSearch` MCP tool usage specifically | **axiom