AgentLayer▸docs
Connect it

Xcode

Build, test, run and debug Apple apps and Swift packages from a session, through the MCP server that ships with Xcode. macOS only, no key.

The Xcode pack lets your agent build, test, run, screenshot and debug Apple apps and Swift packages. It works through Apple's own Xcode MCP server, running headless, so no Xcode window has to be open.

It goes through an MCP server because the host's shell sandbox blocks Apple's toolchain: xcodebuild, swift build, swift test and simctl all fail inside it. MCP servers run outside that sandbox.

What it gives you

PieceWhat it is
The xcode MCP serverRegistered for this home in <HOME>/.mcp.json. Every Xcode tool is allowed. Only InvokeDebuggerCommand asks first, since the debugger can run shell commands
Shell commandsxcodebuild, xcrun simctl and xcrun xctrace are allowed. Deleting or erasing a simulator, deleting a runtime, and anything that uploads (-exportArchive, altool, notarytool) ask first, so an App Store or TestFlight submission never happens without you
Two coding rulesxcode.md, loaded in every session, and xcode-project.md, loaded when a project file is open. Both land in .claude/rules/ and are never overwritten once there
A repo scaffold, if you want itA fill-in AGENTS.md for an app or a Swift package, the .claude/CLAUDE.md bridge and a .xcode-version pin. An unfilled scaffold is worse than none: the agent reads it as fact

Three details of those permissions, in Claude Code, cover DocumentationSearch, RunCodeSnippet and deleting a simulator runtime.

The pack ships no skills. For those it points the agent at the ones Xcode exports, written by Apple's framework teams.

What it needs

  • macOS with full Xcode 27 or later. The headless server ships there, and the Command Line Tools alone are not enough. There is no fallback for an older Xcode, and the pack is not offered on Windows, WSL2 or Linux. The walk checks only that Xcode is 27 or later, but the xcode.md rule it installs is written for Xcode 27.2: picking a preview's device, for one, needs 27.2.
  • No key, no account, no cost.
  • Three steps only you can run, below. Two need sudo or a running Xcode, and the agent is not allowed to widen its own sandbox.

Switch it on

Run the walk

Run configure-skills and pick Xcode. It checks the Mac and the Xcode version, registers the server, sets the permissions, adds the two rules and offers the repo scaffold.

Add the sandbox exclusion

Allowing a command only stops the prompt. It still runs inside the sandbox, where the toolchain fails. If your home's sandbox is on, merge this into <HOME>/.claude/settings.json. The walk writes the exact block for your settings to <HOME>/.state/updates/xcode-sandbox.md:

"sandbox": {
  "excludedCommands": ["xcrun simctl *", "xcodebuild *", "xcrun xctrace *"]
}

Enable the headless server

In your own terminal, with the folder that holds your Apple projects in place of <code-root>:

sudo xcrun mcp-server enable
sudo xcrun mcp-server allow-folder <code-root> --always
xcrun mcp-server status          # prints the pending agent id
sudo xcrun mcp-server approve <id>

Repeat allow-folder for each folder that holds Apple projects. Apple approves each host separately, so a home that also runs Codex gets a second id on Codex's first connect.

Export Apple's skills

With Xcode open:

xcrun agent plugin path --plugin-format claude

Xcode exports its skills per build, so run this again after every Xcode update. Until then the agent finds no skills folder and says so.

Relaunch

Start your host again from the home. In Claude Code, /mcp should show xcode connected.

If something's off

Most problems are an unfinished headless step, a missing sandbox exclusion, unexported skills, or an Xcode older than 27; find the symptom below.

Turning it off

Run configure-skills, choose Deconfigure a skill pack, then Xcode. It removes the server and the allow rules, keeps the ask rules, and offers to delete the two coding rules. Two things are yours to undo: take the three entries out of sandbox.excludedCommands, and run sudo xcrun mcp-server deny <id> to end this host's access to the headless server.

Where it's used

  • Coding rules: what the two rules hold, and Apple's skills.
  • Codex: how the xcode server and its ask rules reach a Codex session.

On this page