Repository navigation
docs: v2 MCP page contradicts config.json and runtime in 4 places #52177
Description
Description
The v2 MCP servers documentation at https://opencode.ai/v2/docs/mcp-servers contradicts the published config schema at https://opencode.ai/config.json and the behavior of the runtime it documents, in four separate places. A student following the v2 docs produces a config that the schema rejects and the runtime does not read as intended.
This is not a matter of opinion about which shape is better. In three of the four cases the live schema and the running runtime agree with each other, and the prose page is the outlier.
The four disagreements, docs versus schema plus runtime 2.0.19:
/v2/docs/mcp-servers |
config.json schema + runtime |
|
|---|---|---|
| server nesting | mcp.servers.<name>; page states "V2 does not place server names directly under mcp" |
flat map on mcp; no servers key exists |
| disabling | disabled: true |
enabled (in both McpLocalConfig and McpRemoteConfig); disabled in neither |
| OAuth fields | client_id, client_secret, callback_port, redirect_uri |
clientId, clientSecret, callbackPort, redirectUri |
| plugins (adjacent page) | plugins |
plugin |
In the three schema-related cases the live schema and the running runtime agree with each other, and the prose page is the outlier. A flat mcp block connects correctly on 2.0.19 - opencode mcp list reports two local servers and one remote server marked disabled, all as configured.
The v2 documentation matches the v2 schema. When prose and schema disagree on a field name, students hit the schema, not the prose, so the docs lose.
The v2 MCP page is wrong in four places relative to the schema and to runtime 2.0.19. The field-name errors are the most costly because a student who follows the docs gets a config that looks plausible and fails quietly.
Plugins
None in opencode.json. A project-local plugin exists at .opencode/plugins/replicate.ts (hand-ported to the v2 API) and is unrelated to this report.
OpenCode version
2.0.19 (OpenCode Desktop)
Steps to reproduce
No response
Screenshot and/or share link
Environment
- opencode version: 2.0.19 (OpenCode Desktop, runtime read from
~/.local/share/opencode/log/opencode.log) - Schema compared against:
https://opencode.ai/config.json, resolved through$defs→ root →properties - Docs page:
https://opencode.ai/v2/docs/mcp-servers - Public CLI for comparison: 1.18.33 (see note below about the version gap)
- OS: Debian GNU/Linux 13 (trixie), x86_64
Note: there is currently no public v2 CLI. https://opencode.ai/install and the opencode-ai npm package only publish the 1.x line (latest 1.18.33), while the Desktop app ships runtime 2.0.19. That means opencode mcp add, which the v2 docs recommend, is not runnable against a v2 runtime today. This is a separate problem and I am not filing it as a bug, but it limits what I could verify from the CLI.
Additional notes
- The failure is quiet in the worst way.
mcp.servers.<name>is not a syntax error, it is a server namedserverswhose value matches no schema branch. Nothing points the student at the real cause. - I have not filed the CLI/version-gap problem noted at the top as a separate issue. If that gap matters, say so and I will write it up.
- Reported against v2 docs on 2026-09-30. If v2 is still unreleased or behind a flag, the schema may be ahead of the docs deliberately — but then the docs should not tell students to use
mcp.servers.
Operating System
Debian GNU/Linux 13 (trixie), x86_64
Terminal
OpenCode Desktop 2.0.19 (Electron, Wayland/KDE) - not a terminal app
Activity
github-actions commentedon Sep 29, 2026
This issue might be a duplicate of existing issues. Please check:
docs: show the OpenCode 2 entry next to the OpenCode 1.x one
neriousy commentedon Oct 20, 2026
Fixed by #55524, released in v2.0.30. The published
config.jsonschema is now generated from the V2 config, so it matches the V2 MCP docs (mcp.servers,disabled, snake_case OAuth fields,plugins) and still accepts the V1 shapes. If you still see a mismatch, comment and we'll reopen.