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.
This commit is contained in:
Wesam Abousaid
2026-05-18 20:00:21 +02:00
parent b170bea020
commit d75be39290
5 changed files with 448 additions and 0 deletions
+62
View File
@@ -0,0 +1,62 @@
# MCP Server Walkthroughs
> Practical setup guides for MCP servers that pair well with OpenCode. New to MCP itself? Read [`docs/mcp.md`](../docs/mcp.md) first.
## Featured servers
| Server | Adds | Type | Walkthrough |
|---|---|---|---|
| **Playwright** | Browser automation — DOM, network, screenshots, accessibility | local | [playwright.md](playwright.md) |
| **Context7** | Live, version-pinned library docs piped into the prompt | remote | [context7.md](context7.md) |
| **Sentry** | Errors, traces, releases | remote (OAuth) | [sentry.md](sentry.md) |
| **Grep by Vercel** | Code search across public GitHub | remote | [grep.md](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:
```json
{
"tools": {
"github_*": false,
"slack_*": false
},
"agent": {
"issue-triager": {
"tools": {
"github_get_issue": true,
"github_list_issues": true
}
}
}
}
```
## Discovery
The [official MCP Registry](https://registry.modelcontextprotocol.io/) lists vetted servers. Search the registry or check the docs for each individual server.
For new servers, also worth checking:
- [github.com/modelcontextprotocol/servers](https://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](https://opencode.ai/docs/mcp-servers).
+97
View File
@@ -0,0 +1,97 @@
# Context7 MCP
> Live, version-pinned library documentation piped into the prompt. Grounds OpenCode's answers in **current** API surfaces — not training-data approximations.
## Why this matters
LLMs hallucinate APIs that don't exist or use APIs that were deprecated three versions ago. Context7 fetches real documentation for the libraries you're using at the **version** you're using, and surfaces it to the model.
## When to reach for it
- Working with a library you don't know well
- Working with a library that's recently changed (new React versions, framework migrations)
- Debugging "this function should exist but it doesn't" confusion
- Writing code for SDKs/APIs the model's training data doesn't cover well
## Setup
Get an API key at [context7.com](https://context7.com).
Add to `opencode.json`:
```json
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"context7": {
"type": "remote",
"url": "https://mcp.context7.com/mcp",
"headers": {
"CONTEXT7_API_KEY": "{env:CONTEXT7_API_KEY}"
}
}
}
}
```
Set the env var in your shell:
```bash
export CONTEXT7_API_KEY=ctx7_...
```
Restart OpenCode. Verify:
```bash
opencode mcp list
```
## Example prompts
```text
use context7 to look up the React Router v7 docs for `loader` functions —
specifically how to handle redirects from a loader
```
```text
I'm migrating from Next.js 14 to 15. Use context7 to find the breaking
changes in the App Router and surface the ones that affect our project.
```
```text
use context7 to check the latest Stripe API for the recommended way to
handle webhook signature verification with raw bodies
```
## Resolve before you query
Context7 resolves a library name + version before fetching docs. Patterns that work:
```text
context7: resolve "next.js" v15 — then look up streaming rendering
context7: resolve "tailwindcss" v4 — show me the breaking changes from v3
```
You can also just name the library; Context7 will resolve to the latest version it knows.
## What it covers
Thousands of libraries — React, Next.js, Vue, Angular, Svelte, Tailwind, TanStack, Prisma, Drizzle, Hono, Fastify, Express, Django, FastAPI, Spring, Rails, etc. — plus most major SaaS SDKs (Stripe, Twilio, Sentry, etc.).
## What it won't do
- Cover your **private** code or internal docs (use Memory MCP or a custom internal MCP for that)
- Replace reading the actual codebase (it grounds in *docs*, not your usage)
- Cover obscure libraries with no real documentation
## Gotchas
- **API key required** — there's a free tier, but you need to sign up.
- **Token budget** — Context7 returns chunks of docs; very chatty queries can push past your context window. Be specific in what you ask for.
- **Version drift** — pin the version explicitly when your repo's `package.json` is behind latest.
## Resources
- [Context7 website](https://context7.com)
- [GitHub: upstash/context7](https://github.com/upstash/context7)
- [List of supported libraries](https://context7.com/libraries) *(check website for current list)*
+93
View File
@@ -0,0 +1,93 @@
# Grep MCP (by Vercel)
> Code search across public GitHub. Useful for "how do real codebases use X?" research without leaving OpenCode.
## When to reach for it
- Researching idiomatic usage of an API or pattern
- Finding examples of a library you're new to
- Comparing implementations across major open-source projects
- Pre-deciding between two patterns by seeing which is more common
## Setup
No API key needed for the public endpoint.
Add to `opencode.json`:
```json
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"gh_grep": {
"type": "remote",
"url": "https://mcp.grep.app"
}
}
}
```
Restart OpenCode. Verify:
```bash
opencode mcp list
```
## Example prompts
```text
use gh_grep to search for "useTransition" usage in React 19 codebases.
Find the 3 most common patterns and summarize when each is used.
```
```text
search github via gh_grep for examples of "drizzle-orm" with
"transaction" — show me how production codebases structure transactions
```
```text
use gh_grep to find how big public Tailwind v4 projects organize their
theme tokens. Pull 3 examples I can browse.
```
## What it can do
- Regex / literal search across public GitHub
- Filter by language, repo, file path
- Return code snippets with surrounding context
- Pagination through large result sets
## What it won't do
- Search private repos (only public)
- Replace GitHub's own search for finding *issues* or *PRs* (use the GitHub MCP for those)
- Grade code quality — you'll see code that's wrong as often as code that's right
## Patterns
### Compare two patterns
```text
use gh_grep to count occurrences of `useFormState` vs `useActionState`
in production React codebases (Next.js 15+). Report the ratio and the
top 5 examples for each.
```
### Validate an approach
```text
I'm thinking of using event sourcing for our audit log. Use gh_grep to
find production codebases doing this in TypeScript, and tell me what
patterns they share. Skip the "hello world" projects.
```
## Gotchas
- **Public only** — anything behind a private repo is invisible.
- **Quality varies** — half of GitHub is half-finished side projects. Filter by repo popularity or maintainer when possible.
- **No semantic search** — it's literal/regex, not "code that does X". Be precise in your queries.
## Resources
- [grep.app](https://grep.app/) — same backing service, web UI
- [Vercel's announcement](https://vercel.com/blog/) — official Vercel posts about Grep
+98
View File
@@ -0,0 +1,98 @@
# Playwright MCP
> Drive a real browser from OpenCode — open pages, click elements, fill forms, take screenshots, capture network requests, inspect accessibility trees.
## When to reach for it
- Visual iteration: implement a UI, take a screenshot, refine
- E2E test scaffolding
- Reading documentation from sites that aren't well-indexed
- Reproducing a bug a user reported with a URL
## Setup
Add to `opencode.json`:
```json
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"playwright": {
"type": "local",
"command": ["npx", "-y", "@playwright/mcp@latest"],
"enabled": true,
"environment": {
"BROWSER_TYPE": "chromium"
}
}
}
}
```
Restart OpenCode. Verify:
```bash
opencode mcp list
```
You should see `playwright` in the list.
## Example prompts
```text
use playwright to open https://example.com and screenshot the navbar
```
```text
use playwright to visit our staging site at https://staging.example.com,
log in with the credentials in @.dev/staging-creds.json, and
verify the dashboard renders without console errors
```
```text
the user reports a bug at https://app.example.com/billing — use playwright to
reproduce: log in, navigate to billing, click "upgrade plan", and report what
happens
```
## Visual-iteration loop
```text
[plan] > here's a mock: [drag mock.png in]
> sketch the HTML/CSS structure that matches
[build] > <Tab>
[build] > implement it under src/components/Dashboard/
[build] > use playwright to render the new component at http://localhost:5173/dashboard
> and screenshot it; compare to the mock
[build] > refine until the screenshot matches
```
Two-three iteration rounds usually closes the gap.
## What it can do
- Open URLs, navigate, fill forms, click, hover, drag
- Take screenshots (full page, viewport, or element-scoped)
- Read DOM (CSS selectors, XPath, ARIA roles)
- Capture network requests/responses
- Inspect console messages
- Run JavaScript in the page context
- Read the accessibility tree
## What it won't do
- Persist browser state across sessions by default (use `--user-data-dir` if you need this)
- Bypass strong bot detection (Cloudflare, etc.)
- Replace a real E2E test suite (use the screenshots and traces to *write* the tests)
## Gotchas
- **First run is slow** — Playwright downloads a browser the first time you invoke it.
- **Headless by default** — you don't see the browser. Pass `BROWSER_HEADED=1` in `environment` to watch it run (useful for debugging).
- **Cross-origin / authenticated flows** — use Playwright's auth-state file pattern; see the upstream docs.
## Resources
- [Source: @playwright/mcp on npm](https://www.npmjs.com/package/@playwright/mcp)
- [Playwright docs](https://playwright.dev/)
- [Visual regression patterns](https://playwright.dev/docs/test-snapshots)
+98
View File
@@ -0,0 +1,98 @@
# Sentry MCP
> Pull errors, traces, and releases from your Sentry org into OpenCode. Useful when investigating a production issue or correlating a deploy with new errors.
## When to reach for it
- Investigating a production error someone pasted a link to
- Auditing recent errors after a deploy
- Correlating a release with a regression
- Tracking down the request trace for a slow endpoint
## Setup
Sentry MCP uses OAuth. OpenCode handles Dynamic Client Registration automatically.
Add to `opencode.json`:
```json
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"sentry": {
"type": "remote",
"url": "https://mcp.sentry.dev/mcp",
"oauth": {}
}
}
}
```
Restart OpenCode, then complete OAuth:
```bash
opencode mcp auth sentry
```
A browser will open. Sign in to Sentry and authorize OpenCode. The credentials are stored locally.
Verify:
```bash
opencode mcp list # should show "sentry" as authenticated
```
## Example prompts
```text
use sentry to fetch the latest 10 errors in the production environment
```
```text
use sentry — pull the error at https://my-org.sentry.io/issues/12345/
and explain what's happening
```
```text
the user got a 500 — request ID is `req_abc123`. find the corresponding
trace in sentry and walk me through what happened
```
```text
we deployed `v2.45.0` 30 minutes ago. use sentry to compare error rates
in the last 30 minutes versus the previous hour — any new error types?
```
## What it can do
- List issues / errors with filtering (project, environment, time range, severity)
- Fetch full error context — stack trace, breadcrumbs, request data, user context
- List recent releases and their error counts
- Fetch traces and spans
- Search issues by message or stack frame
## Common pattern: error → root cause
```text
use sentry to fetch the most recent occurrence of issue PROJ-12345
- Look at the stack trace and identify the failing code
- Open the relevant file (use @ syntax)
- Explain the root cause and propose a fix
```
## What it won't do
- Resolve issues automatically (you wouldn't want it to)
- Create new releases or deploys
- Access projects you're not a member of
## Gotchas
- **OAuth scope** — the OAuth flow grants the same permissions your Sentry user has. Audit before authorizing on shared/admin accounts.
- **Re-auth periodically** — tokens expire. If queries start failing, run `opencode mcp auth sentry` again.
- **Rate limits** — Sentry's API has rate limits. Heavy querying gets throttled.
## Resources
- [Sentry MCP — endpoint and docs](https://mcp.sentry.dev/)
- [Sentry main docs](https://docs.sentry.io/)