docs: add installation guides for Zed and OpenCode#2535
Open
jluocsa wants to merge 1 commit into
Open
Conversation
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.
Contributor
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_serversconfig shape, remote + Docker local, verification, tool-permission notes, troubleshooting). - Added a new installation guide for OpenCode (
mcpconfig 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. |
Comment on lines
+14
to
+59
| ## 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"}}'.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds two new installation guides under
docs/installation-guides/for MCP host applications that were missing documentation:install-zed.md-- the Zed editor.install-opencode.md-- the OpenCode terminal agent.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:
context_serverssettings key (notmcpServers), and expectscommandas a string plus a separateargsarray. It also introduced anmcp:<server>:<tool>permission key format in v0.224.0 that users need to know about to grant approval per-tool.mcpkey with a requiredtypediscriminator ("local"/"remote"),commandas a single array (executable + args),environmentinstead ofenv, automatic OAuth that needs"oauth": falseto opt out, and a{env:VAR}string-interpolation pattern. The OpenCode docs specifically call out that the GitHub MCP server can blow the context window, so the OpenCode guide includes the per-agent tool-gating pattern recommended by their docs.What's in the guides
Each guide covers:
https://api.githubcopilot.com/mcp/with a PAT in theAuthorizationheader.ghcr.io/github/github-mcp-server.opencode mcp list,opencode mcp debug, Zed Agent Panel indicator dot).Index/table updates
I also updated:
docs/installation-guides/README.md-- added both hosts to the installation-guides index list and to the "Support by Host Application" table.README.md-- added both hosts to the "Install in other MCP hosts" (VS Code section) and "Install in Other MCP Hosts" (Claude section) lists.Out of scope
script/generate-docsdoes not need to run.mcp-installdeeplink schemes the way Cursor/VS Code do; the guides instead point at the Zed extension gallery (where a community-maintained GitHub MCP extension already exists) and OpenCode's standard config-file flow.