Skip to content

docs: add installation guides for Zed and OpenCode#2535

Open
jluocsa wants to merge 1 commit into
github:mainfrom
jluocsa:docs/install-zed-and-opencode
Open

docs: add installation guides for Zed and OpenCode#2535
jluocsa wants to merge 1 commit into
github:mainfrom
jluocsa:docs/install-zed-and-opencode

Conversation

@jluocsa
Copy link
Copy Markdown
Contributor

@jluocsa jluocsa commented May 23, 2026

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:

  • Zed uses a context_servers settings key (not mcpServers), and expects command as a string plus a separate args array. It also introduced an mcp:<server>:<tool> permission key format in v0.224.0 that users need to know about to grant approval per-tool.
  • OpenCode uses an mcp key with a required type discriminator ("local" / "remote"), command as a single array (executable + args), environment instead of env, automatic OAuth that needs "oauth": false to 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:

  • Remote server (recommended) using https://api.githubcopilot.com/mcp/ with a PAT in the Authorization header.
  • Local server (Docker) using ghcr.io/github/github-mcp-server.
  • Host-specific gotchas that I confirmed against the host's official docs (Zed's MCP docs and OpenCode's MCP servers docs).
  • Verify steps using each host's actual UI / CLI commands (opencode mcp list, opencode mcp debug, Zed Agent Panel indicator dot).
  • Troubleshooting for the most common configuration mistakes specific to each host.

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

  • No code changes; docs-only.
  • No tool-schema changes -- script/generate-docs does not need to run.
  • Did not add UI deeplink-install buttons. Zed and OpenCode do not currently expose mcp-install deeplink 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.

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.
@jluocsa jluocsa requested a review from a team as a code owner May 23, 2026 18:43
Copilot AI review requested due to automatic review settings May 23, 2026 18:43
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

doc: Add installation guides for Zed and OpenCode

2 participants