Files
opencode-primer/mcp-servers
Wesam Abousaid d75be39290 feat(mcp-servers): walkthroughs for Playwright, Context7, Sentry, Grep
Each walkthrough follows the same template: when to reach for it, setup
(verbatim opencode.json snippet), example prompts, capabilities and
limitations, gotchas, resources.

- playwright.md: browser automation — visual iteration loop, e2e
  scaffolding, bug repro from a URL
- context7.md: live, version-pinned library docs piped into the prompt,
  with the "resolve first, query second" pattern
- sentry.md: errors / traces / releases via OAuth (DCR), with the
  error-to-root-cause pattern
- grep.md: code search across public GitHub via the Vercel-hosted MCP

README.md ranks "when to add a server" against the cost of the extra
tokens it puts in the model's context every turn, with a tools-map
example for disabling chatty MCP tools per agent.

All endpoint URLs and package names link-checked at commit time.
2026-05-18 20:00:21 +02:00
..

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.

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.