MCP OAuth 与认证排障

处理远程认证发现、预注册客户端、API Key、凭据清理与诊断。

This page has not been translated into English yet. The original Chinese version is shown below.

远程 MCP 要求身份时，OpenCode 可处理 OAuth。服务器的 HTTP 可达性、OAuth 发现和用户授权需要分别成功，不能只凭 URL 可访问就判断认证正常。

自动认证

只配置 type: "remote" 和服务 URL 时，OpenCode 遇到需要认证的服务会提示授权。它识别 401 响应，并在服务器支持时尝试 Dynamic Client Registration（RFC 7591）。

不是每个服务器都支持动态注册；已有 client credentials 时可显式提供。服务器无需认证时，也不必添加虚构的 OAuth 设置。

预注册客户端

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

URL、client ID、secret 和 scopes 必须与真实服务匹配。clientSecret 只在授权服务器要求时提供；未配置 clientId 时尝试动态注册。示例 scopes 不是所有 MCP 的通用权限名。

手动授权与清理

命令	用途
`opencode mcp auth my-oauth-server`	打开浏览器完成该服务器授权
`opencode mcp list`	列出服务器及认证状态
`opencode mcp logout my-oauth-server`	删除保存的该服务器凭据
`opencode mcp auth list`	查看支持 OAuth 的服务器认证状态
`opencode mcp debug my-oauth-server`	测试 HTTP 连接、OAuth 发现并显示状态

服务器名称应替换为配置中的键。授权后 token 保存在 ~/.local/share/opencode/mcp-auth.json，与模型提供商的 auth.json 分开。

使用 API Key

服务使用 API Key 时，可设置 oauth: false 禁用自动 OAuth 探测，在 headers 中提供它要求的认证，例如 Authorization: "Bearer {env:MY_API_KEY}"。

只有真实服务使用 Bearer 方式时才采用该 header；其他服务可能使用专用 header。关闭 OAuth 不会免除服务本身的认证要求。

排查顺序

先运行 list 确认配置名称，再用 debug 检查 HTTP 与发现流程；之后核对 client credentials、scopes 和浏览器授权结果。旧身份失效时可 logout 后重新 auth。不要通过清空所有模型和会话数据来替代单个 MCP 认证诊断。