端到端的流程
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 覆盖。
重定向 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 会针对当前已持有作用域与所需作用域的并集重新授权，因此新令牌将覆盖旧令牌的全部作用域，并包含新要求的作用域。
echo y | ...）。输入 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丢弃这些内容并重新开始。