跳转到内容

在代理处保护 MCP 服务器

自己检查令牌的 MCP 服务器需要为此编写代码:获取项目的密钥,检查每个令牌,用正确的请求头回答 401,还要发布一份告诉智能体去哪里登录的文档。用 OAuth 保护 MCP 服务器讲解了这些代码。本页介绍一种可以省掉它们的方式。

你的反向代理(Caddy、Traefik 或 nginx)站在 MCP 服务器前面。每个请求到达服务器之前,代理都会先请你的 FoxAuth 项目检查它。项目检查令牌,以及被调用的工具需要的权限。只有通过检查的请求才会到达你的 MCP 服务器。权限(scope)是令牌携带的一项有名称的许可,例如 files:read。

如果你的代理已经在为 MCP 服务器提供服务,整个过程大约需要十分钟。

对于每个请求,代理都会调用项目的检查地址,例如 https://auth.example.com/acme/verify/api/<checkId>。检查从请求的 Authorization: Bearer 请求头中读取令牌。只有当 MCP 服务器本来要检查的每一项都满足时,它才接受这个令牌:

  • 令牌由项目自己的密钥签名;
  • 令牌由这个项目签发;
  • 令牌是为这个 MCP 服务器签发的,而不是为其他服务器(即它的受众);
  • 令牌没有过期,生效时间也已经到了;
  • 它是访问令牌,而不是 ID 令牌。

项目也可以签发不透明(opaque)令牌:一个随机字符串,里面没有任何可读的内容。检查会在项目中查找这种令牌,只有在它没有过期、也没有被撤销时才接受。

没有令牌或令牌未通过检查的请求会得到 401。响应中的 WWW-Authenticate 响应头会指向一份文档,告诉智能体去哪里登录。这份文档叫作受保护资源元数据(protected resource metadata,RFC 9728),由项目替你发布。你的 MCP 服务器不需要为登录提供任何东西。

  1. 打开你的项目,选择 APIs 标签页,然后点击 New resource。
  2. 填写:
    • Resource identifier:智能体调用的地址,例如 https://mcp.example.com/mcp。它必须是 https 地址,因为检查会把它的主机与代理报告的主机进行比较。
    • Name:用户在授权同意页面上看到的名称。
    • Scopes:你的工具所区分的权限,例如 files:read、files:write 和 files:delete。
    • Who checks tokens?:选择 Your proxy。
  3. 看一下令牌设置。被撤销的自包含令牌在代理处仍然有效,直到它过期(见下文的被撤销的令牌)。所以请选择 Opaque,或者把有效期设得短一些。

你也可以在现有 API 的 Settings 选项卡中把它切换为 Your proxy。切换之前签发的令牌在过期之前仍然有效。

从项目的 APIs 标签页打开该 API 的页面。它的 Connect 选项卡会显示检查地址、元数据地址,以及已经填好你的地址的代理配置。请从那里复制。下面的示例是同一段文字,由同一段代码生成,对应的是项目地址为 https://auth.example.com/acme、MCP 服务器地址为 https://mcp.example.com/mcp 的情况。<checkId> 处会是你的 API 的检查 ID。

每份配置都做三件事:

  • 先把每个请求连同它原来的方法和主机发送给检查。
  • 删除客户端发来的所有 X-Auth-* 请求头,这样谁也无法冒充别人。
  • 把请求连同检查返回的请求头一起转给你的 MCP 服务器。Authorization 请求头原样转发。

这里假设 MCP 服务器本身监听 127.0.0.1:8080。请把它换成真实地址。

Caddyfile
mcp.example.com {
route {
request_header -X-Auth-*
forward_auth https://auth.example.com {
uri /acme/verify/api/<checkId>
header_up Host {upstream_hostport}
copy_headers X-Auth-Subject X-Auth-Client X-Auth-Scope X-Auth-Reason
}
reverse_proxy 127.0.0.1:8080
}
}

route 块会保持指令的书写顺序。没有它,Caddy 会在检查设置好 X-Auth-* 请求头之后又把它们删掉。检查拒绝时,forward_auth 会把检查的回答连同响应头一起返回给客户端。

Traefik dynamic configuration
http:
middlewares:
foxauth:
forwardAuth:
address: "https://auth.example.com/acme/verify/api/<checkId>"
trustForwardHeader: false
authResponseHeadersRegex: "^X-Auth-"
routers:
api:
rule: "Host(`mcp.example.com`)"
entryPoints:
- websecure
middlewares:
- foxauth
service: api
tls: {}
services:
api:
loadBalancer:
servers:
- url: "http://127.0.0.1:8080"

这是给文件提供程序(file provider)用的动态配置。authResponseHeadersRegex 会删除客户端发来的所有 X-Auth-* 请求头,并复制检查返回的那些。检查拒绝时,Traefik 会把检查的完整回答返回给客户端。

nginx configuration
map $status $foxauth_scope_challenge {
403 $foxauth_www_authenticate;
default "";
}
server {
listen 443 ssl;
server_name mcp.example.com;
# ssl_certificate and ssl_certificate_key for mcp.example.com
location / {
auth_request /_foxauth_check;
auth_request_set $foxauth_x_auth_subject $upstream_http_x_auth_subject;
auth_request_set $foxauth_x_auth_client $upstream_http_x_auth_client;
auth_request_set $foxauth_x_auth_scope $upstream_http_x_auth_scope;
auth_request_set $foxauth_x_auth_reason $upstream_http_x_auth_reason;
auth_request_set $foxauth_www_authenticate $upstream_http_www_authenticate;
add_header WWW-Authenticate $foxauth_scope_challenge always;
proxy_set_header X-Auth-Subject $foxauth_x_auth_subject;
proxy_set_header X-Auth-Client $foxauth_x_auth_client;
proxy_set_header X-Auth-Scope $foxauth_x_auth_scope;
proxy_set_header X-Auth-Reason $foxauth_x_auth_reason;
proxy_set_header Host $host;
proxy_pass http://127.0.0.1:8080;
}
location = /_foxauth_check {
internal;
proxy_pass https://auth.example.com/acme/verify/api/<checkId>;
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Uri $request_uri;
proxy_set_header X-Forwarded-Method $request_method;
proxy_set_header Host auth.example.com;
proxy_ssl_server_name on;
proxy_pass_request_body off;
proxy_set_header Content-Length "";
}
}

nginx 的 auth_request 只理解三种回答:允许、401 和 403。遇到 401 时,nginx 会自己把检查返回的 WWW-Authenticate 响应头转给客户端;遇到 403 时则不会,所以开头的 map 会把它加回去。客户端正是从这个请求头得知某个工具需要哪些权限。map 必须放在 http 上下文中,而 conf.d 里的文件本来就在这个上下文中。请在注释所指的位置加上证书配置。

3. 确保只能通过你的代理访问 MCP 服务器

Section titled “3. 确保只能通过你的代理访问 MCP 服务器”

检查只保护经过你的代理的请求。绕过代理到达 MCP 服务器的请求不会经过检查,而服务器会相信它携带的任何 X-Auth-* 请求头。

所以,请让 MCP 服务器只在代理能访问到的地方监听:127.0.0.1、私有网络,或者只放行代理的防火墙规则之后。

请求被放行时,代理会加上这些请求头:

请求头 内容
X-Auth-Subject 令牌代表的是谁:令牌的 sub。对于没有用户参与的机器令牌,它是客户端的 ID。
X-Auth-Client 持有令牌的客户端的 ID,例如智能体宿主。
X-Auth-Scope 令牌的权限,以空格分隔。
X-Auth-Reason 表示决定的简短代码:allowed,或者浏览器 CORS 检查时的 preflight。CORS 检查不带令牌,其他请求头为空。
Authorization 原样转发的令牌。需要用它换取用户在其他服务上的令牌的服务器会用到它。服务器也可以自己再检查一遍。

没有工具表时,任何有效令牌都可以调用任何工具。要设置工具表,请打开该 API 的页面及其 Access 选项卡。

遵循 2026-07-28 版 MCP 规范的 MCP 客户端会用两个请求头说明它要做什么:Mcp-Method(例如 tools/call)和 Mcp-Name(工具名)。检查会读取这两个请求头,所以工具表可以指定每个工具需要哪些权限:

工具 需要的权限
search_files files:read
delete_file files:write, files:delete

权限只能从 API 自己的权限中选择。使用这张表时:

  • 用只含 files:write 的令牌调用 delete_file,会得到 403。它的 WWW-Authenticate 响应头写有 error="insufficient_scope",并列出这个工具需要的所有权限 files:write files:delete。客户端可以据此准确申请这些权限。
  • 列出工具(tools/list)只需要有效令牌,所以客户端总能看到自己可以调用什么。
  • 没有指明工具的 tools/call 会被拒绝。
  • 工具名必须完全一致:Delete_File 和 delete_file 是不同的名字。

工具表下面有两个选项:

  • Any other tool:表中没有列出的工具,要么被拒绝,要么只需要有效令牌。默认是拒绝。
  • Clients too old to say which tool they call:不发送 Mcp-Method、或者使用早于 2026-07-28 的协议版本的客户端,默认会被拒绝。你可以放行它们,但这样它们就能调用任何工具。一旦某个工具有了自己的条件,就不能再放行它们:请参阅旧应用会被拒绝。
  • 读取资源(resources/read)和获取提示词(prompts/get)只需要有效令牌。工具表只针对工具。
  • 代理看得到请求头,看不到请求体。你的 MCP 服务器仍然必须拒绝 Mcp-Name 请求头与请求体所指工具不一致的请求。MCP 规范要求服务器这样做,这也是旧客户端默认被拒绝的原因:它们对应的服务器不会比较这两者。

被撤销的令牌在过期前仍然有效

Section titled “被撤销的令牌在过期前仍然有效”

自包含令牌带有检查所需的一切,所以检查不会去问项目它是否已被撤销。如果去问,每次调用都要多读一次数据库。因此,被撤销的自包含令牌在代理处仍然有效,直到它过期。默认有效期是十五分钟。如果你需要撤销立即生效,请签发不透明令牌:检查会逐个查找它们,被撤销的令牌在下一个请求时就会被拒绝。

有些令牌只能与客户端持有的某个密钥一起使用,方式是 DPoP 或客户端证书(mTLS)。持有密钥的证明属于客户端发给你的 MCP 服务器的那个请求,而代理只转发请求头。所以检查无法证明密钥,它会以 401 和原因 bound_token_unsupported 拒绝这类令牌,而不会把它们当作普通令牌接受。

只有当回答带有 CORS 响应头时,浏览器才允许另一个网站的页面读取它。检查返回的 401 和 403 不带这些请求头。所以,运行在浏览器中的 MCP 客户端无法从拒绝的回答中读取 WWW-Authenticate,除非你的代理为错误回答加上 CORS 响应头。浏览器自己的 CORS 检查(带有 Access-Control-Request-Method 的 OPTIONS)不带令牌,会被放行,由你的 MCP 服务器来回答。

任何能登录项目的人都能获得令牌

Section titled “任何能登录项目的人都能获得令牌”

任何能登录这个项目的人都能获得这个 API 的令牌。要限制谁可以调用它,可以给 API 添加条件(见在代理处添加条件),或给它的某个工具添加条件(见单个工具的条件)。你也可以限制谁可以登录这个项目。

  1. 不带令牌调用你的 MCP 服务器:

    终端窗口
    curl -i https://mcp.example.com/mcp -X POST \
    -H 'content-type: application/json' \
    -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

    你应该得到 401,并带有 WWW-Authenticate: Bearer resource_metadata="…" 响应头。如果得到的是 MCP 服务器自己的回答,说明请求没有经过检查。

  2. 打开 resource_metadata 中的地址。其中的 resource 是你的 API 标识符,authorization_servers 指向你的项目。

  3. 让你的智能体宿主连接你的 MCP 服务器。它会读取这份文档,在项目中让用户登录,然后带着令牌回来。同样的调用现在会到达你的服务器,并带上 X-Auth-* 请求头。

不需要开启任何开关,所有方案都可以使用。

如果只想让某些用户组调用该 API,或只允许来自你的网络、只在你设定的时间内调用,请参阅在代理处添加条件。如果只想对一个工具这样做,请继续往下读。

API 自己的条件对所有工具都有效。有时某一个工具需要更多限制。例如,只有 Ops 用户组可以调用 delete_files,或者只能在工作时间从办公室网络调用 export_billing。其他工具和以前一样开放。

在该 API 的 Access 选项卡的工具表中,点击该工具下方的 Add conditions。一个工具可以带三种条件,控件和 API 自己的条件相同:

  • Groups:此人属于你选择的某个用户组。
  • From where:地址在你的地址范围之内,或不在其中。它还可以挡住 FoxTrust 网络信息所指的网络,例如 Tor。你的代理必须传递用户的地址,做法见 From where。
  • When:日期和时段,按 API 的时区计算。一个 API 只有一个时区。

一个工具最多有四个条件。工具的条件中没有属性,也没有重新登录。验证码或近期登录针对整个 API 设置:请参阅连接时要求验证码或近期登录。

  • 工具的条件加在 API 的条件之上。它们永远不会取代或放宽 API 的条件。如果 API 只允许 Staff 用户组,而 delete_files 只允许 Ops 用户组,那么只有同时属于这两个用户组的人才能调用 delete_files。
  • 在工具下方,编辑器会把 API 的条件标为来自 API。在那里无法删除它们。
  • 检查按这个顺序判断:API 的条件、API 的登录要求、MCP 请求头、工具需要的权限,最后是工具的条件。
  • 缺少工具所需权限的令牌会和以前一样收到 insufficient_scope。它不会得知工具的任何条件。
  • 一个工具可以有条件而不需要任何权限。表中的每个工具至少需要一个权限或一个条件。
  • 只有指明该工具的 tools/call 才会按它的条件判断。列出工具和开始会话不受影响。

删除或放宽工具的条件,会让更多调用通过。所以控制台会列出放宽了什么,并在保存前请你确认。添加条件会立即保存。

不满足工具条件的调用会收到 403。X-Auth-Reason 说明原因:

原因 含义
not_in_group 此人不在工具的用户组中,或不在 API 的用户组中。
not_from_network 条件不允许这个地址,或者代理没有传来可信的地址。
network_facts_unknown 网络信息已关闭或超过 26 小时,所以需要它的条件会拒绝。
outside_hours 调用发生在允许的时段之外,按 API 的时区计算。
no_person 令牌不代表任何人,例如应用为自己获取的令牌。
cannot_sign_in 此人已被锁定或停用。

被拒绝的调用永远不会是 401,也永远不会要求此人重新登录。重新登录不会让人加入某个用户组,也不会让人回到办公室。回答中既不写工具名,也不写它的条件。

代理看得到请求头,看不到请求体。工具名来自应用发送的 Mcp-Name 请求头。

工具的条件能挡住如实说明自己调用哪个工具的应用。如果被盗的令牌在一个谎报工具的应用中使用,只有你的 MCP 服务器把请求头和请求体对照检查,才能挡住它。MCP 2026-07-28 的服务器必须这样做。要让某人完全无法使用整个 API,请使用 API 自己的条件或它的登录要求。

所以,工具的条件防的是智能体的失误,而不是持有被盗令牌的人。

太旧、无法说明自己调用哪个工具的应用,无法按单个工具的条件来判断。这类应用不发送 Mcp-Method 请求头,或者使用早于 2026-07-28 的 MCP 协议。所以,只要有任何工具带有条件,Clients too old to say which tool they call 就必须选 Refuse them。控制台会禁用 Let them in,要求放行它们的保存会以 422 被拒绝。目前这样的应用很多,具体是哪些,请看下面的表格。

MCP 服务器上新增或改名的工具还不在工具表中。在你把它加进表之前,它按 Any other tool 的设置处理。

该 API 的 Access 选项卡最下方有一张 Check access 卡片。选择一个人,或者选择 No person: an app acting for itself(没有对应的人:应用以自己的身份行事)。然后选择应用令牌持有的权限、调用的工具或其他请求、地址和时间。如果 API 要求验证码或近期登录,还要说明登录时是否输入了验证码,以及何时登录。

卡片会回答 Allowed(允许)、Refused(拒绝)或 Asked to sign in again(要求重新登录),并用平实的话说明原因。它会分别针对已保存的工具表和你正在编辑的工具表作答。如果缺少需要的信息,它会回答 Not known(未知),并说明缺少什么。卡片在你的浏览器中运行与代理处检查相同的判断。不由任何服务器替它判断,也不会写入审计记录。如果某个条件需要网络信息,卡片会在你的服务器自己的副本中查找这个地址。

智能体可以用 resource_update 设置工具的条件,即 tools 中某一行的 conditions。单个工具的条件在所有方案中免费提供。

令牌只说明有人登录了这个项目,并不说明是怎样登录的。所以,一个被盗的密码就足以让智能体连接到你的 MCP 服务器。API 的 Access 选项卡中的两项设置可以改变这一点。打开项目的 APIs 标签页,再打开该 API,然后打开 Access:

  • Require a code from an authenticator app。只有在用户登录时输入了身份验证器应用(例如 Google Authenticator)中的验证码之后,才会为这个 API 签发令牌。
  • Ask to sign in again every。选择每天、每 7 天、每 14 天,或 Custom:一个整数的小时数或天数,从 1 小时到 14 天。令牌所代表的用户,其登录时间不能早于这个时长。

可以只设置其中一项,也可以两项都设置。无论谁检查这个 API 的令牌(你的代理或 API 自己的服务器),这两项设置都有效。智能体也可以通过管理 MCP 服务器设置它们:在 resource_declare 和 resource_update 中使用 requireCode 和 signInEveryMinutes。所有方案均免费提供。

API 要求更强或更近期的登录时,有一个标准的回答:带有 error="insufficient_user_authentication" 的 401(RFC 9470)。截至 2026-11-12,我们查看过的 MCP 客户端都不理解它。但每个客户端在收到 401 时都会去申请新令牌。这个令牌由 FoxAuth 签发,所以 FoxAuth 自己保证这一要求得到满足:

  • 当用户为获取这个 API 的令牌而登录时,无论客户端请求了什么,FoxAuth 都会要求输入验证码。如果用户的登录早于允许的时长,FoxAuth 会要求重新登录。
  • 登录页面上有一行文字写出 API 的名称,例如“Files 需要身份验证器应用中的验证码才能连接。”或“Files 要求您每天重新登录一次,以保持连接。”
  • 没有身份验证器应用的用户可以在同一次登录中设置一个,前提是项目允许用户自行设置。
  • 为用户获取令牌的每一种方式都会检查这一要求:授权码、设备流程(device flow)、CIBA 和刷新令牌。
  • 如果用刷新令牌续期得到的令牌不满足要求,续期会以 invalid_grant 被拒绝。刷新令牌本身不会被用掉。客户端随后会开始新的登录,而该用户的其他连接继续正常工作。
  • 在你的代理处,检查会根据每个令牌来自的那次登录来判断它。不满足要求的令牌会收到 401,带有 WWW-Authenticate: Bearer error="insufficient_user_authentication" 以及 acr_values="…" 或 max_age="…"。这是标准的质询,供将来支持它的客户端使用。X-Auth-Reason 为 code_required 或 sign_in_not_fresh。
  • 令牌内省会返回 acr 和 auth_time,所以自己检查令牌的 API 也可以应用同样的规则。

对于自己检查令牌的 API,已经签发的令牌由它自己决定如何处理。在你开启要求之前签发的令牌,在那里会一直有效到过期,除非你的服务器检查令牌中的 acr 和 auth_time。它的续期则无论如何都会被拒绝。

有些令牌并不对应 FoxAuth 看到过的任何登录。重新登录也无法改变这一点,所以它们会被直接拒绝,而不是被要求重新登录:

  • 不代表任何人的应用。通过 client credentials 授权类型为自己获取令牌的应用,拿不到这个 API 的令牌。在你的代理处,这样的令牌会收到 403。
  • 通过断言(assertion)登录。来自 JWT bearer 授权类型、identity assertions 或 ID-JAG 的令牌也会被拒绝。用户是在别处登录的,FoxAuth 无法知道是怎样登录的。

通过身份提供方(例如 Google 或你公司的身份提供方)登录的人是第三种情况。他们无法在 FoxAuth 输入验证码。所以当 API 要求验证码时,登录页面会告诉他们无法以这种方式连接。当 API 只要求重新登录时,FoxAuth 会把他们送到身份提供方重新登录。怎样重新登录由身份提供方决定,FoxAuth 无法确认他们确实重新登录了。

开启要求或缩短时长时,控制台会先告诉你会影响哪些人:

  • 能访问这个 API 的人中,有多少人没有身份验证器应用;
  • 有多少人只能通过身份提供方登录;
  • 有多少人拥有包含这个 API 的有效连接。

控制台还会列出将无法再连接的应用:不代表任何人的应用,以及通过断言登录的应用。这些数字以“Up to”(最多)开头,因为 FoxAuth 不会记录谁在使用每个 API。你需要根据这些数字确认更改。智能体也会得到同样的数字:第一次调用返回 409 confirmationRequired,智能体再带上 confirm: true 重复这次调用。

如果你把实例升级到这个版本,请先运行 bun run db:migrate。之后,较旧的版本会拒绝在这个数据库上启动,因此不会签发绕过验证码的令牌。

FoxAuth 会拒绝旧令牌或它的续期,并在下一次登录时提出要求。在这两者之间用户看到什么,取决于他们使用的应用。最后一列说明应用是否按 MCP 2026-07-28 的要求说明自己调用的工具。不说明的应用,会被工具带有自己条件的 API 拒绝。下表来自各个应用的代码、文档和问题跟踪器,是我们在 2026-11-12 阅读的结果。我们还没有逐一实际试用每个应用。在依赖它之前,请用你的用户实际使用的应用试一试。

应用 用户看到什么 用户要做什么 说明调用哪个工具(MCP 2026-07-28)
Claude Code 续期令牌并再试一次。然后把服务器标记为需要身份验证。 运行 /mcp,选择该服务器,再选择 Re-authenticate。调用不会自动继续,需要再问一次。 是
claude.ai、Claude Desktop Connect 卡片和登录窗口。文档中描述的是令牌无效的情况,我们还没有在这种质询下见到过。 选择 Connect 并登录。 未核实
ChatGPT 可能只显示一个错误。 在 ChatGPT 的设置中重新连接该连接器。 未核实
Codex 可能会反复重试被拒绝的续期。 重新连接该服务器。 否
VS Code(GitHub Copilot) 登录窗口。同时进行的多个调用可能会打开多个窗口。 在其中一个窗口登录。在另一个窗口再次输入同一个验证码时,会显示“此验证码刚刚已被使用。请等待下一个验证码。” 否
Cursor、Zed、Gemini CLI 服务器被标记为需要身份验证。 手动为该服务器重新进行身份验证。 否

Goose 从 1.48.0 版起也会说明自己调用的工具。

如果应用在重新登录之后没有继续,请让它再试一次。

  1. 按照第 1 步声明一个 MCP 服务器并配置你的代理,或者使用已有的服务器。
  2. 打开它的 Access 选项卡,打开 Require a code from an authenticator app。查看会影响哪些人,然后保存。
  3. 用你的 MCP 客户端连接这个服务器。登录页面会写出 API 的名称,并在输入密码后要求输入验证码。如果你没有身份验证器应用,可以在那里设置一个。
  4. 调用一个工具。它可以正常工作。
  5. 在同一个选项卡中,把 Ask to sign in again every 设为 Custom、1 小时,然后保存。
  6. 一小时后再次调用工具。下一次续期会被拒绝,你的客户端会要求你重新登录,或者按上表中对它的描述行事。
  7. 如果应用在重新登录之后没有继续,请让它再试一次。