MCP 服务器

添加本地和远程 MCP 工具。

你可以使用 Model Context Protocol（即 MCP）向 OpenCode 添加外部工具。OpenCode 同时支持本地和远程服务器。

添加后，MCP 工具会与内置工具一起自动提供给 LLM 使用。

注意事项

当你使用一个 MCP 服务器时，它会增加上下文。如果你有大量工具，这会很快累积起来。所以我们建议你谨慎选择使用哪些 MCP 服务器。

提示： MCP 服务器会增加你的上下文，所以你需要谨慎选择启用哪些。

某些 MCP 服务器，例如 GitHub MCP 服务器，往往会增加大量 token，很容易超出上下文限制。

启用

你可以在 OpenCode 配置 (opens in a new tab) 的 mcp 下定义 MCP 服务器。为每个 MCP 添加一个唯一的名称。在向 LLM 发出提示时，你可以通过该名称引用对应的 MCP。

opencode.jsonc

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

你也可以通过将 enabled 设置为 false 来禁用某个服务器。如果你想临时禁用某个服务器而不将其从配置中移除，这会很有用。

覆盖远程默认值

组织可以通过其 .well-known/opencode 端点提供默认的 MCP 服务器。这些服务器可能默认被禁用，允许用户按需选择启用所需的那些。

要从你组织的远程配置中启用某个特定的服务器，请将其加入你的本地配置并设置 enabled: true：

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "jira": {
      "type": "remote",
      "url": "https://jira.example.com/mcp",
      "enabled": true
    }
  }
}

你的本地配置值会覆盖远程默认值。更多细节请参阅配置优先级。

本地

在 MCP 对象内将 type 设为 "local" 来添加本地 MCP 服务器。

opencode.jsonc

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

command 是本地 MCP 服务器的启动方式。你还可以传入一组环境变量。

例如，下面是添加测试用 @modelcontextprotocol/server-everything (opens in a new tab) MCP 服务器的方式。

opencode.jsonc

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

要使用它，我可以在提示词中加入 use the mcp_everything tool。

use the mcp_everything tool to add the number 3 and 4

选项

以下是配置本地 MCP 服务器的所有选项。

选项	类型	必填	描述
`type`	String	Y	MCP 服务器连接的类型，必须为 `"local"`。
`command`	Array	Y	运行 MCP 服务器的命令及参数。
`environment`	Object		运行服务器时设置的环境变量。
`enabled`	Boolean		在启动时启用或禁用该 MCP 服务器。
`timeout`	Number		从 MCP 服务器获取工具的超时时间（毫秒）。默认为 5000（5 秒）。

远程

通过将 type 设为 "remote" 来添加远程 MCP 服务器。

opencode.json

{
  "$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"
      }
    }
  }
}

url 是远程 MCP 服务器的 URL，通过 headers 选项你可以传入一组请求头。

选项

选项	类型	必填	描述
`type`	String	Y	MCP 服务器连接的类型，必须为 `"remote"`。
`url`	String	Y	远程 MCP 服务器的 URL。
`enabled`	Boolean		在启动时启用或禁用该 MCP 服务器。
`headers`	Object		随请求发送的请求头。
`oauth`	Object		OAuth 身份验证配置。参见下方 OAuth 一节。
`timeout`	Number		从 MCP 服务器获取工具的超时时间（毫秒）。默认为 5000（5 秒）。

OAuth

OpenCode 会自动处理远程 MCP 服务器的 OAuth 身份验证。当某个服务器需要身份验证时，OpenCode 会：

检测到 401 响应并发起 OAuth 流程
在服务器支持的情况下使用动态客户端注册（Dynamic Client Registration，RFC 7591）
安全地存储 token 以供后续请求使用

自动

对于大多数启用了 OAuth 的 MCP 服务器，无需特殊配置。只需配置远程服务器：

opencode.json

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

如果服务器需要身份验证，OpenCode 会在你首次尝试使用时提示你进行验证。如果不需要，你可以用 opencode mcp auth <server-name> 手动触发该流程。

预注册

如果你拥有来自 MCP 服务器提供方的客户端凭据，你可以对其进行配置：

opencode.json

{
  "$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"
      }
    }
  }
}

进行身份验证

你可以手动触发身份验证或管理凭据。

针对某个特定 MCP 服务器进行身份验证：

opencode mcp auth my-oauth-server

列出所有 MCP 服务器及其验证状态：

opencode mcp list

移除已存储的凭据：

opencode mcp logout my-oauth-server

mcp auth 命令会打开你的浏览器进行授权。授权完成后，OpenCode 会将 token 安全地存储在 ~/.local/share/opencode/mcp-auth.json 中。

禁用 OAuth

如果你想为某个服务器禁用自动 OAuth（例如，对于改用 API 密钥的服务器），将 oauth 设置为 false：

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-api-key-server": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp",
      "oauth": false,
      "headers": {
        "Authorization": "Bearer {env:MY_API_KEY}"
      }
    }
  }
}

OAuth 选项

选项	类型	描述
`oauth`	Object \| false	OAuth 配置对象，或 `false` 以禁用 OAuth 自动检测。
`clientId`	String	OAuth 客户端 ID。如果未提供，将尝试动态客户端注册。
`clientSecret`	String	OAuth 客户端密钥，如果授权服务器要求的话。
`scope`	String	授权期间要请求的 OAuth scope。

调试

如果某个远程 MCP 服务器身份验证失败，你可以用以下命令诊断问题：

# 查看所有支持 OAuth 的服务器的验证状态
opencode mcp auth list
 
# 调试某个特定服务器的连接和 OAuth 流程
opencode mcp debug my-oauth-server

mcp debug 命令会显示当前的验证状态、测试 HTTP 连通性，并尝试 OAuth 发现流程。

管理

你的 MCP 会作为工具在 OpenCode 中提供，与内置工具并列。因此你可以像管理任何其他工具一样，通过 OpenCode 配置来管理它们。

全局

这意味着你可以全局地启用或禁用它们。

opencode.json

{
  "$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
  }
}

我们也可以使用 glob 模式来禁用所有匹配的 MCP。

opencode.json

{
  "$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*": false
  }
}

这里我们使用 glob 模式 my-mcp* 来禁用所有 MCP。

按 agent

如果你有大量 MCP 服务器，你可能希望只按 agent 启用它们，而在全局禁用它们。要做到这一点：

在全局将它作为工具禁用。
在你的 agent 配置中，将该 MCP 服务器作为工具启用。

opencode.json

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

Glob 模式

glob 模式使用简单的正则 glob 匹配模式：

* 匹配零个或多个任意字符（例如，"my-mcp*" 匹配 my-mcp_search、my-mcp_list 等）
? 恰好匹配一个字符
所有其他字符按字面匹配

注意： MCP 服务器工具会以服务器名作为前缀进行注册，所以要禁用某个服务器的所有工具，只需使用：
"mymcpservername_*": false

示例

下面是一些常见 MCP 服务器的示例。如果你想记录其他服务器，可以提交一个 PR。

Sentry

添加 Sentry MCP 服务器 (opens in a new tab) 以与你的 Sentry 项目和 issue 交互。

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "sentry": {
      "type": "remote",
      "url": "https://mcp.sentry.dev/mcp",
      "oauth": {}
    }
  }
}

添加该配置后，与 Sentry 进行身份验证：

opencode mcp auth sentry

这会打开一个浏览器窗口来完成 OAuth 流程，并将 OpenCode 连接到你的 Sentry 账户。

完成身份验证后，你可以在提示词中使用 Sentry 工具来查询 issue、项目和错误数据。

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

Context7

添加 Context7 MCP 服务器 (opens in a new tab) 以在文档中搜索。

opencode.json

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

如果你注册了一个免费账户，你可以使用你的 API 密钥并获得更高的速率限制。

opencode.json

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

这里我们假设你已设置了 CONTEXT7_API_KEY 环境变量。

在你的提示词中加入 use context7 以使用 Context7 MCP 服务器。

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

或者，你可以在你的 AGENTS.md 中添加类似下面的内容。

AGENTS.md

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

Grep by Vercel

添加 Grep by Vercel (opens in a new tab) MCP 服务器以在 GitHub 上搜索代码片段。

opencode.json

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

由于我们将 MCP 服务器命名为 gh_grep，你可以在提示词中加入 use the gh_grep tool，让 agent 使用它。

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

或者，你可以在你的 AGENTS.md 中添加类似下面的内容。

AGENTS.md

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

LSP 服务器 ACP 支持