远程 MCP 认证

恢复 OAuth 登录，为无头环境配置 client_credentials，并了解 Entra 与 WorkIQ。

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

远程 MCP 的认证与 Copilot 自身登录不是同一件事。CLI 已登录 GitHub，也可能因某个服务令牌过期而显示 needs-auth。

重新认证

/mcp auth SERVER-NAME

普通 OAuth 服务打开认证流程，可登录或换账号，成功后自动重新连接。先核对服务器名称、URL 和账号，再重复登录；配置中的静态 HTTP header 与 OAuth 设置也应分别检查。

OAuth 字段

字段	作用
oauthClientId	静态客户端 ID，跳过动态注册
oauthScopes	非空 scope 数组，需要 oauthClientId
oauthPublicClient	默认 true；有已保存 secret 的 confidential client 设 false
oauthGrantType	默认 authorization_code，或无头 client_credentials

服务器 WWW-Authenticate challenge 提供的非空 scope 优先；否则 oauthScopes 覆盖发现元数据中的 scopes_supported。

无头服务认证

CI 等没有浏览器的环境可用：

{
  "mcpServers": {
    "headless-api": {
      "type": "http",
      "url": "https://api.example.com/mcp",
      "tools": ["*"],
      "oauthClientId": "YOUR-CLIENT-ID",
      "oauthPublicClient": false,
      "oauthGrantType": "client_credentials"
    }
  }
}

替换为服务发放的 URL 和 ID，还需事先通过 /mcp 界面或 OAuth 凭据存储配置系统钥匙串中的 client_secret。仅复制 JSON 并不足以完成认证。

该模式跳过浏览器、回调、PKCE 和动态注册；遇到 401 时，向发现的 token endpoint 发送 client_credentials 请求。

Microsoft Entra 与 WorkIQ

Windows 上 Entra 保护的远程 MCP 可使用操作系统 Web Account Manager broker，通常不显示提示；Linux / macOS 使用 /login → Microsoft Entra 建立的身份尝试静默获取对应资源令牌，不能满足时回退浏览器。

命令参考提供 --device-code 绕过 broker 使用设备码流程；没有 broker 库的 Windows 也会回退浏览器。实际可用流程以登录提示和服务配置为准。

WorkIQ 启用状态绑定该 Entra 身份，不自动转给另一个账号，也不会往 mcp-config.json 写条目；显式配置、禁用与组织允许/拒绝策略仍优先。它与单独运行 npx @microsoft/workiq mcp 的 stdio 服务是不同入口。

OIDC

oidc: true 为服务器启用 OIDC 注入。远程服务通过 Bearer Authorization 头接收令牌；本地服务通过 env 引用 GITHUB_COPILOT_OIDC_MCP_TOKEN 或带后缀变体。多服务器应使用独立后缀变量，避免把一项服务的令牌当成通用认证。