Skip to main content
远程 MCP 服务器通常需要授权。Inspector 在三个客户端中均实现了完整的授权流程，并将生成的令牌共享到磁盘上，因此只需登录一次，即可在各处使用。

​
端到端的流程

1

连接并被拒绝

Inspector 连接到服务器 URL。服务器返回 401。当响应携带 WWW-Authenticate 标头时，该标头会指向受保护资源元数据 URL (resource_metadata)，并可选地指出请求所需的作用域。
2

发现授权服务器

Inspector 获取服务器的受保护资源和 授权服务器 元数据， 以了解相关端点和所支持的授权授予类型。
3

注册或识别客户端

Inspector 通过已配置的机制向授权服务器标识自身：包括动态客户端 注册、 预注册的静态客户端（--client-id / --client-secret）、客户端 ID 元数据 文档 （--client-metadata-url），或企业管理的 IdP。
4

在浏览器中授权

Inspector 打开授权 URL。您登录并同意授权。
5

接收回调

授权服务器将请求重定向到 Inspector 的回调 URL，并携带授权码。
6

交换并重试

授权码被交换为令牌，令牌会被持久化保存，最初的连接（或者对于会话中途的挑战，即被拒绝的请求）会自动重试。

完成 OAuth 流程后的连接信息：授权状态、动态注册的客户端以及已授予的作用域。

​
回调 URL

Web 应用在自身的 URL 上监听 OAuth 回调，而 CLI 和 TUI 则有意共享第二个 URL： 在使用 CLI 或 TUI 之前，请在任何要求预先注册重定向 URI 的 IdP 上注册 http://127.0.0.1:6276/oauth/callback。默认值保持固定正是为了便于使用：注册一次，重复使用。 使用 --callback-url 或 MCP_OAUTH_CALLBACK_URL 覆盖此设置。
回调 URL 必须绑定回环主机：localhost、127.0.0.0/8 或 [::1]。监听器通过明文 http 接收授权码，因此非回环主机会被拒绝并返回错误，且没有可覆盖此限制的标志。如果浏览器运行在另一台机器上，请将回调端口转发到该机器；--print-handoff（见下文）会打印一个可直接使用的 portForwardCmd。
重定向 URI 必须与注册信息完全匹配。对于授权服务器而言，http://localhost:6276/... 和 http://127.0.0.1:6276/... 是不同的 URI，尽管它们会到达同一个监听器。默认端口同一时间只能由一个进程占用；第二个并发流程会因 EADDRINUSE 失败。请为每个实例使用不同的固定端口；当授权服务器支持动态重定向 URI 注册时，也可以使用 http://127.0.0.1:0/oauth/callback，以便由操作系统分配临时端口。

​
凭据存放位置

oauth.json 的路径按以下顺序解析：MCP_INSPECTOR_OAUTH_STATE_PATH，然后是 <MCP_STORAGE_DIR>/oauth.json（参见环境变量），最后是上述默认路径。三个客户端都以相同方式解析该路径。命令行中的 --client-id / --client-secret / --client-metadata-url 会覆盖 client.json。

​
会话中途重新授权

服务器可以在会话中途使用 401 或 403 insufficient_scope 拒绝单个请求，而 Inspector 会在不中断连接的情况下处理这两种情况：
  • 重新授权：令牌已过期或已被撤销。Inspector 会解析 WWW-Authenticate 挑战并重新执行授权流程，然后重试失败的请求。
  • 升级授权：请求需要当前令牌未包含的作用域。Inspector 会针对已持有作用域与所需作用域的并集重新授权，使新令牌覆盖旧令牌包含的全部作用域，以及新要求的作用域。
在 Web 客户端中，这会显示为重新授权横幅。在 CLI 中，它会在 stderr 上提示：
回答 y 即可继续。管道输入也有效（echo y | ...），前提是输入以换行结束或 stdin 关闭。输入 N，或在没有回答的情况下遇到 EOF，都会拒绝授权。非 TTY stdin 如果在 5 秒内没有发送任何内容，则会以 auth_required 失败；这与明确拒绝是不同的情况。企业管理的升级授权会静默地重新签发令牌，不会显示提示。

​
非交互式运行和 CI 运行

交互式 OAuth 要求 stdin 或 stderr 上存在 TTY，或者设置 MCP_AUTO_OPEN_ENABLED=true。将 stderr 重定向到管道中（例如 2>&1 | tee）仍然有效，因为 stdin 仍然是 TTY。当两者都不满足时（这正是通常的 CI 场景），CLI 会立即失败并返回 auth_required，而不是等待长达十五分钟来接收一个无人完成的回调。 对于 CI，请明确指定：
--stored-auth-only 不会启动交互式 OAuth 或升级验证，不会打开浏览器；如果共享存储中存在令牌，则使用该令牌，否则立即失败。

​
从 Web 客户端移交到 CLI

常见情况：用户已在此计算机上的 Web Inspector 中完成 OAuth，现在脚本希望使用该令牌。 一个典型的远程 VM 流程：
移交信息块中的 deepLink 会将浏览器直接导航到一个_已连接_的 Inspector；请参阅深层链接。
由于已存储条目不记录过期时间，因此每次运行 --use-stored-auth 时都会使用已存储的刷新令牌。对于轮换型（单次使用）刷新令牌，这会带来两个很小的故障窗口：针对同一状态文件的两个并发调用可能会争抢令牌，而在刷新成功与写回之间发生崩溃，则会导致轮换后的令牌未被保存。这两种情况都不太可能发生；重新在 Web 客户端中进行授权即可恢复。

​
检查身份验证状态

  • Web：连接信息面板显示发现结果、已注册的客户端、已授予的作用域和令牌状态，并为当前服务器提供清除 OAuth 状态选项。
  • TUI：身份验证选项卡（a）显示相同的字段，并以相同方式清除状态。
  • CLI：--list-stored-auth 显示磁盘上的内容，而 --relogin 会丢弃这些内容并重新开始。