Skip to content

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

Merged
aanbrn merged 2 commits into
mainfrom
fix-the-global-mcp-config-guidance
Oct 1, 2026
Merged

aanbrn merged 2 commits into
mainfrom
fix-the-global-mcp-config-guidance

Conversation

@aanbrn

@aanbrn aanbrn commented Oct 1, 2026

Copy link
Copy Markdown
Owner

Summary

Fixes the repository's guidance for the global OpenCode MCP config so it produces a shape both OpenCode lines load.

IDEA's AI could not start: its ACP session launches OpenCode 1.18.15 (a 1.x binary, from JetBrains' registry), which
exits on the v2-only spellings — Unrecognized key: permissions, then mcp.servers / Missing key mcp.servers.enabled.
The repo's own instructions produced exactly that shape.

  • .opencode/skills/setup-agent-tools/SKILL.md — both steps and the Notes lead with the flat mcp entry in the global
    config; --global for the CLI route (opencode mcp add defaults to the project config and writes the servers
    nesting); a repair offer for an existing mcp.servers nesting; anomalyco/opencode#49904 cited with its retire-when.
  • README.md — the global-config snippet back to the flat mcp map.
  • AGENTS.md — the tooling bullet, the V1-shape note (extended to the global config and the 1.x ACP agent, with the
    #49904 citation in a file upstreamReferences scans), the mcp add probe passage, and the version-pinned
    debug config claims re-stated for 2.0.21.

OpenSpec change: openspec/changes/fix-the-global-mcp-config-guidance (skip_specs: no capability spec describes the
skill or the config shape). Upstream: commented on anomalyco/opencode#49904 with the 1.x impact and a reproduction;
the schema half is the already-open #43748.

Test plan

  • ./gradlew check -PskipITs -Pcoverage.gate.enabled=false is green
  • spotlessApply run after the final edit to a Spotless-owned file (and spotlessCheck green)
  • Behavior change went through an OpenSpec change (with its archive commit on this PR)
  • The per-unit lesson-capture ran — recorded as task 2.2 in the change's tasks.md with the applied AGENTS.md
    delta (+8 lines: the monitored-corpus rule and the probe-write hazard)

Evidence:

  • The documented shape (flat mcp + permission) loads under 1.x — the ACP binary stays alive — and under 2.x
    (opencode debug config exits 0); the control (the same 1.x binary against mcp.servers) exits 1.
  • opencode debug config on 2.0.21 lifts flat entries into mcp.servers.<name> with no materialized disabled key and
    masks the credential value — both version-pinned claims updated from the v2.0.15 wording.
  • openspec validate --all: 25 passed, 0 failed.
  • Quick review clean after five rounds, all findings fixed.

aanbrn added 2 commits October 1, 2026 07:34
IntelliJ IDEA's AI could not start: its OpenCode ACP agent is 1.x
(1.18.15) and rejects the v2-only spellings in the global config
(permissions; the mcp.servers nesting). The repository's own guidance
produced that shape, so the setup skill, the README snippet, and four
AGENTS.md sites now lead with the flat mcp map plus permission -- the
one shape both lines load. The skill also offers to flatten an existing
mcp.servers nesting and cites anomalyco/opencode#49904 with a
retire-when clause.

OpenSpec change: openspec/changes/fix-the-global-mcp-config-guidance
(skip_specs -- no capability spec describes the skill or the config shape)
skip_specs: no delta to sync, so the archive is the change dir move.
@aanbrn
aanbrn merged commit 6e251ad into main Oct 1, 2026
1 check passed
@aanbrn
aanbrn deleted the fix-the-global-mcp-config-guidance branch October 1, 2026 00:38
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.

1 participant