MCP 工具调用为什么返回 401 或 403：用 metadata、scope 和 audience 快速定位

远程 MCP 服务本地联调时一切正常，部署到 HTTPS 公网地址后经常碰到很迷惑的情况：客户端能连上，甚至能列出部分工具，一调用敏感功能就返回 401 Unauthorized 或 403 Forbidden。这时候别着急把问题归到模型或者工具描述配置上。对 HTTP 协议的 MCP 服务来说，401 通常意味着没有可用令牌、令牌过期，或是授权发现路径没走通；403 更像“令牌本身存在，但它没有覆盖这次调用需要的权限”。

先把 401 和 403 分开看，后续排查路径完全不同

先把客户端日志里那条失败请求留存下来，但只保留状态码、目标 MCP 地址、工具名和 WWW-Authenticate 的字段名，绝对不要把令牌明文写进日志。MCP 的授权规范把 HTTP 401 归为“需要授权或 token 无效”，把 403 归为“权限不足”。如果两种状态混在一起盲目重试，最常见的结果就是反复刷新同一张不带目标 audience 的无效令牌。

这里有个很容易误判的细节：工具列表并不永远固定。MCP Tools 规范允许服务器根据请求携带的授权返回不同的工具集合。因此“能看见一个只读工具”并不能证明写入、导出或管理类工具也会通过授权检查。

401 时的最小排查路径：从 WWW-Authenticate 找到 metadata

HTTP MCP 服务器可在 401 响应的 WWW-Authenticate 中给出 resource_metadata。客户端应优先使用这个 URL；没有该字段时，再按照规范尝试受保护资源的 well-known 地址。metadata 的作用是告诉客户端关联的授权服务器位置，之后才能继续读取 OAuth 或 OpenID Connect 的授权服务器元数据。

from dataclasses import dataclass


@dataclass
class AuthNextStep:
    kind: str
    action: str


def classify_mcp_failure(status_code: int, www_authenticate: str) -> AuthNextStep:
    header = www_authenticate.lower()

    if status_code == 401 and "resource_metadata=" in header:
        return AuthNextStep("discover", "读取 resource_metadata，再发现授权服务器")
    if status_code == 401:
        return AuthNextStep("token", "核对 token 是否过期、签发方和 resource")
    if status_code == 403 and "insufficient_scope" in header:
        return AuthNextStep("scope", "按响应头 scope 走一次增量授权")
    return AuthNextStep("inspect", "保存状态码和字段名，检查服务端授权日志")

这段函数不负责完整解析 HTTP 头，它只把排查方向收窄。实际客户端逻辑应该交给成熟的 HTTP 和 OAuth 库处理引号、转义和多行头。测试时可以先把服务端返回的 resource_metadata 地址单独请求一遍，确认它能返回资源元数据；再检查 metadata 里的 authorization_servers 是否包含预期的授权服务。到这步先别急着下判断，能读取 metadata 只说明发现链路通了，不代表 token 已经适用于目标 MCP 资源。

token 能正常拿到却仍是 401，多半是 resource 和 audience 没对齐

MCP 授权规范要求客户端在授权请求和 token 请求中带上 resource 参数，它应该标识客户端想要访问的 MCP 服务。服务端则需要确认 token 是专门签给自己的，而不是用户把本来用于另一个 API 的 token 顺手转发过来。路径、端口或末尾斜杠处理不一致时，肉眼看起来是同一个地址，resource server 却可能把它判成不同对象。

• 把客户端实际请求的 MCP endpoint 和申请 token 时的 resource 并排记录，重点核对协议、主机、端口和路径。
• 让授权服务按规范返回面向该资源的 token；不要复用其他 SaaS API 的 access token。
• 服务端验签后继续核对 audience 与目标资源，再决定是否接受调用。
• 令牌要只放在 Authorization 请求头中，不要带到 query string，也不要把完整值输出到调试日志。

碰到 403 不要直接重试登录，要读取这次工具真正需要的 scope

当服务器认为 token 本身有效、但权限不够时，规范建议返回 403，并用 WWW-Authenticate 标出 error="insufficient_scope"、所需 scope 和资源元数据地址。这个 scope 是当前调用的有效提示，不能只拿客户端配置里的 scopes_supported 做简单对照。尤其在同一 MCP 服务同时提供查询和修改工具时，服务端完全可以给不同工具要求不同权限。

正确的处理流程是一次受控的增量授权：解析响应头，合并既有的有效权限与新增需要的权限，获取新 token，再重试原调用少数几次。一直对同一个 403 循环尝试没有意义，还会让用户反复看到授权提示。如果工具属于删除、发信、导出或修改配置等高风险操作，客户端层还应保留明确的人工确认，不要仅因 scope 已通过就静默放行。

部署前做一份小核对，比线上猜权限省很多时间

相关问题

STDIO MCP 也要走这套 OAuth 流程吗？

不一定。MCP 授权规范针对 HTTP transport；STDIO 场景通常从环境中取得本地凭据，并采用适合本地进程边界的安全做法即可。不用把远程 HTTP 的发现步骤机械照搬过去。

401 没有 resource_metadata 怎么办？

先检查目标地址是不是实际 MCP endpoint，再按规范的 well-known 规则尝试受保护资源元数据地址；如果仍然失败，回到服务端检查反向代理和 metadata 路由是否对外可达。

为什么 tools/list 请求成功，调用 tools/call 却返回 403？

工具展示权限和具体工具调用权限可以相互独立。服务端可能允许公开或只读工具被列出，但对写入、导出等操作要求额外 scope 和用户确认。

可以把 access token 缓存在浏览器地址栏参数里排查吗？

不可以。令牌不应出现在 URL query string。使用受保护的本地存储或内存存储，并在日志、错误上报和截图中做脱敏处理。

把失败码转化为下一步动作

远程 MCP 授权问题最高效的排查思路，是把 401 当作发现链或 token 有效性问题处理，把 403 当作当前工具权限问题处理。先读 challenge，再核对 resource 与 audience，最后才处理 scope 升级。这样既能减少无效重试，也能让敏感工具始终保留明确的权限边界。

规范细节可以回看 MCP 官方的 Authorization、Tools 与 授权教程；实际接入时还要结合所用客户端、身份提供方和工具风险等级做集成测试。