You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/installation-guides/install-claude.md
+69-1Lines changed: 69 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -164,7 +164,75 @@ Add this codeblock to your `claude_desktop_config.json`:
164
164
165
165
---
166
166
167
-
## Troubleshooting
167
+
## Xcode (Claude Agent)
168
+
169
+
Xcode's Claude Agent uses the same `.claude.json` configuration format as the Claude Code CLI, but reads it from an Xcode-specific directory rather than the global config location.
> Configurations placed here only affect Claude Agent when launched from Xcode. See [Apple's documentation](https://developer.apple.com/documentation/xcode/setting-up-coding-intelligence#Customize-the-Claude-Agent-and-Codex-environments) for more details.
178
+
179
+
### Remote Server Setup (Recommended)
180
+
181
+
Run the following command in Terminal to add the remote GitHub MCP server:
182
+
183
+
```bash
184
+
claude mcp add-json github '{"type":"http","url":"https://api.githubcopilot.com/mcp/","headers":{"Authorization":"Bearer YOUR_GITHUB_PAT"}}' --config ~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig/.claude.json
185
+
```
186
+
187
+
Or open the file in a text editor and add the `mcpServers` block manually:
188
+
189
+
```json
190
+
{
191
+
"mcpServers": {
192
+
"github": {
193
+
"type": "http",
194
+
"url": "https://api.githubcopilot.com/mcp/",
195
+
"headers": {
196
+
"Authorization": "Bearer YOUR_GITHUB_PAT"
197
+
}
198
+
}
199
+
}
200
+
}
201
+
```
202
+
203
+
### Local Server Setup (Docker)
204
+
205
+
> **macOS note**: Xcode runs with a minimal `PATH` that typically excludes `/usr/local/bin` (Intel) and `/opt/homebrew/bin` (Apple Silicon). Use the full path to `docker` to ensure it can be found. Run `which docker` in Terminal to find the correct path on your system.
206
+
207
+
```json
208
+
{
209
+
"mcpServers": {
210
+
"github": {
211
+
"command": "/usr/local/bin/docker",
212
+
"args": [
213
+
"run",
214
+
"-i",
215
+
"--rm",
216
+
"-e",
217
+
"GITHUB_PERSONAL_ACCESS_TOKEN",
218
+
"ghcr.io/github/github-mcp-server"
219
+
],
220
+
"env": {
221
+
"GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_PAT"
222
+
}
223
+
}
224
+
}
225
+
}
226
+
```
227
+
228
+
### Setup Steps
229
+
1. Create or open `~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig/.claude.json`
230
+
2. Add the configuration block above
231
+
3. Replace `YOUR_GITHUB_PAT` with your actual token
Xcode currently supports two built-in coding agents: **Codex** (powered by OpenAI) and **Claude Agent** (powered by Anthropic). Follow the standard installation guide for each agent, with one important difference: Xcode uses its own isolated configuration directories for each agent, separate from your global config.
4
+
5
+
> Configurations placed in these directories only affect agents when launched from Xcode. See [Apple's documentation](https://developer.apple.com/documentation/xcode/setting-up-coding-intelligence#Customize-the-Claude-Agent-and-Codex-environments) for more details.
Xcode runs with a minimal `PATH` that typically excludes common binary locations. If you are using a local STDIO server (e.g. Docker or a pre-built binary), use the **full path** to the command in your config. Run `which docker` (or `which github-mcp-server`) in Terminal to find the correct path on your system. Common locations:
| Tools not loading | Config placed in wrong directory | Ensure config is in the Xcode-specific path above, not `~/.codex/` or `~/.claude.json`|
37
+
| Command not found (STDIO) | Xcode's PATH excludes binary location | Use the full path (e.g. `/usr/local/bin/docker` or `/opt/homebrew/bin/docker`); run `which docker` in Terminal to confirm |
38
+
| Docker not found | Docker not running | Start Docker Desktop and restart Xcode |
39
+
| Authentication failed | Invalid or expired PAT | Regenerate PAT and update config |
40
+
41
+
## References
42
+
43
+
-[Apple Developer Documentation — Setting up coding intelligence](https://developer.apple.com/documentation/xcode/setting-up-coding-intelligence#Customize-the-Claude-Agent-and-Codex-environments)
0 commit comments