Xcode 26.3 + Claude Agent: Model Swapping,MCP, Skills, and Adaptive Configuration

Unexpectedly, Apple has directly provided support for Claude Code/Codex in Xcode 26.3. With this update, developers can finally use native AI Agents elegantly within Xcode.

Over the past two days, I’ve conducted a series of experiments with this new version, including configuring MCP and writing an adaptive CLAUDE.md. This article uses Claude Code as an example to share some tips that go beyond the official documentation.

🛠️ Hardcore Experiment: Manually Swapping the Latest Model

The claude client version bundled with the Xcode 26.3 RC is 2.1.14, which corresponds to the Opus 4.5 model. However, Anthropic has actually already released the more powerful Opus 4.6 (v2.1.32).

Can we make Xcode run on the latest model?

I tried replacing the claude binary located at ~/Library/Developer/Xcode/CodingAssistant/Agents/Versions/26.3 directly with the latest 2.1.32 version provided by Anthropic.

Result: After setting the Model to Opus in Xcode, asking it what model it is returns 4.6. Considering that the client and model versions are usually tied together, this can be seen as an “unofficial upgrade” method, allowing Xcode to enjoy the capabilities of Opus 4.6 ahead of time.

🔌 Injecting MCP Support into Xcode

By default, Xcode shields developers from MCP (Model Context Protocol) configurations set globally on the system. If you want the built-in Xcode Agent to use custom tools (such as the mail processing tool I use frequently), you need to modify a specific configuration file.

Configuration File Path: ~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig/.claude

Configuration Example:

"projects": {
    "/Users/yangxu/Development/DataNoteV3": {
      "mcpServers": {
        "mail": {
          "type": "stdio",
          "command": "/Users/yangxu/myenv/bin/python3",
          "args": ["/path/to/mail_mcp_server.py"],
          "env": { ... }
        }
      },
      "hasTrustDialogAccepted": true
    }
  }

After configuration, you can verify if the MCP has loaded successfully by typing /context in the Agent panel.

🧩 Locations for Skills and Commands

The Claude Agent in Xcode searches for Skills in the following paths:

1. ~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig/skills
2. /Library/Application Support/ClaudeCode/.claude/skills

The corresponding location for Commands is:

~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig/commands

Simply drag your scripts into these directories and restart Xcode to enable them.

Note: Custom commands do not appear in the / autocomplete menu, but they can be executed by typing the command name directly. To list available skills, use find-skill (without a preceding /).

🔗 Installing via Symlinks

For both Skills and Commands, you can also use symbolic links (symlinks) to map the configurations from your current environment directly to the corresponding Xcode locations.

ln -s ~/.claude/commands ~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig/commands 

🧠 Advanced Tip: Adaptive Claude.md

Since I frequently switch between the Xcode built-in Agent and the Command Line Claude Code, the environmental differences (especially regarding compilation methods) make it difficult to use a single set of prompts. I adopted an “Environment Awareness” strategy.

1. Environment Adaptation

In the root CLAUDE.md, I distinguish whether I am currently inside Xcode or in the terminal by detecting the CLAUDE_CONFIG_DIR environment variable:

## 🔍 Environment Adaptation

This project supports two Claude development environments:
- **Xcode 26.3+ Claude Agent SDK** - Uses Xcode built-in MCP tools
- **Pure Claude Code** - Uses command line Claude Code

### Environment Detection

Judge the current environment by checking the `CLAUDE_CONFIG_DIR` environment variable:

- ✅ **Contains `Xcode/CodingAssistant`** → Use configuration from [CLAUDE-XCODE.md](CLAUDE-XCODE.md)
  - Example: `~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig`
- ❌ **Does not contain or is another path** → Use configuration from [CLAUDE-PURE.md](CLAUDE-PURE.md)
  - Example: `~/.config/claude` or other standard configuration paths

2. Compilation Awareness (Context Awareness)

In the Xcode environment, the multi-Target structure of SPM (Swift Package Manager) often confuses the AI. I added a Scheme checking mechanism to CLAUDE-XCODE.md:

## 🎯 Context-Aware Development Rules

### 1. Auto-Detect Context

When working within an SPM module:
1. Identify which module the current file primarily belongs to (e.g., `AppShared`, `DataNoteCore`).
2. Check if the corresponding Scheme is switched to.
3. If not switched, remind the developer to switch to the corresponding Scheme.

**Prompt Template**:
```
⚠️ Current context primarily involves the [PackageName] module.
Suggested Scheme: [PackageName] or [PackageName]Tests
```

### 2. Check Module-Level CLAUDE.md

After switching the Scheme, check if a module-level configuration exists in the corresponding directory:
- **FileSystem Path**: `Modules/[PackageName]/CLAUDE.md`
- **Xcode Project Path**: `DataNoteV3/Packages/[PackageName]/CLAUDE.md`
- If it exists, combine project-level and module-level instructions for work.

### 3. Prioritize Corresponding SPM Scheme

- ✅ Developing in `AppShared` module → Use `AppShared` Scheme
- ✅ Developing in `DataNoteCore` module → Use `DataNoteCore` Scheme
- ✅ Modifying persistence layer code → Use `DataNotePersistent` Scheme

Final Thoughts

The update to Xcode 26.3 is satisfying in both its effect and direction. If the accuracy of AI code completion can be further improved, Xcode is very likely to regain the initiative in the AI era and become the preferred IDE for Swift developers once again.

Unknown surprises often bring the greatest joy.