> ## Documentation Index > Fetch the complete documentation index at: https://mcp.zhcndoc.com/llms.txt > Use this file to discover all available pages before exploring further. # 授权 > MCP Inspector 如何执行 OAuth、在会话中途重新授权，以及在其客户端之间共享令牌 远程 MCP 服务器通常需要授权。Inspector 在三个客户端中均实现了完整的[授权](/specification/latest/basic/authorization)流程，并将生成的令牌共享存储在磁盘上，因此只需登录一次即可在所有地方使用。 ## 端到端的流程 Inspector 连接到服务器 URL。服务器返回 `401`。当响应包含 `WWW-Authenticate` 标头时，其中会指向受保护资源元数据 URL (`resource_metadata`)，以及请求所需的作用域（如果有）。 Inspector 获取服务器的[受保护资源和 授权服务器 元数据](/specification/latest/basic/authorization/authorization-server-discovery)， 以了解端点和支持的授权授予类型。 Inspector 通过已配置的机制向授权服务器标识自身：包括[动态客户端 注册](/specification/latest/basic/authorization/client-registration#dynamic-client-registration)、 预注册的静态客户端（`--client-id` / `--client-secret`）、[客户端 ID 元数据 文档](/specification/latest/basic/authorization/client-registration#client-id-metadata-documents) （`--client-metadata-url`），或[企业管理的 IdP](/extensions/auth/enterprise-managed-authorization)。 Inspector 打开授权 URL。您登录并同意授权。 授权服务器重定向到 Inspector 的回调 URL，并携带授权码。 授权码被交换为令牌，令牌会被持久化保存，原始连接（或对于[会话中途的挑战](#mid-session-re-authorization)， 被拒绝的请求）会自动重试。 ## 回调 URL Web 应用在其自身的 URL 上监听 OAuth 回调，而 CLI 和 TUI 则有意共享第二个 URL： | 界面 | 默认回调 | 原因 | | ------- | -------------------------------------- | ------------------------------------- | | **Web** | `http://localhost:6274/oauth/callback` | 主应用服务器已经有一个 HTTP 监听器。 | | **CLI** | `http://127.0.0.1:6276/oauth/callback` | 专用的回环监听器，因此不会与正在运行的 Web Inspector 冲突。 | | **TUI** | `http://127.0.0.1:6276/oauth/callback` | 与 CLI 使用相同的监听器。 | 在使用 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`，让操作系统分配临时端口。 ## 凭据存放位置 | 文件 | 内容 | | ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | | `~/.mcp-inspector/storage/oauth.json` | 按规范化服务器 URL 作为键存储令牌和客户端信息。仅所有者可写入。 | | `~/.mcp-inspector/storage/client.json` | 安装级客户端设置（客户端元数据 URL、企业 IdP）。Web 客户端 **客户端设置** 对话框写入的也是同一个文件。 | | [目录文件](/docs/2026-07-28/tools/inspector/configuration#catalog-file-format)中的服务器 `oauth` 块 | 每个服务器的客户端 ID/密钥、作用域、企业管理标志以及 [升级授权](#mid-session-re-authorization)策略。 | `oauth.json` 的路径按以下顺序解析：`MCP_INSPECTOR_OAUTH_STATE_PATH`，然后是 `/oauth.json`（参见[环境变量](/docs/2026-07-28/tools/inspector/configuration#environment-variables)），最后是上述默认路径。三个客户端均以相同方式解析该路径。命令行中的 `--client-id` / `--client-secret` / `--client-metadata-url` 会覆盖 `client.json`。 ## 会话中途重新授权 服务器可以在会话中途使用 `401` 或 `403 insufficient_scope` 拒绝某个请求，而 Inspector 会在不中断连接的情况下处理这两种情况： * **重新授权**：令牌已过期或被撤销。Inspector 解析 `WWW-Authenticate` 挑战并重新执行授权流程，然后重试失败的请求。 * **升级授权**：请求需要当前令牌未包含的作用域。Inspector 会针对当前已持有作用域与所需作用域的并集重新授权，因此新令牌将覆盖旧令牌的全部作用域，并包含新要求的作用域。 在 **Web** 客户端中，这会显示为重新授权横幅。在 **CLI** 中，则会在 stderr 上提示： ``` Proceed with step-up authorization? [y/N] ``` 回答 **y** 以继续。只要输入以换行符结尾或 stdin 关闭，管道输入也可以正常工作（`echo y | ...`）。输入 **N**，或未作答即遇到 EOF，都会拒绝授权。非 TTY stdin 在 5 秒内没有发送任何内容时，会以 `auth_required` 失败；这与明确拒绝是不同的情况。企业管理的升级授权会静默地重新签发令牌，不显示提示。 ## 非交互式运行和 CI 运行 交互式 OAuth 要求 **stdin 或 stderr** 上有 TTY，或设置 [`MCP_AUTO_OPEN_ENABLED=true`](/docs/2026-07-28/tools/inspector/configuration#environment-variables)。将 stderr 重定向到管道（例如 `2>&1 | tee`）仍然有效，因为 stdin 仍是 TTY。当两者都不满足时（这正是 CI 中的常见情况），CLI 会快速失败并返回 `auth_required`，而不是等待长达十五分钟，去等待一个不会有人完成的回调。 对于 CI，请明确指定： ```bash theme={null} mcp-inspector --cli "$URL" --transport http --stored-auth-only --method tools/list ``` `--stored-auth-only` 永远不会启动交互式 OAuth 或升级验证，不会打开浏览器；如果共享存储中存在令牌，则使用该令牌，否则立即失败。 ## 从 Web 客户端切换到 CLI 常见情况：用户已在此计算机上的 Web Inspector 中完成 OAuth，现在脚本需要使用该令牌。 | 标志 | 行为 | | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | `--use-stored-auth` | 读取 `--server-url` 对应的已存储身份验证信息，并注入 `Authorization: Bearer`。如果已存储刷新令牌，则先执行刷新授权并注入**新鲜**令牌，同时持久化轮换后的令牌。如果没有匹配项，则退出并返回 `3`（列出已存储的服务器 URL）。 | | `--wait-for-auth ` | 轮询状态文件，直到出现 `--server-url` 对应的令牌，然后注入该令牌。在 `` 秒后超时并返回 `3`。将登录交给用户后使用此选项。 | | `--list-stored-auth` | 打印 `{ oauthStatePath, storedServerUrls }`，然后退出，不建立连接。 | | `--print-handoff` | 为 `--server-url` 打印一个 JSON 块（`deepLink`、`portForwardCmd`、`oauthStatePath`、`apiToken`），然后退出；这是远程脚本驱动浏览器端所需的全部信息。 | | `--relogin` | 在连接前删除此服务器 URL 对应的已存储 OAuth 信息。仅适用于 HTTP/SSE。 | 典型的远程 VM 流程： ```bash theme={null} # 在 VM 上：打印用户在浏览器中完成 OAuth 所需的信息 mcp-inspector --cli --server-url https://api.example/mcp --print-handoff # 然后阻塞等待令牌写入，并使用该令牌执行调用 mcp-inspector --cli --transport http --server-url https://api.example/mcp \ --wait-for-auth 120 --method tools/list ``` 交接信息块中的 `deepLink` 会将浏览器直接导航到一个\_已连接\_的 Inspector；请参阅[深层链接](/docs/2026-07-28/tools/inspector/web#deep-links)。 由于已存储的条目不记录过期时间，因此每次运行 `--use-stored-auth` 时都会使用已存储的刷新令牌。对于轮换型（单次使用）刷新令牌，这会产生两个较小的故障窗口：针对同一状态文件的两个并发调用可能会争抢令牌，而在刷新成功与回写之间发生崩溃，则会导致轮换后的令牌未被保存。两种情况都不太可能发生；重新在 Web 客户端中进行授权即可恢复。 ## 检查身份验证状态 * **Web**：连接信息面板显示发现结果、已注册的客户端、已授予的作用域和令牌状态，并提供针对当前服务器的**清除 OAuth 状态**功能。 * **TUI**：**身份验证**选项卡（`a`）显示相同的字段，并以相同方式清除状态。 * **CLI**：`--list-stored-auth` 显示磁盘上的内容，而 `--relogin` 丢弃这些内容并重新开始。