菜单

MCP 授权实战:401、WWW-Authenticate 与受保护资源元数据

2026-10-30MCP Checkup

MCP 里鉴权是可选的。如果你的服务器用了,客户端最难的一步不是拿 token,而是弄清楚去哪里拿。一个从没见过你服务器的客户端,只知道一件事:你的 URL。它开始登录所需的一切,都得在不带凭据的情况下从这个 URL 拿到:一个 401、一个响应头、两份 JSON 文档。

这篇文章按规范描述的顺序走一遍这条链,列出它会在哪里断开,并给每一步配一条 curl 命令。这些命令都不需要 token。把 https://your-server.example.com/mcp 换成你的地址就行。

规范对受保护服务器的要求

下面的规则出自当前版本 2026-07-28;除非另外注明,2025-11-25 的要求相同。

  • 这些规则适用于 HTTP 传输。走 stdio 的服务器应该改从环境里取凭据。
  • 你的 MCP server 扮演 OAuth 2.1 的资源服务器。它必须实现 OAuth 2.0 受保护资源元数据(Protected Resource Metadata,RFC 9728),而且这份文档必须在 authorization_servers 里至少列出一个授权服务器。
  • 它必须用以下两种方式中的至少一种,告诉客户端这份文档在哪里:在 401 响应的 WWW-Authenticate 头里放一个 resource_metadata 参数,或者把文档放在 well-known 地址上。客户端两种都必须支持。
  • 授权服务器必须发布 OAuth 2.0 授权服务器元数据(RFC 8414)或 OpenID Connect Discovery 1.0 文档。客户端两种都必须尝试。
  • 客户端在每个请求里用 Authorization: Bearer <token> 发送 token,绝不放进查询字符串。你的服务器必须核对 token 是不是签发给它的,对无效或过期的 token 回 401,并且既不能接受、也不能转发签发给别处的 token。

更早的版本有几处要紧的差别:

  • 2025-06-18 强制要求这个响应头:服务器回 401 时,必须在 WWW-Authenticate 里给出元数据地址。它没有为客户端规定 well-known 兜底,授权服务器那边也只列了 RFC 8414,没有 OpenID Connect Discovery。
  • 2025-03-26 根本没有受保护资源元数据。客户端直接在 MCP server 自己的主机上找授权服务器元数据,找不到就退回 /authorize 这类默认路径。如果你的服务器还是这种配置,任何更新版本的客户端都没法只凭 URL 找到它的授权服务器。
  • 2026-07-28 明确要求客户端拒绝 issuer 对不上的授权服务器元数据,增加了对 iss 参数的校验(RFC 9207),并弃用了 Dynamic Client Registration,改推 Client ID Metadata Documents。

第 1 步:401

客户端先发一个普通的 MCP 请求,不带 token。受保护的服务器应该这样回:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://your-server.example.com/.well-known/oauth-protected-resource/mcp", scope="files:read"

每一部分各有用处:

  • **401 加上 WWW-Authenticate 头。**这是 HTTP 本身的要求:发 401 的服务器必须同时给出至少一个质询(RFC 9110 第 15.5.2 节)。光秃秃的 401 违反的是 HTTP,跟你遵循哪个 MCP 版本无关。
  • Bearer 是 RFC 6750 定义的方案名。
  • resource_metadata 是你的受保护资源元数据的地址(RFC 9728 第 5.1 节)。有了它,客户端就直接用,而不去猜 well-known 地址。
  • scope 是可选的,但从 2025-11-25 起,规范说服务器应该带上。客户端会把它当作首先要申请的 scope;没有它,就退回去用元数据里的 scopes_supported。
  • **没有 error 参数。**请求根本没带凭据时,RFC 6750 说服务器不应该给出错误码。error="invalid_token" 是给「发了 token 但校验失败」的情况用的。

之后,如果客户端出示的 token 缺少某个需要的 scope,回复就变成 403,带 error="insufficient_scope"、这次操作需要的 scope,以及同样的 resource_metadata(2025-11-25、2026-07-28)。

看看你的服务器发的是什么:

MCP_URL=https://your-server.example.com/mcp
curl -sS -o /dev/null -D headers.txt "$MCP_URL" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -H 'Mcp-Method: tools/list' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"curl-test","version":"0.1"},"io.modelcontextprotocol/clientCapabilities":{}}}}'
grep -iE '^HTTP/|^www-authenticate|^location|^content-type' headers.txt

如果服务器是更早的版本,改发 initialize 请求。如果回的是 200,说明在你的服务器上这个方法不需要 token;换一个需要 token 的方法再试。

第 2 步:受保护资源元数据

从响应头里取出地址,再去请求它:

PRM_URL=$(tr -d '\r' < headers.txt | grep -i '^www-authenticate:' \
  | sed -n 's/.*resource_metadata="\([^"]*\)".*/\1/p')
echo "$PRM_URL"
curl -sS -i "$PRM_URL"

RFC 9728 要求返回 200、Content-Type: application/json,内容是类似这样的 JSON 对象:

{
  "resource": "https://your-server.example.com/mcp",
  "authorization_servers": ["https://auth.your-server.example.com"],
  "scopes_supported": ["files:read", "files:write"],
  "bearer_methods_supported": ["header"],
  "resource_name": "Example Files"
}
字段 RFC 9728 MCP 额外的要求
resource 必填 你的服务器的规范 URI:scheme 和主机名小写,不带 fragment,最好也不带结尾斜杠
authorization_servers 可选 必填,至少一个 issuer
scopes_supported 推荐 401 里没有 scope 时用它;从 2025-11-25 起,它应该是基本功能所需的最小集合
bearer_methods_supported 可选 MCP 客户端只用请求头发送 token
resource_name 推荐 客户端可以展示给正在登录的人看的名字

规则最严的是 resource。RFC 9728 第 3.3 节规定:如果客户端是经由 resource_metadata 找到这份文档的,resource 必须和客户端发请求用的 URL 完全一致;如果是在 well-known 地址找到的,resource 必须和构造这个地址所用的标识完全一致。对不上,客户端就不能用这份文档。对比一下你的:

curl -sS "$PRM_URL" | jq --arg url "$MCP_URL" \
  '{resource_matches: (.resource == $url), resource, authorization_servers, scopes_supported}'

第 3 步:没有响应头时,找 well-known 地址

从 2025-11-25 起,服务器可以不给 resource_metadata,只靠 well-known 地址,客户端必须去那里找。RFC 9728 构造这个地址的方式,是把 /.well-known/oauth-protected-resource 插在主机名和路径之间。MCP 规范让客户端按下面的顺序试两个位置:

for u in https://your-server.example.com/.well-known/oauth-protected-resource/mcp \
         https://your-server.example.com/.well-known/oauth-protected-resource; do
  curl -sS -o /dev/null -w "%{http_code} %{content_type}  $u\n" "$u"
done

既在第一个位置发布文档,又在响应头里写明地址,客户端走哪条路都能找到。常见的失误是把后缀接在路径后面,比如 /mcp/.well-known/oauth-protected-resource。RFC 是把它插在主机名后面的,规范也从不让客户端去找这种接在后面的形式。

第 4 步:授权服务器的元数据

authorization_servers 里的每一项都是一个 issuer 标识(RFC 8414)。客户端用它构造 well-known 地址,并按固定顺序尝试(2025-11-25、2026-07-28)。对于带路径的 issuer,比如 https://auth.example.com/tenant1:

  1. https://auth.example.com/.well-known/oauth-authorization-server/tenant1
  2. https://auth.example.com/.well-known/openid-configuration/tenant1
  3. https://auth.example.com/tenant1/.well-known/openid-configuration

不带路径的 issuer 只适用前两种,后面也不再接路径。下面这个循环对文档里的第一个 issuer 逐个尝试:

AS=$(curl -sS "$PRM_URL" | jq -r '.authorization_servers[0]')
origin=$(printf '%s' "$AS" | sed -E 's#^(https?://[^/]+).*#\1#')
as_path=$(printf '%s' "$AS" | sed -E 's#^https?://[^/]+##; s#/$##')
for u in "$origin/.well-known/oauth-authorization-server$as_path" \
         "$origin/.well-known/openid-configuration$as_path" \
         ${as_path:+"$origin$as_path/.well-known/openid-configuration"}; do
  printf '%s  %s\n' "$(curl -sS -o /dev/null -w '%{http_code}' "$u")" "$u"
done

把 AS_META_URL 设成第一个返回 200 的地址,再看客户端依赖的那几个字段:

curl -sS "$AS_META_URL" | jq --arg as "$AS" '{issuer_matches: (.issuer == $as), issuer,
  authorization_endpoint, token_endpoint, code_challenge_methods_supported,
  client_id_metadata_document_supported, registration_endpoint}'

要看的是:

  • **issuer 与 authorization_servers 里的那一项完全一致。**RFC 8414 第 3.3 节规定,不一致时客户端不能使用这份元数据,2026-07-28 也重申了这一条。一边有结尾斜杠、一边没有,就足以对不上。
  • **code_challenge_methods_supported 存在,并且包含 S256。**客户端靠它确认授权服务器支持 PKCE。如果这个字段缺失,MCP 客户端必须拒绝继续(2025-11-25、2026-07-28)。
  • **authorization_endpoint 和 token_endpoint 都是 https。**规范要求授权服务器的所有端点都走 HTTPS。
  • **有办法注册客户端。**用 Client ID Metadata Documents 的话是 client_id_metadata_document_supported: true,用 Dynamic Client Registration 的话是 registration_endpoint,或者由你事先分发 client ID。

常见的配置错误

**401 没带 WWW-Authenticate 头。**这违反了 HTTP。遵循 2025-06-18 的客户端无路可走;遵循 2025-11-25 及之后版本的客户端会退回去找 well-known 地址,所以只有文档确实在那里才行得通。我们目录里的情况:截至 2026 年 10 月 26 日的一周内检查过的 5,924 台服务器里,至少 1,999 台对不带凭据的请求回了 401,其中 33 台的 401 完全没带 WWW-Authenticate 头。

**质询里没有 resource_metadata,**比如 Bearer realm="api"。这在 HTTP 上是合法的,但在 2025-06-18 下不够,在之后的版本里也只是把客户端推向同样的兜底路径。我们目录里的情况:上面这些服务器里有 131 台是这样。

**元数据地址返回的不是元数据。**可能是 404,可能是兜底路由返回的网站 HTML 首页,也可能是跳转到登录页。RFC 9728 要求 200 加 JSON,其他任何回复都给不了客户端需要的东西。我们目录里的情况:有 4 台服务器给出的元数据地址回了 HTTP 错误;回的内容不是 JSON 对象的,0 台。

**resource 和端点对不上。**典型原因:客户端用的是 https,这里写的却是 http;代理后面的内部主机名漏了出来(http://localhost:8080/mcp);客户端调的是 /mcp,这里却只写了域名;或者多了一个结尾斜杠。客户端必须丢弃这份文档。

**authorization_servers 为空,或者干脆没有。**RFC 9728 允许这样,MCP 不允许。

**授权服务器元数据不在客户端会尝试的任何一个地址上,**或者其中的 issuer 和 authorization_servers 里的那一项不一致。无论哪种,客户端都拿不到可用的元数据,登录也就无从开始。

**用登录页代替 401。**比如 302 跳到 /login,或者回一个带 HTML 登录表单的 200。客户端说的是 JSON-RPC。Streamable HTTP 要求对请求的回复必须是 application/json 或 text/event-stream,而一个 HTML 页面里没有任何可读的质询。

**MCP 端点上的重定向。**遇到 301 或 302 时,curl 和浏览器的 fetch 都会把 POST 改成 GET,并丢掉请求体。重定向到另一个源(scheme、主机或端口不同)时,两者都会丢掉 Authorization 头。307 或 308 会保留请求方法,但跨源的规则照样适用。直接把最终的 URL 给客户端,不要依赖重定向。

不带凭据能查什么,不能查什么

第 1 到第 4 步本来就是公开的。这条发现链就是为一个还什么都没有的客户端准备的,所以一个不发送任何凭据的检查,看到的正是新客户端看到的东西:401 和它的响应头、元数据文档和其中的 resource、两个 well-known 位置,以及授权服务器的元数据。

剩下的需要 token,请用你自己的账号来测:

  • 过期或格式错误的 token 得到 401,带 error="invalid_token";
  • 签发给别的受众(audience)的 token 被拒绝;
  • 缺少 scope 的 token 得到 403,带 error="insufficient_scope" 和所需的 scope;
  • 如果你的工具列表随 token 的 scope 变化(2026-07-28 允许这样),每种 scope 看到的都是对应的列表;
  • 你的服务器从不把客户端的 token 转发给它调用的 API。

清单

步骤 检查什么
质询 不带凭据的请求得到 401,而不是 200、重定向或 HTML 页面
响应头 WWW-Authenticate: Bearer,带 resource_metadata 和 scope
元数据 resource_metadata 地址返回 200 和 JSON
资源 resource 与客户端使用的端点 URL 完全一致
授权服务器 authorization_servers 至少列出一个 issuer
Well-known 同一份文档也放在 /.well-known/oauth-protected-resource 加上你的路径
授权服务器元数据 在客户端会尝试的某个地址上;所有端点都走 HTTPS
Issuer issuer 与 authorization_servers 里的那一项逐字符一致
PKCE code_challenge_methods_supported 包含 S256
端点 MCP 地址直接响应,不经过重定向
有 token 时 无效 → 401;受众不对 → 拒绝;缺 scope → 403 insufficient_scope

上面每一个不带凭据的步骤,都是新客户端最先要走的。想像外部 agent 那样看一遍,而且全程不发送任何凭据,可以在 mcpcheckup.com 粘贴你的地址。