Skip to content

Commit ea5af50

Browse files
JoannaaKLJoannaaKL
authored
Merge branch 'main' into add-get_me-metadata
2 parents 2d354fa + 2dab994 commit ea5af50

3 files changed

Lines changed: 117 additions & 1 deletion

File tree

‎docs/installation-guides/README.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ This directory contains detailed installation instructions for the GitHub MCP Se
1313
- **[OpenAI Codex](install-codex.md)** - Installation guide for OpenAI Codex
1414
- **[Roo Code](install-roo-code.md)** - Installation guide for Roo Code
1515
- **[Windsurf](install-windsurf.md)** - Installation guide for Windsurf IDE
16+
- **[Xcode (Codex & Claude Agent)](install-xcode.md)** - Installation guide for Codex and Claude Agent within Xcode
1617

1718
## Support by Host Application
1819

@@ -32,6 +33,8 @@ This directory contains detailed installation instructions for the GitHub MCP Se
3233
| Windsurf | ✅ | ✅ PAT + ❌ No OAuth | Docker or Go build, GitHub PAT | Easy |
3334
| Copilot in Xcode | ✅ | ✅ Full (OAuth + PAT) | Local: Docker or Go build, GitHub PAT<br>Remote: Copilot for Xcode 0.41.0+ | Easy |
3435
| Copilot in Eclipse | ✅ | ✅ Full (OAuth + PAT) | Local: Docker or Go build, GitHub PAT<br>Remote: Eclipse Plug-in for Copilot 0.10.0+ | Easy |
36+
| Xcode (Codex) | ✅ | ✅ PAT + ❌ No OAuth | Local: Docker (full path required), GitHub PAT<br>Remote: GitHub PAT via `GITHUB_PAT_TOKEN` env var (`bearer_token_env_var`) | Easy |
37+
| Xcode (Claude Agent) | ✅ | ✅ PAT + ❌ No OAuth | Local: Docker (full path required), GitHub PAT<br>Remote: GitHub PAT | Easy |
3538

3639
**Legend:**
3740
- ✅ = Fully supported

‎docs/installation-guides/install-claude.md‎

Lines changed: 69 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -164,7 +164,75 @@ Add this codeblock to your `claude_desktop_config.json`:
164164

165165
---
166166

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.
170+
171+
### Configuration File Location
172+
173+
```
174+
~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig/.claude.json
175+
```
176+
177+
> 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
232+
4. Restart Xcode
233+
234+
---
235+
168236

169237
**Authentication Failed:**
170238
- Verify PAT has `repo` scope

‎docs/installation-guides/install-xcode.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# Install GitHub MCP Server in Xcode
2+
3+
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.
6+
7+
## Configuration Directories
8+
9+
| Agent | Configuration Directory |
10+
|-------|------------------------|
11+
| Codex | `~/Library/Developer/Xcode/CodingAssistant/codex/` |
12+
| Claude Agent | `~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig/` |
13+
14+
Place your MCP server configuration in the relevant directory above rather than the default location used by the standalone CLI.
15+
16+
## Setup Guides
17+
18+
- **[Codex](install-codex.md)** — configure `config.toml` inside `~/Library/Developer/Xcode/CodingAssistant/codex/`
19+
- **[Claude Agent](install-claude.md#xcode-claude-agent)** — configure `.claude.json` inside `~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig/`
20+
21+
## macOS Path Note
22+
23+
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:
24+
25+
| Installation | Typical path |
26+
|---|---|
27+
| Docker (Intel Mac) | `/usr/local/bin/docker` |
28+
| Docker (Apple Silicon) | `/usr/local/bin/docker` |
29+
| Homebrew (Intel Mac) | `/usr/local/bin/` |
30+
| Homebrew (Apple Silicon) | `/opt/homebrew/bin/` |
31+
32+
## Troubleshooting
33+
34+
| Issue | Possible Cause | Fix |
35+
|-------|----------------|-----|
36+
| 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)
44+
- [Codex MCP documentation](https://developers.openai.com/codex/mcp)
45+
- Main project README: [Advanced configuration options](../../README.md)

0 commit comments

Comments
 (0)