Files
opencode-primer/mcp-servers/README.md
Wesam AbousaidandClaude Opus 4.8 29a69a35b0 docs: refresh for OpenCode v1.16.2 and fix correctness bugs
Update the guide to the current release (v1.16.2, 2026-06-05), verified
against opencode.ai/docs and github.com/anomalyco/opencode.

Correctness fixes:
- Plugins: tool.execute.before/after and shell.env are top-level hooks
  with an (input, output) signature, not event.type values. Rewrite both
  shipped example plugins plus the docs/migration examples so they fire.
- Permissions: bash glob maps resolve last-matching-rule-wins (catch-all
  "*" first), not most-specific-wins. Fix prose, reorder examples, and fix
  the shipped opencode.json (rm -rf* deny was shadowed by a later rm *).
- Drop non-existent permission keys repo_clone/repo_overview (15 keys, not
  17); fix steps (integer), deprecate maxSteps/tools, move reasoningEffort
  into model options; fix the `mise` install command.

Currency updates:
- v1.15.4 -> v1.16.2; add v1.16 highlights and a changelog section.
- Refresh OpenCode Zen lineup/pricing (Claude Opus 4.8, gpt-5.4,
  gemini-3.5-flash, qwen3.7, grok-build-0.1; correct free-tier IDs).
- Add `opencode mcp add`, run --replay, extra skill paths, shift+tab, and
  native GitHub commands; correct the specialist-prompt count; bump dates.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-08 19:00:39 +02:00

2.6 KiB

MCP Server Walkthroughs

Practical setup guides for MCP servers that pair well with OpenCode. New to MCP itself? Read docs/mcp.md first.

Server Adds Type Walkthrough
Playwright Browser automation — DOM, network, screenshots, accessibility local playwright.md
Context7 Live, version-pinned library docs piped into the prompt remote context7.md
Sentry Errors, traces, releases remote (OAuth) sentry.md
Grep by Vercel Code search across public GitHub remote grep.md

When to add an MCP server

  • Your AI needs external state (browser, DB, ticketing, error tracker)
  • You repeatedly run the same external CLI/API from within OpenCode prompts
  • You want OpenCode to act on a system, not just describe it

If everything you need is already in local files, you probably don't need MCP yet.

💡 Each walkthrough below shows the opencode.json entry to hand-edit. To register a server interactively instead, run opencode mcp add and answer the prompts.

Cost of adding a server

MCP tools land in the model's tool surface every turn. A heavy server (say, a full GitHub integration with 40 tools) can eat 10K+ tokens of context just to describe the available tools. Don't add a server you won't use, and disable tools you don't need with the tools map:

{
  "tools": {
    "github_*": false,
    "slack_*": false
  },
  "agent": {
    "issue-triager": {
      "tools": {
        "github_get_issue": true,
        "github_list_issues": true
      }
    }
  }
}

Discovery

The official MCP Registry lists vetted servers. Search the registry or check the docs for each individual server.

For new servers, also worth checking:

General troubleshooting

Problem Try
Server won't connect opencode mcp debug <name>
OAuth flow stuck opencode mcp logout <name> then opencode mcp auth <name>
Tools missing in the model surface Check the tools map and the agent's tools override
Local server fails on Windows Make sure the command array uses npx with -y, and that Node 18+ is on PATH
Timeouts Bump timeout (default 5000ms) under the server's config

📚 Full MCP guide in OpenCode: opencode.ai/docs/mcp-servers.