MCP OAuth 与认证排障

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

远程 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 认证诊断。