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

Prerequisites

• OpenCode installed (npm install -g opencode)
• 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 reads your MCP config at startup and exposes each server's tools to the agent.

Enabling MCP in OpenCode

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

Configuring MCP Servers (opencode.json)

Add an mcp block to your opencode.json:

{
  "mcp": {
    "servers": {
      "filesystem": {
        "command": "npx",
        "args": ["-y", "@anthropic/mcp-server-filesystem", "./"],
        "env": {}
      },
      "github": {
        "command": "npx",
        "args": ["-y", "@anthropic/mcp-server-github"],
        "env": {
          "GITHUB_TOKEN": "${GITHUB_TOKEN}"
        }
      },
      "brave-search": {
        "command": "npx",
        "args": ["-y", "@anthropic/mcp-server-brave-search"],
        "env": {
          "BRAVE_API_KEY": "${BRAVE_API_KEY}"
        }
      }
    }
  }
}

Each server entry has three fields:

Using "${VAR_NAME}" makes OpenCode resolve the value from your shell environment at launch — keep secrets out of the committed file.

Global vs Project Config

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

Servers defined in both merge, with project-level taking precedence on conflicts.

Verifying Your Servers

1. Start OpenCode in your project: opencode
2. Ask the agent to use a tool from the server, e.g. "search the filesystem for README files" or "list my recent GitHub issues"
3. OpenCode loads the server's tools at startup — if a server failed to connect, you'll see an error in the session log

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]

MCP tools are namespaced by server, so multiple servers can expose similarly named tools without conflict.

Security Considerations

• Least privilege — only give servers the credentials they need; use read-only scopes where possible
• Keep secrets out of git — use ${VAR_NAME} interpolation or keep private server config in your global ~/.config/opencode/opencode.json
• Review server tools — an MCP server executes arbitrary commands on your machine; only add servers you trust
• Scoped servers — prefer project-level config over global for workspace-specific tools

Troubleshooting

Further Resources

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