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>
MCP Server Walkthroughs
Practical setup guides for MCP servers that pair well with OpenCode. New to MCP itself? Read
docs/mcp.mdfirst.
Featured servers
| 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.jsonentry to hand-edit. To register a server interactively instead, runopencode mcp addand 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:
- github.com/modelcontextprotocol/servers — reference implementations
- The provider's own docs (Sentry, Atlassian, etc. publish their own MCP guides)
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.