Files
Wesam Abousaid a3f328c043 docs: refresh for OpenCode v1.17.13, add Go coverage, and rebrand
- 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
2026-07-05 14:11:51 +02:00

222 lines
7.6 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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:
```mermaid
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.
```mermaid
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
```json
{
"$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
```json
{
"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.
```json
{
"mcp": {
"sentry": {
"type": "remote",
"url": "https://mcp.sentry.dev/mcp",
"oauth": {}
}
}
}
```
For servers that require pre-registered credentials:
```json
{
"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
```bash
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:
```json
{
"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/`](../mcp-servers/):
| Server | Adds | Type | Walkthrough |
|---|---|---|---|
| **Playwright** | Browser automation (DOM, network, screenshots, accessibility) | local | [`playwright.md`](../mcp-servers/playwright.md) |
| **Context7** | Live, version-pinned library docs | remote | [`context7.md`](../mcp-servers/context7.md) |
| **Sentry** | Errors, traces, releases | remote (OAuth) | [`sentry.md`](../mcp-servers/sentry.md) |
| **Grep by Vercel** | Code search across GitHub | remote | [`grep.md`](../mcp-servers/grep.md) |
> ⚠️ **Warning:** the `mcp.grep.app` endpoint has been flaky (returning 504 as of 2026-07-05). See the [walkthrough](../mcp-servers/grep.md) and Vercel's [announcement post](https://vercel.com/blog/grep-a-million-github-repositories-via-mcp) for details.
### Other notable servers
| Server | Adds | Type | Source |
|---|---|---|---|
| **Chrome DevTools** | Drive a real Chrome instance | local | [`ChromeDevTools/chrome-devtools-mcp`](https://github.com/ChromeDevTools/chrome-devtools-mcp) |
| **Memory / mem0** | Long-term cross-session memory | local/remote | [`mem0ai/mem0`](https://github.com/mem0ai/mem0) |
| **Tavily** | Web search + extraction for agents | remote | [`tavily-ai/tavily-mcp`](https://github.com/tavily-ai/tavily-mcp) |
| **Sequential Thinking** | Step-by-step reasoning helper | local | [`modelcontextprotocol/servers`](https://github.com/modelcontextprotocol/servers) |
## Invocation from a prompt
Reference an MCP server's tools naturally — OpenCode surfaces them as additional tools:
```text
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](https://github.com/anomalyco/opencode/releases/tag/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](https://registry.modelcontextprotocol.io/) (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](https://opencode.ai/docs/mcp-servers) · Registry: [registry.modelcontextprotocol.io](https://registry.modelcontextprotocol.io/) · Protocol spec: [modelcontextprotocol.io](https://modelcontextprotocol.io/).
---
*Last reviewed: 2026-07-05 · Canonical source: [opencode.ai/docs/mcp-servers](https://opencode.ai/docs/mcp-servers).*