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.

Xcode MCP You MUST use this skill for ANY Xcode MCP interaction — setup, tool usage, workflow patterns, or troubleshooting. Bundled tools on Claude Code: if command v <tool finds nothing (hooks off or bare ), use <plugin root /tools/<tool in place of the bare name; <plugin root is two levels above this skill's Base directory for this skill: path. 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 xcrun mcp server open <project or workspace path , which launches the service if needed. 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 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 xcode mcp MCP tool invocation Build failures diagnosed via CLI axiom build Traditional build debugging Build failures diagnosed via MCP tools axiom xcode mcp MCP workflow patterns 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 workspace?" / "How do I run this without Xcode open?" 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 Skills : skills/xcode mcp setup.md, skills/xcode mcp tools.md, skills/xcode mcp ref.md, skills/axe ref.md

axiom-xcode-mcp