mirror of
https://github.com/wesammustafa/opencode-primer.git
synced 2026-11-18 18:04:22 +00:00
- 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
222 lines
7.6 KiB
Markdown
222 lines
7.6 KiB
Markdown
# 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).*
|