Skip to content

cli: mcp list / mcp auth ignore the global config — servers added with --global are invisible #55811

Open

Description

@cladone-com

Summary

opencode mcp add <name> --global --url ... writes the server to
~/.config/opencode/opencode.json, but opencode mcp list and
opencode mcp auth <name> never see it — they only read project-level config.
Adding the exact same server to a project's opencode.json makes both commands
work immediately (after a service restart). opencode service restart does not
fix the global case.

Environment

  • opencode version: 2.0.24
  • OS: Linux 6.18.54.1-microsoft-standard-WSL2 (x64)
  • Terminal: xterm-256color (WSL2)
  • Shell: /bin/bash
  • Install/channel: latest
  • Active plugins: none configured

Reproduction

  1. opencode mcp add myserver --global --url https://mcp.example.com/mcp
    → output: MCP server "myserver" added to ~/.config/opencode/opencode.json
    → file contains "mcp": { "servers": { "myserver": { "type": "remote", "url": "..." } } }
  2. opencode mcp list (run from $HOME or any project) → No MCP servers configured
  3. opencode service restart && opencode mcp list → still No MCP servers configured
  4. Rewrite the global entry in the documented shape
    ("mcp": { "myserver": { ... } }, server name directly under mcp) →
    opencode service restart && opencode mcp list → still No MCP servers configured
  5. Create a project opencode.json with the same server entry (either shape) →
    opencode service restart && opencode mcp list → ⚠ myserver needs authentication
    and opencode mcp auth myserver resolves it correctly.

Expected Behavior

Per the docs, --global makes the server "available in every project";
mcp list and mcp auth <name> should resolve servers from the global config.

Actual Behavior

  • mcp list → No MCP servers configured
  • mcp auth <name> → MCP server not found: <name>
  • consistently reproducible across multiple service restarts, with both config shapes.

Additional Context

  • mcp add --global writes the mcp.servers.<name> shape while
    https://opencode.ai/docs/mcp-servers/ documents <name> directly under mcp
    — the writer and docs disagree; both shapes behave identically in mcp list
    (i.e. ignored) when present in the global file.
  • Workaround: add the server to a project-level opencode.json instead of
    --global, then restart the background service.
  • Discovered while setting up an OAuth-protected remote MCP server (the CLI
    stopped at "MCP server not found" until the project-level config was used).

Activity

  1. opencode-agent commented on Oct 15, 2026

    @opencode-agent
    Contributor

    Thanks for the detailed report and the workaround. I think this is a duplicate of #50710: servers in the global config never reach the running service, so opencode mcp list shows No MCP servers configured every time. It keeps happening after service restarts, whichever config shape you use. That issue's title mentions Windows, but comments there reproduce it on macOS with both the flat mcp.<name> and nested mcp.servers.<name> shapes, so your Linux/WSL2 report on 2.0.24 looks like the same bug.

    Possible duplicates and related issues, most likely first:

    The bot will close this issue as a duplicate in 1 day unless you reply explaining how your problem is different. If you post there, it would help to say whether opencode debug config lists the server while mcp list doesn't, and that a project-level config works for you.

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

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions