How to Set Up MCP Servers in OpenCode (Step-by-Step)

Prerequisites

• OpenCode 2 installed (npm install -g @opencode/cli or curl -fsSL https://opencode.ai/v2/install | bash)
• Node.js 18+ or Docker for npx- and Docker-based servers
• A configured LLM provider (see OpenCode Getting Started)

What is MCP?

MCP (Model Context Protocol) lets OpenCode's agent use external tools — filesystem access, GitHub, web search, databases — through a standard interface. OpenCode connects to your configured servers and exposes their tools, prompts, resources, and instructions to the agent.

Enabling MCP in OpenCode

OpenCode reads server definitions from opencode.json or opencode.jsonc in your project (or ~/.config/opencode/ for global config). MCP support is on by default — you only define servers.

The CLI writes the configuration for you:

# Remote server, project scope
opencode mcp add context7 --url https://mcp.context7.com/mcp

# Local server, global scope
opencode mcp add everything --global -- npx -y @modelcontextprotocol/server-everything

# Check connection state
opencode mcp list

Configuring MCP Servers

V2 groups servers under mcp.servers. Server names do not go directly under mcp, and V2 uses disabled, not enabled.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "filesystem": {
        "type": "local",
        "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "."],
        "environment": {
          "LOG_LEVEL": "info"
        }
      },
      "github": {
        "type": "remote",
        "url": "https://api.githubcopilot.com/mcp/",
        "headers": {
          "Authorization": "Bearer {env:GITHUB_TOKEN}"
        }
      }
    }
  }
}

The server entry fields differ by type:

OpenCode's interpolation syntax is {env:NAME} (not ${NAME}), as used in the GitHub header above.

Timeouts

Defaults live under mcp.timeout; a server's own timeout object overrides matching values:

{
  "mcp": {
    "timeout": {
      "startup": 45000,
      "catalog": 30000,
      "execution": 600000
    },
    "servers": {
      "slow-tools": {
        "type": "remote",
        "url": "https://mcp.example.com/mcp"
      }
    }
  }
}

startup covers the transport and initialization, catalog covers listing tools and resources, and execution covers tool calls. Execution defaults to 12 hours so long-running tools are not cut off.

Code Mode

Code Mode is on by default. MCP tools become JavaScript functions grouped by server:

tools.context7.resolve_library_id(...)

The agent composes them in one script instead of making a separate model round trip per tool call, and large MCP catalogs add little context overhead. Set codemode: false on a server when a tool must stay on the provider's native tool list.

Global vs Project Config

• Project — opencode.jsonc in your project root applies only there
• Global — ~/.config/opencode/opencode.jsonc applies to every session

A higher-precedence project config replaces the entire server object with the same name, so repeat every required field when overriding a global server.

Remote Servers and OAuth

Remote servers use OAuth by default. Add the server, then authenticate:

opencode mcp add sentry --url https://mcp.sentry.dev/mcp
opencode mcp auth sentry

Or run /mcps in the TUI, select the server, and sign in through the browser. Credentials are stored outside project configuration.

For servers that use an API key instead of OAuth, disable OAuth explicitly:

{
  "type": "remote",
  "url": "https://mcp.example.com/mcp",
  "oauth": false,
  "headers": { "Authorization": "Bearer {env:MCP_API_KEY}" }
}

V2 OAuth client fields use snake case: client_id, client_secret, callback_port, and redirect_uri.

Verifying Your Servers

1. List servers and their state:

   opencode mcp list
   

   A connected server shows as connected; one that needs a sign-in shows needs authentication.

2. Start OpenCode in your project: opencode.

3. Ask the agent to use a tool from the server, e.g. "search the filesystem for README files" or "list my recent GitHub issues".

4. In the TUI, /mcps shows every configured server and lets you connect, disconnect, or authenticate without editing config.

Using MCP Tools in OpenCode

Once connected, the agent calls the server's tools like any built-in tool:

You: "Use the github server to find issues labeled bug in this repo."

Agent: [calls the github tool, returns matching issues]

Tool names are normalized to <server>_<tool>, so multiple servers can expose similarly named tools without conflict. Prompts become slash commands named <server>:<prompt>, for example /context7:find_docs.

Security Considerations

• Least privilege — only give servers the credentials they need; use read-only scopes where possible

• Keep secrets out of git — use {env:VAR_NAME} interpolation or keep private server config in your global ~/.config/opencode/opencode.jsonc

• Review server tools — an MCP server executes arbitrary commands on your machine; only add servers you trust

• Scope permissions — deny individual tools with a permission rule instead of removing the whole server:

  {
    "permissions": [
      { "action": "context7_*", "resource": "*", "effect": "deny" }
    ]
  }
  

Troubleshooting

Further Resources

• MCP Servers directory — pick servers that match your tools
• OpenCode Configuration — full opencode.jsonc reference
• MCP Setup in Cursor — the same concepts in Cursor
• MCP Setup in Claude Code — CLI-based MCP configuration

Sources

• https://opencode.ai/v2/docs/mcp-servers/
• https://opencode.ai/v2/docs/config/
• https://github.com/github/github-mcp-server