端到端的流程
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
交换并重试
授权码被交换为令牌，令牌会被持久化保存，原始连接会重试。对于会话中途的挑战，CLI 会自动重试被拒绝的请求，而 Web 客户端会要求你重试操作。
OAuth 流程完成后的连接信息：授权状态、动态注册的客户端以及已授予的作用域。
回调 URL
Web 应用在其自身的 URL 上监听 OAuth 回调，而 CLI 和 TUI 则有意共享第二个 URL：
在使用 CLI 或 TUI 之前，请在任何要求预先注册重定向 URI 的 IdP 上注册
http://127.0.0.1:6276/oauth/callback。可预测的默认值正是其意义所在：注册一次，重复使用。
CLI 和 TUI 可使用 --callback-url 或 MCP_OAUTH_CALLBACK_URL 覆盖。Web 回调始终遵循页面的源，因此在那里 localhost 和 127.0.0.1 也会产生不同的重定向 URI。
重定向 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。
机密信息本身（访问令牌和刷新令牌、客户端密钥、注册访问令牌和 IdP 会话令牌）不在 oauth.json 中，而会进入机密信息存储；可访问时使用操作系统密钥链。MCP_INSPECTOR_PERSIST_TOKENS 限制保存哪些已获取的令牌：all（默认）、access（不保存刷新令牌）或 none（每次运行都重新授权）。请参阅机密信息存储变量。
会话中途重新授权
服务器可以在会话中途使用401 或 403 insufficient_scope 拒绝某个请求，而 Inspector 会在不中断连接的情况下处理这两种情况：
- 重新授权：令牌已过期或被撤销。Inspector 解析
WWW-Authenticate挑战并重新执行授权流程，然后重试失败的请求。 - 升级授权：请求需要当前令牌未包含的作用域。Inspector 会针对当前已持有作用域与所需作用域的并集重新授权，因此新令牌将覆盖旧令牌的全部作用域，并包含新要求的作用域。
403 直接作为错误显示。在 CLI 中，升级授权会在 stderr 上提示：
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 流程如下。该流程假定 VM 上运行着 Web Inspector，并且已知
MCP_INSPECTOR_API_TOKEN；下面的 Shell 中也导出了相同的值。没有该值时，交接信息中的 deepLink 不会携带 autoConnect 令牌，Web 客户端会拒绝它：
deepLink 会将浏览器直接导航到一个_已连接_的 Inspector；请参阅深层链接。
由于已存储的条目不记录过期时间，因此每次运行
--use-stored-auth 时都会使用已存储的刷新令牌。对于轮换型（单次使用）刷新令牌，这会产生两个较小的故障窗口：针对同一状态文件的两个并发调用可能会争抢令牌，而在刷新成功与回写之间发生崩溃，则会导致轮换后的令牌未被保存。两种情况都不太可能发生；重新在 Web 客户端中进行授权即可恢复。检查身份验证状态
- Web：连接信息面板显示授权状态、客户端注册类型、客户端 ID、已授予的作用域和访问令牌，并提供针对当前服务器的清除 OAuth 状态并断开连接功能。除非服务器的清除时撤销令牌设置已关闭，否则清除操作还会撤销授权。
- TUI：身份验证选项卡（
a）显示相同的字段，并以相同方式清除状态。 - CLI：
--list-stored-auth显示磁盘上的内容，而--relogin撤销并丢弃这些内容，然后重新开始。