Sam Morrow
fab5fc5ff2
* docs: lead local/stdio install with OAuth login Surface OAuth 2.1 login as a first-class option above the Personal Access Token in the README install section and in every local-capable installation guide, each in that client's own config syntax, linking to the dedicated docs/oauth-login.md guide. The github.com OAuth example needs no token; in Docker it publishes a fixed callback port to loopback (-p 127.0.0.1:8085:8085). The PAT block is retained below it and noted as taking precedence over OAuth. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs(oauth): correct PKCE/client-secret explanation The previous "How it works" text claimed PKCE removes the need for a client secret. In practice GitHub requires the client secret at the token endpoint for both OAuth Apps and GitHub Apps, and the implementation sends it alongside the PKCE verifier (Manager.oauth2Config populates ClientSecret; flow.go exchanges with VerifierOption). The secret is baked into the distributed binary and is not truly confidential; PKCE is what actually secures the flow. Reword to reflect this accurately. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs: don't frame OAuth login as github.com-only The intro line said "On github.com you can skip the token entirely", which implied OAuth login only works on github.com. OAuth works on GitHub Enterprise too — you just supply your own app credentials there. Reword to lead with OAuth as the mechanism and scope the zero-config claim correctly: on github.com the official image already includes the app credentials, so the user provides none. Enterprise / bring-your-own-app is covered by the linked OAuth guide. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
48 lines
3.2 KiB
Markdown
48 lines
3.2 KiB
Markdown
# Install GitHub MCP Server in Xcode
|
|
|
|
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.
|
|
|
|
> 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.
|
|
|
|
## Configuration Directories
|
|
|
|
| Agent | Configuration Directory |
|
|
|-------|------------------------|
|
|
| Codex | `~/Library/Developer/Xcode/CodingAssistant/codex/` |
|
|
| Claude Agent | `~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig/` |
|
|
|
|
Place your MCP server configuration in the relevant directory above rather than the default location used by the standalone CLI.
|
|
|
|
## Setup Guides
|
|
|
|
- **[Codex](install-codex.md)** — configure `config.toml` inside `~/Library/Developer/Xcode/CodingAssistant/codex/`
|
|
- **[Claude Agent](install-claude.md#xcode-claude-agent)** — configure `.claude.json` inside `~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig/`
|
|
|
|
## macOS Path Note
|
|
|
|
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:
|
|
|
|
| Installation | Typical path |
|
|
|---|---|
|
|
| Docker (Intel Mac) | `/usr/local/bin/docker` |
|
|
| Docker (Apple Silicon) | `/usr/local/bin/docker` |
|
|
| Homebrew (Intel Mac) | `/usr/local/bin/` |
|
|
| Homebrew (Apple Silicon) | `/opt/homebrew/bin/` |
|
|
|
|
> **Logging in with OAuth?** You can run the local server with no PAT — it opens a browser login on first use and keeps the token in memory only. With Docker this needs a fixed callback port published to loopback (`-p 127.0.0.1:8085:8085 -e GITHUB_OAUTH_CALLBACK_PORT` with `GITHUB_OAUTH_CALLBACK_PORT=8085`); a native binary uses a random loopback port and needs no extra configuration. See **[Local Server OAuth Login](../oauth-login.md)**.
|
|
|
|
## Troubleshooting
|
|
|
|
| Issue | Possible Cause | Fix |
|
|
|-------|----------------|-----|
|
|
| Tools not loading | Config placed in wrong directory | Ensure config is in the Xcode-specific path above, not `~/.codex/` or `~/.claude.json` |
|
|
| 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 |
|
|
| Docker not found | Docker not running | Start Docker Desktop and restart Xcode |
|
|
| Authentication failed | Invalid or expired PAT | Regenerate PAT and update config |
|
|
|
|
## References
|
|
|
|
- [Apple Developer Documentation — Setting up coding intelligence](https://developer.apple.com/documentation/xcode/setting-up-coding-intelligence#Customize-the-Claude-Agent-and-Codex-environments)
|
|
- [Codex MCP documentation](https://developers.openai.com/codex/mcp)
|
|
- Main project README: [Advanced configuration options](../../README.md)
|