Setting Up MCP in OpenCode: Complete Configuration Guide

Introduction to OpenCode MCP

OpenCode is an open source AI coding agent available as a terminal-based interface, desktop app, or IDE extension. It leverages the Model Context Protocol (MCP) to extend its capabilities beyond built-in tools, allowing you to connect to external data sources, APIs, and services.

Once configured, MCP tools are automatically available to the LLM alongside OpenCode's built-in tools. You can reference them by name in your prompts to leverage their capabilities.

Prerequisites

Before configuring MCP servers in OpenCode, ensure you have:

• •OpenCode installed: Install via curl -fsSL https://opencode.ai/install | bash or npm/brew.
• •Node.js: Required for running npm-based MCP servers. Verify with node --version.
• •API provider configured: Connect OpenCode to an LLM provider via /connect command.
• •Project initialised: Run /init in your project to create the configuration file.

OpenCode MCP Features

OpenCode provides comprehensive MCP support with the following features:

Configuring Local MCP Servers

Local MCP servers run on your machine and communicate via standard input/output (stdio). They're ideal for file system access, local database queries, and tools that need access to your local environment.

Basic Configuration

Add local MCP servers to your opencode.json file:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-local-mcp-server": {
      "type": "local",
      "command": ["npx", "-y", "my-mcp-command"],
      "enabled": true,
      "environment": {
        "MY_ENV_VAR": "my_env_var_value"
      }
    }
  }
}

Configuration Options

Filesystem Server Example

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "filesystem": {
      "type": "local",
      "command": [
        "npx", 
        "-y", 
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/projects",
        "/Users/username/documents"
      ],
      "enabled": true
    }
  }
}

Configuring Remote MCP Servers

Remote MCP servers are hosted in the cloud and accessed via HTTP. They're perfect for documentation search, web scraping, and third-party API integrations.

Basic Configuration

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-remote-mcp": {
      "type": "remote",
      "url": "https://my-mcp-server.com",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer MY_API_KEY"
      }
    }
  }
}

Remote Server Options

OAuth Authentication

OpenCode automatically handles OAuth authentication for remote MCP servers that require it. When a server returns a 401 response, OpenCode initiates the OAuth flow automatically.

Automatic OAuth

For most OAuth-enabled servers, no special configuration is needed:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-oauth-server": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp"
    }
  }
}

Pre-registered Client Credentials

If you have client credentials from the MCP server provider:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-oauth-server": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp",
      "oauth": {
        "clientId": "{env:MY_MCP_CLIENT_ID}",
        "clientSecret": "{env:MY_MCP_CLIENT_SECRET}",
        "scope": "tools:read tools:execute"
      }
    }
  }
}

Managing OAuth Credentials

Use these commands to manage OAuth:

# Authenticate with a specific MCP server# List all MCP servers and their auth status# Remove stored credentials# Remove stored credentials# Remove stored credentialsls
opencode mcp logout my-oauth-server

Managing MCP Servers

Global Enable/Disable

You can enable or disable MCP servers globally using the tools configuration:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-mcp-foo": {
      "type": "local",
      "command": ["bun", "x", "my-mcp-command-foo"]
    },
    "my-mcp-bar": {
      "type": "local",
      "command": ["bun", "x", "my-mcp-command-bar"]
    }
  },
  "tools": {
    "my-mcp-foo": false,
    "my-mcp*": false  // Glob pattern to disable all matching
  }
}

Per-Agent Configuration

For large numbers of MCP servers, enable them per-agent rather than globally:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-mcp": {
      "type": "local",
      "command": ["bun", "x", "my-mcp-command"],
      "enabled": true
    }
  },
  "tools": {
    "my-mcp*": false  // Disable globally
  },
  "agent": {
    "my-agent": {
      "tools": {
        "my-mcp*": true  // Enable for this agent only
      }
    }
  }
}

Glob Patterns

OpenCode supports glob patterns for tool configuration:

• * - Matches zero or more of any character
• ? - Matches exactly one character
• All other characters match literally

Real-World Examples

Here are complete configuration examples for popular MCP servers:

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

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "gh_grep": {
      "type": "remote",
      "url": "https://mcp.grep.app"
    }
  }
}

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "filesystem": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/path/to/directory"],
      "enabled": true
    }
  }
}

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "github": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-github"],
      "environment": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "{env:GITHUB_TOKEN}"
      },
      "enabled": true
    }
  }
}

Troubleshooting

References & Further Reading