- Bump every version pin, pricing table, and model ID to the verified 2026-07-05 state (v1.17.13): Claude Fable 5 / Sonnet 5 on Zen, new free tier, deprecation sunset table, v1.17.x changelog section - Cover gaps: OpenCode Go vs Zen billing, Anthropic subscription-login removal (PR #18186), MCP resources, --mini mode, --auto flag, yolo mode - Fix correctness bugs: command-template !`cmd` syntax in docs and .opencode/commands, protect-secrets regex missing 'cat .env', dual plugin exports, quickstart PATH fix, Playwright MCP flags, ctrl+d keybind conflict, agent/command required-field claims - Fix links: cursor.com, windsurf.com, platform.claude.com, code.claude.com, opencode.ai/discord, Vercel Grep announcement - Rebrand: banner (Images/banner.svg), 1280x640 social preview asset, hero redesign with star CTA, ecosystem stats, private vulnerability reporting channel, CI-matching local checks, MD060 lint opt-out
7.6 KiB
Model Context Protocol (MCP)
Mental model: MCP is the universal connector — one open protocol that lets OpenCode talk to external tools (browsers, databases, search engines, ticket systems) without writing custom integrations for each. Think USB-C for AI integrations.
Why MCP exists
Before MCP, every AI app needed a custom integration for every tool — N × M brittle one-off connections:
flowchart LR
subgraph Before[Before MCP - N x M integrations]
direction LR
A1[App 1] --- T1[Postgres]
A1 --- T2[GitHub]
A1 --- T3[Slack]
A2[App 2] --- T1
A2 --- T2
A2 --- T3
A3[App N] --- T1
A3 --- T2
A3 --- T3
end
MCP collapses this to N + M: each app implements MCP once, each tool exposes MCP once.
flowchart LR
subgraph After[With MCP - N + M integrations]
direction LR
B1[App 1] --> MCP{{MCP Protocol}}
B2[App 2] --> MCP
B3[App N] --> MCP
MCP --> S1[Postgres]
MCP --> S2[GitHub]
MCP --> S3[Slack]
end
For OpenCode that means you get a Playwright MCP server, a Sentry MCP server, a Postgres MCP server, etc. — and any of them works without OpenCode-specific glue code.
Local vs. remote servers
OpenCode supports both, declared in opencode.json under mcp.
Local servers — spawned subprocess
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"playwright": {
"type": "local",
"command": ["npx", "-y", "@playwright/mcp@latest"],
"enabled": true,
"environment": { "PLAYWRIGHT_MCP_BROWSER": "chromium" },
"timeout": 5000
}
}
}
| Key | Required | Notes |
|---|---|---|
type |
yes | "local" |
command |
yes | Array form — argv-style |
enabled |
no | Default true; set false to keep the entry but disable it |
environment |
no | Extra env vars for the subprocess |
cwd |
no | Working directory for the spawned subprocess (v1.17.4+) |
timeout |
no | Tool-call timeout (ms). Default 5000. |
Remote servers — HTTP
{
"mcp": {
"context7": {
"type": "remote",
"url": "https://mcp.context7.com/mcp",
"headers": { "CONTEXT7_API_KEY": "{env:CONTEXT7_API_KEY}" }
}
}
}
| Key | Required | Notes |
|---|---|---|
type |
yes | "remote" |
url |
yes | HTTPS endpoint |
headers |
no | Custom HTTP headers (supports {env:NAME}) |
oauth |
no | Pre-registered OAuth client credentials |
enabled |
no | Default true; set false to keep the entry but disable it |
timeout |
no | Tool-call timeout (ms). Default 5000. |
OAuth
OpenCode handles OAuth automatically for remote servers that support it. When a server returns 401, OpenCode initiates Dynamic Client Registration (RFC 7591), pops a browser to complete auth, and stores the credentials locally.
{
"mcp": {
"sentry": {
"type": "remote",
"url": "https://mcp.sentry.dev/mcp",
"oauth": {}
}
}
}
For servers that require pre-registered credentials:
{
"mcp": {
"my-corp-api": {
"type": "remote",
"url": "https://mcp.example.com/mcp",
"oauth": {
"clientId": "{env:CLIENT_ID}",
"clientSecret": "{env:CLIENT_SECRET}",
"scope": "tools:read tools:execute"
}
}
}
}
Managing servers from the CLI
opencode mcp add # interactively register a local or remote server
opencode mcp list # show servers and auth status
opencode mcp auth sentry # complete or refresh OAuth flow
opencode mcp logout sentry # forget stored credentials
opencode mcp debug sentry # diagnose connection issues
opencode mcp add walks you through type, command/URL, and headers, then writes the entry to your config — the no-hand-editing alternative to the JSON blocks above.
Token budget warning
MCP tools land in the model's tool surface every turn. Heavy servers (e.g., a full GitHub MCP with dozens of tools) can easily eat 10K+ tokens of context — purely for tool descriptions the model may never actually call.
Disable noisy tools at the project level and re-enable them only for agents that need them:
{
"tools": {
"github_*": false,
"slack_*": false
},
"agent": {
"issue-triager": {
"tools": {
"github_get_issue": true,
"github_list_issues": true,
"github_add_comment": true
}
}
}
}
Featured servers
Walkthroughs in this repo
Step-by-step setup guides live in ../mcp-servers/:
| Server | Adds | Type | Walkthrough |
|---|---|---|---|
| Playwright | Browser automation (DOM, network, screenshots, accessibility) | local | playwright.md |
| Context7 | Live, version-pinned library docs | remote | context7.md |
| Sentry | Errors, traces, releases | remote (OAuth) | sentry.md |
| Grep by Vercel | Code search across GitHub | remote | grep.md |
⚠️ Warning: the
mcp.grep.appendpoint has been flaky (returning 504 as of 2026-07-05). See the walkthrough and Vercel's announcement post for details.
Other notable servers
| Server | Adds | Type | Source |
|---|---|---|---|
| Chrome DevTools | Drive a real Chrome instance | local | ChromeDevTools/chrome-devtools-mcp |
| Memory / mem0 | Long-term cross-session memory | local/remote | mem0ai/mem0 |
| Tavily | Web search + extraction for agents | remote | tavily-ai/tavily-mcp |
| Sequential Thinking | Step-by-step reasoning helper | local | modelcontextprotocol/servers |
Invocation from a prompt
Reference an MCP server's tools naturally — OpenCode surfaces them as additional tools:
use playwright to open https://example.com and screenshot the navbar
look up the React Router v7 changelog (use context7)
search the codebase for `parseToken` calls with grep
MCP resources
🆕 As of v1.17.10, OpenCode exposes MCP resources, not just tools: it can list a server's resource templates and read individual resources through dedicated tools. Instructions published by an MCP server are also appended to the session context automatically.
Discovery — the MCP Registry
The Official MCP Registry (live since 2025) catalogues vetted servers. Browse via the website or look for opencode mcp discovery features in newer versions.
Troubleshooting
| Problem | Fix |
|---|---|
| Server fails to connect | opencode mcp debug <name> |
| OAuth flow stuck | opencode mcp logout <name> then opencode mcp auth <name> |
| Server eats too many tokens | Disable tools you don't use via the tools map |
command not found for local server |
Make sure the binary is on $PATH or use a fully-qualified npx invocation |
| Connection times out | Bump timeout (default 5000ms) |
📚 Full MCP guide: opencode.ai/docs/mcp-servers · Registry: registry.modelcontextprotocol.io · Protocol spec: modelcontextprotocol.io.
Last reviewed: 2026-07-05 · Canonical source: opencode.ai/docs/mcp-servers.