Claude Code Xcode Plugin: Install, Connect, and Fix MCP Errors

Connect Claude Code to Xcode using Apple's marketplace plugin or manual MCP registration. Check the local exporter and active Xcode installation, enable external agents, verify a real build, diagnose missing tools, and connect Codex without confusing plugin scope or model billing.

Contents
Claude Code Xcode Plugin: Install, Connect, and Fix MCP Errors

Claude Code can edit Swift files yet still lack access to Xcode builds, tests, and previews. On your Mac, enable external-agent access in Xcode and open your project before connecting Claude Code. Install xcode@claude-plugins-official when its local exporter works; otherwise use Apple’s documented xcrun mcpbridge route.

The setup below follows the official documentation available as of 2026-11-16. Apple’s external-agent guide covers the permissions and direct MCP connection.

Check your Mac’s selected Xcode before installing

Use a full Xcode installation and a current Claude Code CLI. The marketplace entry obtains its plugin from the Xcode tools on your Mac; installing the marketplace package does not supply a missing Xcode installation.

In Bash, from your app’s repository, check the CLI version and selected developer directory:

claude --version
xcode-select --print-path

The developer directory should belong to the Xcode installation you intend to use. A result of /Library/Developer/CommandLineTools identifies the standalone command-line tools package, not the Xcode app. Apple’s command-line tools settings guide explains this distinction.

Next, run the exact command used by the marketplace:

xcrun agent plugin path --plugin-format claude

A successful exporter prints an absolute plugin-directory path. Keep that directory intact: the marketplace uses mode: "link", which loads the generated files in place.

Claude Code added command-based plugin sources in 2.1.229, according to its official changelog. Use a current release rather than pinning that historical version. For Xcode, require the exporter check to pass; do not assume that an installation with mcpbridge also provides agent plugin path.

When claude itself is missing, complete the Claude Code installation and first-run checks before diagnosing Xcode.

Enable external agents and open the project

Give the external process access through Xcode’s Intelligence settings. This is separate from installing a Claude Code plugin.

  1. Open Xcode > Settings > Intelligence.
  2. Under Model Context Protocol, set Allow External Agents to Use Xcode Tools to While Xcode is Open or Always.
  3. Open the project or workspace you want the agent to use.

Choose While Xcode is Open for this interactive workflow. Keep the project open while you perform the checks below. Apple documents an Xcode notification when an external agent connects and while it is active.

Keep your working model connection, too. An eligible Claude subscription uses its plan allowance; a Claude Console account provides separately billed API usage. Choose the former when your existing allowance is sufficient, or the latter for usage-based billing. See Claude Code authentication and check Anthropic’s regional eligibility before buying access.

BetterToken is another pay-as-you-go API route, using your own account and console-created key with its documented Claude Code configuration. Choose it for separately funded API access; model billing units, payment channels, and fees need checking before payment. It does not include a Claude subscription. Check current model prices and confirm payment conditions in the console.

Choose the plugin or the direct MCP connection

Use the plugin when your Xcode exporter works. Use direct MCP registration when you want only the bridge connection or the exporter is unavailable but mcpbridge works.

The official marketplace entry lists Apple Inc. as the author. Its source runs xcrun agent plugin path --plugin-format claude locally. The direct command instead registers xcrun mcpbridge as an MCP server.

That is a packaging difference, not evidence that one route has better build results. A plugin can carry skills and other components alongside MCP configuration. Inspect your installed package rather than assuming a fixed skill list or complete feature parity. Start with one route so failures remain easy to isolate.

Install xcode@claude-plugins-official

Start Claude Code from your repository with claude. At its interactive prompt, not in Bash, enter:

/plugin install xcode@claude-plugins-official

Review the installation and choose local scope for an initial, repository-only trial. Approve the displayed exporter only after checking it matches the command above. Follow any reload instruction in the installation summary, or start a new Claude Code session.

Then inspect the installation from Bash in the same repository:

claude plugin list
claude plugin details xcode@claude-plugins-official

Check that the package is enabled and inspect its component inventory. The plugin command reference documents this inventory, including any skills and MCP servers.

In Claude Code, run /mcp and inspect the plugin-provided server. Plugin MCP servers use a scoped name in the form plugin:<plugin>:<server>; do not require the bare name xcode.

For scope changes or removal later, use the plugin installation, verification, and removal guide.

Register xcrun mcpbridge directly

Use Apple’s exact registration command in Bash, from the repository where you will run Claude Code:

claude mcp add --transport stdio xcode -- xcrun mcpbridge
claude mcp list
claude

This registers a local-process connection over standard input and output. The server name you chose is xcode. In the interactive session, run /mcp and inspect its connection status before asking for a build.

The default MCP scope is local to the project. Claude Code stores that configuration in ~/.claude.json, associated with the project, rather than sharing it automatically with every repository. The MCP scope documentation explains the distinction.

Registration alone is not the success check. Confirm that the server connects and can act on the project open in Xcode.

Verify one build before requesting app changes

Ask for a build without edits first. This separates connection problems from changes the model might introduce.

Use this prompt in the connected Claude Code session:

Use Xcode tools to identify the open project and active scheme.
Build that scheme for an available iOS Simulator destination.
Do not edit files.
Report the build result and the first actionable error, if any.

Look for an actual Xcode tool call and its returned build result. Xcode should also report the external agent’s activity. A returned compiler error can confirm that the connection works, even though the app does not build yet; fix that project error rather than reinstalling the plugin.

The marketplace describes scheme builds, runs, and tests; SwiftUI preview rendering; simulator and device operations; build logs and diagnostics; and Apple documentation search. Available operations still need checking against your installed Xcode and connected tool list.

For example, Apple’s Xcode 27 release notes document simulator booting, app installation and launch, touch input, and screenshots. Check that the corresponding tools are exposed before requesting a UI-interaction task.

After the build check, ask the agent to identify available tests and run one relevant test or suite. For a view change, ask it to render an existing SwiftUI preview and inspect the returned preview artifact. Require the test result or preview itself, not merely a statement that the task succeeded.

Keep the first task narrow. Before adding repeated builds and large diagnostic outputs, use the MCP context-cost workflow to compare a repeatable task.

Fix the failing layer, not the whole installation

Choose the branch that matches your result. These checks are alternatives, not a sequence everyone must run.

xcrun cannot locate agent or mcpbridge

Check xcode-select --print-path first. An older selected Xcode or the standalone command-line tools package can make your terminal use a different toolchain from the Xcode window you opened.

If the intended app is installed at /Applications/Xcode.app, select it in Bash:

sudo xcode-select --switch /Applications/Xcode.app

Use the actual installation path when it differs. This changes the default developer directory, so confirm the selection and rerun the failed command.

If agent plugin path remains unavailable but the direct MCP connection works, use that connection. If neither works, install or select an Xcode build providing the required tools before changing Claude Code’s model credentials.

claude mcp list has no bare xcode entry

For the direct route, run the command from the repository where you added the server. A project-local registration will not automatically appear in another repository.

For the plugin route, check claude plugin list, then /mcp inside Claude Code. Look for a plugin-scoped server rather than a bare xcode entry. If the plugin is installed but inactive, enable it through /plugin and start a new session.

If the installer cannot find the marketplace entry, refresh its catalog from the Claude Code prompt:

/plugin marketplace update claude-plugins-official

Retry the installation after the refresh. If the marketplace itself is missing, run /plugin marketplace add anthropics/claude-plugins-official first. Anthropic’s plugin troubleshooting guide distinguishes these catalog errors from unsupported source types.

The server connects, but the project is unavailable

Open the intended project in Xcode and recheck Allow External Agents to Use Xcode Tools. For this workflow, leave Xcode open, start a fresh agent session, and repeat the build-without-edits prompt.

A server entry proves configuration exists; the returned project and build result prove that the agent reached the intended work. If the tool returns a project-specific error, use that diagnostic as your next step.

Connect Codex to the same Xcode project

Codex users can use Apple’s direct MCP route without installing the Claude Code marketplace plugin. Keep the same Xcode permission setting and project open.

With Codex CLI installed and authenticated, run these commands in Bash:

codex mcp add xcode -- xcrun mcpbridge
codex mcp list
codex

Inside Codex, use /mcp to inspect active servers, as described in OpenAI’s MCP documentation. Then use the same build-without-edits prompt and inspect the returned result.

To revoke external-agent access later, return to Xcode’s Intelligence settings and select Never under Allow External Agents to Use Xcode Tools.

Ready to optimize your LLM workflow?

Join thousands of developers building faster, smarter, and more cost-effective AI applications with BetterToken.

Get Started for Free