docs: add installation guides for Zed and OpenCode - #2535
Conversation
Sorry, something went wrong.
There was a problem hiding this comment.
Pull request overview
Adds missing documentation for installing/configuring the GitHub MCP Server in two additional MCP host applications (Zed and OpenCode), and wires those guides into the repo’s existing installation-guide indexes so they’re discoverable.
Changes:
- Added a new installation guide for Zed (context_servers config shape, remote + Docker local, verification, tool-permission notes, troubleshooting).
- Added a new installation guide for OpenCode (mcp config shape, remote + Docker local, verification/CLI commands, per-agent tool gating pattern, troubleshooting).
- Updated the top-level README and the installation-guides index README to include both hosts in lists/tables.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
| README.md | Adds OpenCode/Zed links to the two “other MCP hosts” guide lists for discoverability. |
| docs/installation-guides/README.md | Adds OpenCode/Zed to the installation guide index and support matrix table. |
| docs/installation-guides/install-zed.md | New Zed-specific setup guide covering remote + local Docker configuration, verification, permissions, and troubleshooting. |
| docs/installation-guides/install-opencode.md | New OpenCode-specific setup guide covering remote + local Docker configuration, verification/CLI usage, per-agent tool gating, and troubleshooting. |
Sorry, something went wrong.
| ## Remote Server (Recommended) | ||
|
|
||
| Uses GitHub's hosted server at `https://api.githubcopilot.com/mcp/`. Edit your [OpenCode config](https://opencode.ai/docs/config/) (typically `~/.config/opencode/opencode.json`, or `opencode.json` in your project root) and add the following under `mcp`: | ||
|
|
||
| ```json | ||
| { | ||
| "$schema": "https://opencode.ai/config.json", | ||
| "mcp": { | ||
| "github": { | ||
| "type": "remote", | ||
| "url": "https://api.githubcopilot.com/mcp/", | ||
| "enabled": true, | ||
| "oauth": false, | ||
| "headers": { | ||
| "Authorization": "Bearer YOUR_GITHUB_PAT" | ||
| } | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| Replace `YOUR_GITHUB_PAT` with your [GitHub Personal Access Token](https://github.com/settings/tokens). The `oauth: false` setting disables OpenCode's automatic OAuth discovery and tells it to use the PAT in `Authorization` instead — without this, OpenCode may try the OAuth flow first. | ||
|
|
||
| ### Using an environment variable for the PAT | ||
|
|
||
| OpenCode supports environment-variable interpolation in config values via `{env:VAR_NAME}`. To avoid putting your PAT directly in `opencode.json`: | ||
|
|
||
| ```json | ||
| { | ||
| "$schema": "https://opencode.ai/config.json", | ||
| "mcp": { | ||
| "github": { | ||
| "type": "remote", | ||
| "url": "https://api.githubcopilot.com/mcp/", | ||
| "enabled": true, | ||
| "oauth": false, | ||
| "headers": { | ||
| "Authorization": "Bearer {env:GITHUB_PERSONAL_ACCESS_TOKEN}" | ||
| } | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| Set `GITHUB_PERSONAL_ACCESS_TOKEN` in your shell environment before starting OpenCode. | ||
|
|
There was a problem hiding this comment.
Why not just use opencode mcp add as mentioned in https://opencode.ai/docs/cli/#mcp ?
After all, https://github.com/github/github-mcp-server/blob/main/docs/installation-guides/install-claude.md prefers to use claude mcp add-json github '{"type":"http","url":"https://api.githubcopilot.com/mcp","headers":{"Authorization":"Bearer YOUR_GITHUB_PAT"}}'.
Sorry, something went wrong.
There was a problem hiding this comment.
Good call — that's a fair parallel with the Claude guide. The PR has already merged, but a follow-up adding an opencode mcp add example alongside the JSON config would be very welcome. Happy to review if you'd like to open one. Thanks for flagging!
Sorry, something went wrong.
There was a problem hiding this comment.
Good call — that's a fair parallel with the Claude guide. The PR has already merged, but a follow-up adding an opencode mcp add example alongside the JSON config would be very welcome. Happy to review if you'd like to open one. Thanks for flagging!
I'm actually still waiting for the improvements in anomalyco/opencode#29827. It might be better to shelve the improvements on the documentation side of the GitHub MCP server.
Sorry, something went wrong.
Adds two new installation guides under docs/installation-guides/ covering MCP host applications that are not yet documented:
- install-zed.md: covers Zed's 'context_servers' settings key (command + args shape), the official GitHub MCP extension as an easier alternative, remote/local setup, the 'mcp:<server>:<tool>' permission key format introduced in Zed v0.224.0, and OAuth-vs-PAT trade-offs.
- install-opencode.md: covers OpenCode's 'mcp' config block (type-discriminated local/remote, command-as-array, 'environment' instead of 'env'), the 'oauth: false' opt-out needed when using a PAT, the '{env:VAR}' interpolation pattern, and the per-agent tool-gating pattern recommended for token-heavy servers like GitHub.
Also adds both hosts to:
- docs/installation-guides/README.md installation-guides index and the support-by-host-application table.
- README.md 'Install in other MCP hosts' and 'Install in Other MCP Hosts' lists.
Closes github#2531.
SamMorrowDrums
left a comment
There was a problem hiding this comment.
Pure docs addition — two new install guides (OpenCode and Zed) plus index/README entries. Both guides are accurate against the hosts' real config schemas (Zed context_servers with command string + args array; OpenCode mcp with type discriminator and single-array command). Sensible callouts on PAT vs OAuth, toolset filtering for context window, and Docker requirements. LGTM.
Sorry, something went wrong.
Summary
Adds two new installation guides under docs/installation-guides/ for MCP host applications that were missing documentation:
Both guides follow the established pattern of the existing installation guides (Cursor, Cline, Windsurf, Antigravity, etc.): prerequisites, remote-server-recommended path, local Docker path, verify steps, host-specific quirks, and troubleshooting.
Closes #2531.
Why these two
The two hosts have notably different MCP config shapes from the IDEs already covered, and both have shipped users hitting setup issues:
What's in the guides
Each guide covers:
Index/table updates
I also updated:
Out of scope