MCP: invalid location of mcp when used --global #49904

Activity

1. aanbrn commented on Sep 30, 2026

   

   aanbrn

   on Sep 30, 2026

   More actions

   Reproduced on 2.0.21 (macOS, arm64; Homebrew opencode-v2). Adding --global writes mcp.servers — and when the config already has the flat mcp map, it nests servers inside that map (abridged; the command pretty-prints with expanded command arrays):

   mkdir -p /tmp/fh/.config/opencode
   cat > /tmp/fh/.config/opencode/opencode.jsonc <<'JSON'
   { "$schema": "https://opencode.ai/config.json",
     "mcp": { "github": { "type": "local", "command": ["gh", "mcp"] } } }
   JSON
   HOME=/tmp/fh opencode mcp add --global probe -- gh mcp
   # the file then contains, under "mcp":
   #   "github":  { "type": "local", "command": ["gh", "mcp"] }
   #   "servers": { "probe": { "type": "local", "command": ["gh", "mcp"] } }

   Why it matters beyond the shape: the result is unloadable by the 1.x line — which is what npm opencode-ai@latest (1.18.34; no 2.x versions are published under that name) and JetBrains' ACP integration (1.18.15) still distribute. A 1.x binary exits 1 against that config:

   Error: Configuration is invalid at /tmp/fh/.config/opencode/opencode.jsonc
   ↳ Expected { readonly "type": "local", ... } | { readonly "type": "remote", ... }, got {"probe":{"type":"local","command":["gh","mcp"]}} mcp.servers
   ↳ Missing key mcp.servers.enabled
   

   A pure top-level mcp.servers fails identically; a flat mcp map exits 0 under 1.x. So the flat form — the one #52177 reports the 2.0.19 runtime reads, and the form a flat-shape project config uses — is the one both lines accept.

   This broke IntelliJ IDEA's AI in practice: its ACP session launches opencode 1.18.15, which first exits on a V2 permissions array (Unrecognized key: permissions) and, once that is converted to the 1.x permission shape, on the mcp.servers entry written by mcp add.

   Suggested fix: when the file uses the flat mcp map, write a flat entry (mcp.<name>) rather than adding a servers key — or, when the file already uses that map, warn before writing.

   Related: #52177 (the V2 MCP docs page disagrees with the published schema and the runtime on this shape) and #43748 (the published $schema is a hybrid V1 shape, so editors flag valid V2 configs).
2. aanbrn

   added a commit that references this issue on Oct 1, 2026

   Keep the global MCP config loadable by both OpenCode lines (#466)

   ...

   6e251ad
3. yaohuangguan commented on Oct 2, 2026

   

   yaohuangguan

   on Oct 2, 2026

   More actions

   I reproduced this on current v2. The CLI always writes mcp.servers.<name>, while the config normalizer intentionally accepts both the legacy flat mcp.<name> shape and the native V2 nested shape.

   I'm going to keep new/native configs on mcp.servers, but preserve an existing flat MCP map when adding another server so a shared global config does not become a mixed shape that 1.x cannot load. I'll add regression coverage for both shapes.
4. yaohuangguan commented on Oct 2, 2026

   

   yaohuangguan

   on Oct 2, 2026

   More actions

   Implementation is now in #52667. It preserves an existing flat MCP map, while new/native V2 configs continue to use mcp.servers; the added tests cover both shapes and the real --global reproduction passes.
5. rekram1-node commented on Oct 15, 2026

   

   rekram1-node

   on Oct 15, 2026

   Contributor

   More actions

   Thanks for the report! This is working as intended. In OpenCode V2, MCP servers go under mcp.servers, so opencode mcp add --global writes the correct shape:

   {
     "mcp": {
       "servers": {
         "my-server": {
           "type": "remote",
           "url": "https://mcp.example.com/mcp"
         }
       }
     }
   }

   The older shape, with servers directly under mcp, is from V1. V2 still reads those entries and migrates them, so existing configs keep working, but new entries use mcp.servers.

   See the V2 docs for the full config reference: https://opencode.ai/v2/docs/mcp-servers

   Closing this. If a server added this way doesn't connect, please open a new issue with your config and the output of opencode mcp list.
6. rekram1-node

   closed this as not plannedon Oct 15, 2026