Xcode MCP Setup: Connect Apple's Built-In Bridge Before Adding 82 Tools
Start with Xcode’s built-in MCP bridge: enable external-agent access in Xcode, run xcrun mcpbridge, keep the intended project open, and verify project context plus a build. Add XcodeBuildMCP only when you need broader simulator, test, preview, or UI-automation workflows. This establishes a known Xcode baseline before expanding the tool surface.
Start with Xcode’s built-in MCP bridge: enable external-agent access in Xcode, run xcrun mcpbridge, keep the intended project open, and verify project context plus a build. Add XcodeBuildMCP only when you need broader simulator, test, preview, or UI-automation workflows. This establishes a known Xcode baseline before expanding the tool surface.
Table of contents
- Should you use Apple's bridge or XcodeBuildMCP?
- How do you enable Xcode's built-in MCP server?
- How do you connect Claude Code or Codex?
- How do you verify project context and builds first?
- When should you add simulator, test, preview, or UI tools?
- How do you fix Xcode selection, project, scheme, permission, and tool-surface failures?
- FAQ
Should you use Apple's bridge or XcodeBuildMCP?
Use Apple’s built-in bridge first, then add XcodeBuildMCP when your work needs a wider workflow surface. The starting sequence is xcrun mcpbridge, the intended project open in Xcode, and a verified project context and build. Apple’s external-agent documentation describes how Xcode exposes its tools to external agents.
Apple’s bridge is the right first connection when the goal is to work with the project already open in Xcode. It keeps the initial setup close to Xcode’s own project, scheme, build, and permission state. Xcode also alerts you when an external agent connects and when that agent is active.
XcodeBuildMCP is a separate community project. Its documentation describes up to 82 tools across 15 workflows, with simulator as the default enabled workflow to limit context. That broader surface can help when the task extends beyond the built-in bridge. See the XcodeBuildMCP directory entry when you are ready to compare its supported workflows.
Choose the built-in bridge first when you are diagnosing connection, project, or build behavior. Choose XcodeBuildMCP after that baseline works and you specifically need simulator, testing, preview, or UI-automation workflows. This staged approach also matches MCP’s client-server model, where each connected tool surface should be understood before it is added to an agent’s context. MCP architecture provides the protocol background.
How do you enable Xcode's built-in MCP server?
Open the intended project in Xcode, enable external-agent access in Xcode’s Intelligence settings, and use xcrun mcpbridge for the agent connection. The project must remain open in Xcode while the external agent uses the bridge.
Follow this order:
- Open the project you intend the agent to inspect or change.
- In Xcode’s Intelligence settings, enable access for external agents.
- Start the client connection using
xcrun mcpbridge. - Watch for Xcode’s connection and active-agent alerts.
The open-project requirement matters because the bridge is tied to Xcode’s current project context. If another project is open, the agent may be connected successfully while operating against the wrong context for your task.
Treat the Xcode alert as part of the connection check. It confirms that an external agent has connected and indicates when that agent is active. If no alert appears, stop and resolve the connection or setting issue before adding another MCP server. The Apple setup instructions contain the client connection details and current setting names.
How do you connect Claude Code or Codex?
For Claude Code or Codex, use Apple’s client-specific direct command for the client you are connecting, with xcrun mcpbridge as the Xcode bridge process. Select the command for the correct client, connect while the intended project is open, and confirm Xcode reports the external agent connection.
Apple documents direct setup commands for both Claude Code and Codex. Use the Claude Code command with Claude Code and the Codex command with Codex; do not exchange client-specific syntax between them. The exact command should come from Apple’s current external-agent setup page rather than from an unrelated MCP configuration example.
For Claude Code users, MCPtrove’s Claude Code client guide is a practical next step after the Apple connection is understood. It can help organize the client-side setup without changing the Xcode-side sequence:
- Open the intended project in Xcode.
- Enable external-agent access.
- Apply the documented command for the client.
- Confirm Xcode’s connection and active-agent alerts.
- Test project context before adding more tools.
Codex follows the same project-first principle, but its registration command is the one Apple documents for Codex. If the connection succeeds but the project context is wrong, return to Xcode selection and the open project before changing client configuration.
How do you verify project context and builds first?
Verify that the intended project and scheme are open in Xcode, then complete a build before adding broader tools. If the project context or build is not correct, fix that baseline while the built-in bridge is still the only added surface.
Use a short verification pass:
- Check the project currently open in Xcode.
- Check that the selected scheme targets the work you intend to perform.
- Ask the connected agent to inspect the current project context.
- Run a build through the established Xcode workflow.
- Record whether the build completes before expanding tool coverage.
A successful connection does not prove that the agent is attached to the right project. Likewise, a tool can be available while the selected scheme or build state is unsuitable for the task. Confirm both independently.
Keep the result narrow: project identity, scheme selection, and build outcome. If any one is unclear, do not add simulator or UI tools yet. The Xcode IDE bridge documentation is useful when you need to understand how an additional Xcode-focused tool surface relates to the IDE.
When should you add simulator, test, preview, or UI tools?
Add simulator, test, preview, or UI tools only after the built-in bridge connects to the intended project and a baseline build succeeds. Use XcodeBuildMCP when the task genuinely requires workflows that the initial bridge does not cover.
XcodeBuildMCP documents a larger collection of tools across 15 workflows, including simulator-oriented work. Its default enabled workflow is simulator, which limits the initial context instead of enabling every workflow at once. Review the XcodeBuildMCP MCP mode documentation before selecting additional workflows.
A practical expansion sequence is:
- Keep Apple’s bridge connected and verified.
- Add the simulator workflow if the task requires device or simulator interaction.
- Add testing tools when the task requires test execution or diagnosis.
- Add preview or UI-automation tools when those surfaces are part of the requested work.
- Recheck project context and build behavior after each expansion.
For test-specific validation, MCPtrove’s guide on how to test an MCP server provides a practical follow-up path. The goal is to make each added tool surface explainable: know which server supplies it, which workflow it supports, and why the task needs it.
How do you fix Xcode selection, project, scheme, permission, and tool-surface failures?
Fix failures in this order: Xcode selection, open project, scheme and build, permission flow, then tool surface. Resolve the narrowest failing layer first, and do not widen the setup until the built-in bridge behaves as expected.
| Symptom | Check first | Next action |
|---|---|---|
| No Xcode connection alert | External-agent access and client-specific command | Enable the setting, use the matching Claude Code or Codex command, then reconnect |
| The wrong project appears active | Intended project open in Xcode | Close the unrelated project context and reopen the intended project |
| The agent reaches Xcode but the build fails | Selected scheme and build result | Correct the scheme or project state, then repeat the baseline build |
| A permission prompt blocks work | Which agent and tool are requesting access | Confirm the intended connection through the normal permission flow; do not bypass permission checks |
| Expected tools are missing | Whether you connected Apple’s bridge or XcodeBuildMCP | Check the selected server and workflow before adding another configuration |
| Too many tools appear | Enabled XcodeBuildMCP workflows | Reduce the surface to the workflow required for the current task |
Xcode selection can affect which installation and project context are available. Project and scheme selection determine what the agent can meaningfully inspect or build. Permissions determine whether the connection is authorized. Tool-surface selection determines which capabilities are actually present. Treat these as separate checks.
MCP security guidance recommends keeping authorization boundaries explicit and avoiding assumptions about connected tools or servers. MCP security best practices is the right reference when a permission or server-identity question remains. For a practical configuration check, use MCPtrove’s config doctor after confirming the Xcode-side baseline.