OpenCode MCP Server Configuration

MCP (Model Context Protocol) is an open protocol that allows you to connect external tools and data sources to OpenCode. After adding an MCP server, the tools it provides are automatically listed alongside OpenCode's built-in tools, and the LLM can call them directly during conversations.

OpenCode supports two types of MCP servers:

• Local: An MCP process started via the command line on your machine, suitable for local tools and scripts.
• Remote: A remote MCP service connected via HTTPS, suitable for cloud services and third-party platforms.

Context Consumption Reminder:Each MCP server consumes context space in the conversation. The more tools are enabled, the more tokens are consumed per conversation, and the easier it is to hit the model's context limit. It is recommended to enable only the MCP servers actually needed for the current task and turn them off when done. Some servers (such as GitHub MCP) have a large number of tools and consume especially significant tokens, so please pay extra attention when using them.

Basic Configuration Structure

All MCP server configurations are written under theopencode.jsonofmcpfield. Each server requires aunique nameas the key name, which can also be used in the prompt to specify which MCP to call:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-mcp-server": {         // 服务器名称（自定义，全局唯一）
      "type": "local",         // 连接类型：local 或 remote
      // ...其他配置项
      "enabled": true          // 是否启用，默认为 true
    },
    "another-mcp-server": {    // 可同时配置多个 MCP 服务器
      "type": "remote",
      // ...
    }
  }
}

willenabledSet tofalsecan temporarily disable a server without removing it from the configuration file, making it easy to toggle on demand:

Local MCP Server

A local MCP server provides tools by running a command process on your machine. Settypeto"local", and specify the startup command viacommand:

Local Server Configuration Options

Example: Adding a Test MCP Server

Below is an example of adding the official test MCP server@modelcontextprotocol/server-everything, which can be used to verify whether the MCP functionality is working correctly:

After configuration is complete, add the server name to the prompt to let the LLM call the tools of that MCP:

use the mcp_everything tool to add the number 3 and 4

Remote MCP Server

A remote MCP server connects to cloud services via HTTPS. Settypeto"remote", and specify the server address viaurl:

Remote Server Configuration Options

Referencing Environment Variables

In the configuration file,sensitive information such as API keys should not be written directly in plaintext. OpenCode supports reading system environment variables at runtime via the{env:变量名}syntax:

OAuth Authentication

OpenCode has built-in OAuth authentication support for remote MCP servers. The entire process is almost fully automatic, with no need to handle tokens manually.

Automatic Authentication Flow

When the server requires OAuth authentication, OpenCode automatically completes the following steps:

1. Detects a 401 (Unauthorized) response from the server
2. Automatically starts the OAuth authorization flow and opens a browser to guide you through login
3. When the server supports it, automatically registers the application using dynamic client registration (RFC 7591)
4. Securely stores the obtained token in~/.local/share/opencode/mcp-auth.jsonMedium
5. Subsequent requests automatically carry the token; no need to log in repeatedly

1. Automatic OAuth (No Additional Configuration Required)

For most MCP servers that support OAuth, simply configureurland OpenCode will automatically guide you through authentication on first use:

You can also manually trigger the authentication flow (e.g., to log in again after a token expires):

opencode mcp auth my-oauth-server

2. Pre-registered Client Credentials

If you have already obtained a fixed client ID and secret from the service provider, you can specify them directly in the configuration and skip the dynamic registration step:

3. Disabling OAuth (Using API Key Authentication)

If the server uses an API key instead of OAuth authentication, you can setoauthtofalseto disable automatic OAuth detection and useheadersto pass the key:

OAuth Configuration Options

Authentication Management Commands

OpenCode provides a set of command-line tools for managing MCP authentication state:

# 对指定 MCP 服务器进行身份验证（会打开浏览器完成 OAuth 授权）
opencode mcp auth my-oauth-server

# 列出所有已配置的 MCP 服务器及其当前认证状态
opencode mcp list

# 删除指定服务器已存储的凭据（下次使用时需要重新登录）
opencode mcp logout my-oauth-server

# 调试指定服务器的连接和 OAuth 流程（显示认证状态、测试连接、执行 OAuth 发现流程）
opencode mcp debug my-oauth-server

# 查看所有支持 OAuth 的服务器的认证状态
opencode mcp auth list

Overriding Remote Default Configuration

Organizations can provide.well-known/opencodepreset MCP server configurations to members via endpoints. These servers may be disabled by default. If you need to enable one of them, add an entry with the same name in your local configuration and setenabled: trueto enable it.Local configuration will override remote default values：

Tool Management

After an MCP server is registered, its tools appear in服务器名称_工具名称the form of in OpenCode's tool list, and can be managedtoolsthrough the field for unified management.

1. Globally Disabling Tools of a Specific MCP

2. Batch Disabling with Glob Patterns

Using Glob wildcards can match and disable tools from multiple MCP servers at once:

3. Enabling Specific MCP Tools per Agent

If you have configured many MCP servers but each agent only needs a subset, you can first globally disable all MCP tools, then enable them as needed in specific agent configurations. This allows precise control over which tools each agent can access, avoiding context waste:

Glob Pattern Rules

MCP server tools are prefixed with the server name when registered. For example, tools from servermyserverare registered asmyserver_toolname. Therefore, to disable all tools of a server, use"myserver_*": falsefor an exact match.

Configuration Examples

Sentry

Add the Sentry MCP server to query errors, issues, and event data of Sentry projects directly in conversations:

After adding the configuration, run the following command to complete account authorization (a browser will open for OAuth login):

opencode mcp auth sentry

After authentication is complete, adduse sentryto your prompt to invoke the Sentry tools:

Show me the latest unresolved issues in my project. use sentry

Context7

Add the Context7 MCP server to search various technical documents in conversations, helping LLMs obtain the latest and accurate API references:

Adduse context7to your prompt to invoke the document search functionality:

Configure a Cloudflare Worker script to cache JSON API responses for five minutes. use context7

You can also add global rules in the project'sAGENTS.mdto let the LLM automatically use Context7 when it needs to look up documentation, without having to specify it manually each time:

When you need to search docs, use `context7` tools.

Grep by Vercel

Add the Grep by Vercel MCP server to search real code snippets on GitHub directly in conversations, helping LLMs find correct API usage and implementation references:

Adduse the gh_grep toolto your prompt to search for code examples on GitHub:

What's the right way to set a custom domain in an SST Astro component? use the gh_grep tool

Similarly, you can set global rules inAGENTS.mdto let the LLM automatically search for code examples when uncertain about usage:

If you are unsure how to do something, use `gh_grep` to search code examples from GitHub.