Adding MCP servers to opencode

opencode can pull in external tools over the Model Context Protocol (MCP). Both local (subprocess) and remote (HTTP) servers are supported; once configured, their tools appear next to the built-in tools. Caveat from the docs: every server adds tool definitions to your context — the docs single out GitHub’s for blowing the limit. Enable only what you need.

The `mcp` key

Define servers under mcp in opencode.json/opencode.jsonc, each with a unique name. You can steer the agent toward a server by name in prompts (“use context7”), and set enabled: false to keep an entry configured but off:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-server": { "enabled": true }
  }
}

Organizations can ship MCP defaults via .well-known/opencode; local mcp entries override them — e.g. set enabled: true to opt in to a server the org ships disabled. Merge rules are covered in the configuration guide.

Local servers

A local server is a command opencode starts for you:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mcp_everything": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-everything"],
      "environment": { "LOG_LEVEL": "info" }
    }
  }
}

Option	Required	Notes
`type`	yes	Must be `"local"`
`command`	yes	Executable plus args, as an array
`cwd`	no	Working directory; relative paths resolve from the workspace
`environment`	no	Env vars for the server process
`timeout`	no	Tool-fetch timeout in ms; default 5000

Remote servers

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp",
      "headers": {
        "CONTEXT7_API_KEY": "{env:CONTEXT7_API_KEY}"
      }
    }
  }
}

{env:NAME} interpolates environment variables — use it for credentials so secrets stay out of committed config. Remote options: url (required), headers, oauth, enabled, timeout (same 5000 ms default).

OAuth

Remote OAuth is automatic: opencode detects the 401, runs a browser auth flow (Dynamic Client Registration, RFC 7591, when supported), and stores tokens at ~/.local/share/opencode/mcp-auth.json. With pre-registered client credentials, configure them:

"oauth": {
  "clientId": "{env:MCP_CLIENT_ID}",
  "clientSecret": "{env:MCP_CLIENT_SECRET}",
  "scope": "tools:read tools:execute"
}

Set "oauth": false on pure API-key servers to skip OAuth entirely. Servers and credentials are CLI-managed:

opencode mcp add               # interactive add, local or remote
opencode mcp list              # servers + connection status (alias: ls)
opencode mcp auth my-server    # browser auth flow
opencode mcp auth list         # OAuth-capable servers + status
opencode mcp logout my-server  # drop stored credentials
opencode mcp debug my-server   # connectivity + OAuth discovery

Controlling MCP tools

MCP tools register under the server name as prefix, so the tools key accepts globs (* = zero or more chars, ? = exactly one) — disable a server globally, then re-enable it for the agents that need it. (tools is deprecated since v1.1.1 — the equivalent permission rules use the same glob patterns, e.g. "my-server_*": "deny". See the permissions guide.)

{
  "$schema": "https://opencode.ai/config.json",
  "tools": { "my-server_*": false },
  "agent": {
    "reviewer": { "tools": { "my-server_*": true } }
  }
}

v2 differences

v2 reshapes this surface: servers nest under mcp.servers, disabled replaces enabled, OAuth fields are snake_case (client_id), mcp add is flag-driven (--url, --env, --header, --global), and /mcps manages servers in-app. This guide covers the v1 config.

The mcp key