# OpenCode MCP Server Reference

MCP servers extend OpenCode with external tools, services, and data sources.

## Built-in (Enable by Name)

| MCP | Purpose | Config |
|-----|---------|--------|
| `filesystem` | Structured file operations | `"filesystem": { "enabled": true }` |
| `git` | Smart git operations (diffs, blame, log) | `"git": { "enabled": true }` |
| `sequential-thinking` | Chain-of-thought reasoning for complex tasks | `"sequential-thinking": { "enabled": true }` |
| `time` | Current date/time (prevents date hallucination) | `"time": { "enabled": true }` |
| `memory` | Persistent cross-session memory | `"memory": { "enabled": true }` |
| `fetch` | Web page fetching | `"fetch": { "enabled": true }` |

## Web Search & Research

| MCP | Key Required | Free Tier | Install Command | Remote URL Alternative | Sign Up |
|-----|-------------|-----------|-----------------|----------------------|---------|
| **Brave Search** | `BRAVE_SEARCH_API_KEY` | 2K queries/mo | `npx -y @modelcontextprotocol/server-brave-search` | N/A | [brave.com/search/api](https://brave.com/search/api/) |
| **Tavily Search** | `TAVILY_API_KEY` | 1K queries/mo | `npx -y tavily-mcp` | `https://mcp.tavily.com/mcp/?tavilyApiKey=KEY` | [tavily.com](https://app.tavily.com/home) |
| **Firecrawl** | `FIRECRAWL_API_KEY` | 500 pages/mo | `npx -y firecrawl-mcp` | `https://mcp.firecrawl.dev/KEY/v2/mcp` | [firecrawl.dev](https://www.firecrawl.dev/) |
| **Context7** | None | Unlimited | `npx -y @upstash/context7-mcp` | N/A | N/A |

## API Key Injection (Important)

**OpenCode does NOT interpolate `${VAR}` in MCP `env` values.** The literal string is passed to the subprocess. Hardcode keys directly — the approaches that work:

### A) Python direct write (preferred — avoids shell character mangling)

```python
import json
tavily_key = "tvly-dev-..."
firecrawl_key = "fc-a97bf55-..."
brave_key = "BSA0Fa..."

with open("~/.config/opencode/opencode.json") as f:
    data = json.load(f)

data["mcp"]["brave-search"]["env"]["BRAVE_SEARCH_API_KEY"] = brave_key
data["mcp"]["tavily-search"]["env"]["TAVILY_API_KEY"] = tavily_key
data["mcp"]["firecrawl"]["env"]["FIRECRAWL_API_KEY"] = firecrawl_key

with open("~/.config/opencode/opencode.json", "w") as f:
    json.dump(data, f, indent=2)
```

### B) sed with sourced env vars (when keys have no problematic characters)

```bash
source ~/.config/opencode/.env
sed -i "s|\${TAVILY_API_KEY}|$TAVILY_API_KEY|g" ~/.config/opencode/opencode.json
sed -i "s|\${FIRECRAWL_API_KEY}|$FIRECRAWL_API_KEY|g" ~/.config/opencode/opencode.json
```

### C) Persist in shell config

```bash
echo 'export BRAVE_SEARCH_API_KEY="your-key"' >> ~/.bashrc
echo 'export TAVILY_API_KEY="your-key"' >> ~/.bashrc
echo 'export FIRECRAWL_API_KEY="your-key"' >> ~/.bashrc
```

Keys with dashes, underscores, or mixed case can be corrupted by shell heredocs — always verify the stored key length. The Python approach (A) is immune to this.

## Context Caching

For prompt caching to work effectively across all providers, add `"setCacheKey": true` to each provider's `options` block:

```jsonc
"provider": {
    "local-gateway": {
        "options": {
            "baseURL": "http://127.0.0.1:9292/v1",
            "setCacheKey": true
        }
    }
}
```

Pair with the opencode-context-cache plugin for stable SHA256 cache keys (98% hit rate).

## MCP Config Examples

### Brave Search MCP — Best Search Quality

Official MCP server from Brave. v2.x removed base64 image blobs (v1.x bug that wasted tokens).

```jsonc
"brave-search": {
    "type": "local",
    "command": ["npx", "-y", "@modelcontextprotocol/server-brave-search"],
    "env": { "BRAVE_SEARCH_API_KEY": "YOUR_KEY" }
}
```

### Tavily MCP — AI-Optimized Search

Designed for AI agents rather than human browsing. Returns pre-extracted content. Two modes:

**Local:**
```jsonc
"tavily-search-local": {
    "type": "local",
    "command": ["npx", "-y", "tavily-mcp"],
    "env": { "TAVILY_API_KEY": "YOUR_KEY", "TAVILY_HUMAN_ID": "opencode" }
}
```

**Remote (simpler, no npx):**
```jsonc
"tavily-search": {
    "type": "remote",
    "url": "https://mcp.tavily.com/mcp/?tavilyApiKey=YOUR_KEY"
}
```

### Firecrawl MCP — Full Page Content Extraction

Best for extracting content from JS-rendered pages. Crawls, scrapes, and returns markdown.

**Local:**
```jsonc
"firecrawl": {
    "type": "local",
    "command": ["npx", "-y", "firecrawl-mcp"],
    "env": { "FIRECRAWL_API_KEY": "YOUR_KEY" }
}
```

**Remote (keyless free tier available):**
```jsonc
"firecrawl": {
    "type": "remote",
    "url": "https://mcp.firecrawl.dev/v2/mcp"
}
```

### Context7 — Fresh Library Docs (No Key Needed)

Fetches current documentation for 200+ frameworks (Next.js, React, Prisma, Tailwind, etc.). Prevents agents writing code against hallucinated/outdated APIs.

```jsonc
"context7": {
    "type": "local",
    "command": ["npx", "-y", "@upstash/context7-mcp"]
}
```

## GitHub MCP Server

For PR review, issue management, repo operations. **Token concern**: GitHub MCP adds many tools to context — restrict to specific agents.

**Remote** (recommended):
```jsonc
"github": {
    "type": "remote",
    "url": "https://api.githubcopilot.com/mcp/",
    "oauth": false,
    "headers": { "Authorization": "Bearer {env:GITHUB_PAT}" }
}
```

Requires `GITHUB_PAT` environment variable (GitHub Personal Access Token). Restrict tools to avoid context bloat:
```jsonc
"tools": { "github_*": false },
"agent": { "github-helper": { "tools": { "github_*": true } } }
```

**Local** (Docker): See [github-mcp-server install-opencode.md](https://github.com/github/github-mcp-server/blob/main/docs/installation-guides/install-opencode.md)

## Development Tooling

| MCP | What It Does |
|-----|-------------|
| `github` | Authenticated GitHub API (PRs, issues, repos) |
| `filesystem` | Structured file ops beyond built-in read/write/edit |
| `postgres` | Database queries and schema exploration |
| `puppeteer` | Browser automation for testing |

## Community / Notable

| MCP | What It Does |
|-----|-------------|
| **System Monitor** (MCP) | Linux system monitoring (CPU, memory, disk, network, process) |
| **Composio** | 1,000+ toolkits (GitHub, Linear, Slack, Jira, Stripe, Figma) via MCP |