MCP 生产化:认证与 Registry

QuibblerAgentQuibblerAgent 2026-11-20 约 20 分钟 21 次阅读

第 6 篇《MCP 传输层:stdio 与 Streamable HTTP》收尾时留了个口子:TLS、Host 白名单、容器、反向代理全部就位,最后还差一层认证令牌——令牌怎么发、怎么验,是第 7 篇的主题。本篇兑现承诺:《MCP 协议与实现》第 7 篇、传输与部署层收官篇,把部署上线后的三道关一次走完——认证关(谁能调用你的 server)、发现关(客户端怎么找到你)、运营关(上线之后怎么管)。全文按"三道关 → OAuth 角色模型 → PKCE 与 resource → 2026-07-28 硬化 → SDK 实操 → Registry 发布 → 运营清单"组织,口径以规范 2026-07-28 版授权章节、mcp 2.3.0 官方文档与 Registry 仓库为准(本文写作时 2026 年 11 月)。


1、上线三道关

第 6 篇结束时,知识库 server 已经以容器形态跑在 nginx 后面——但只要拿到 URL,任何人都能 curl 进来调 search。这不是疏忽,是部署顺序:先把传输与安全边界立好,再上身份层。生产化剩余的路恰好分成三道关。

  • 认证关:谁来发令牌、server 怎么验令牌、验完怎么用
  • 发现关:客户端怎么找到授权服务器,全网怎么找到你
  • 运营关:监控、限流、权限与版本的日常策略

先定总基调:MCP 没有发明新的认证协议,授权层完整构建在 OAuth 2.1 之上。第 1 篇年表提过 2025 年 3 月修订版引入 OAuth 2.1 授权;2025-06-18 版把它拧紧成硬约束——PKCE(Proof Key for Code Exchange)必选、令牌按 RFC 8707 绑定 resource;2026-07-28 GA 版再硬化一轮,第 4 节专讲。三道关的顺序也是本篇的顺序。

2、server 是资源服务器

OAuth 世界里有三种角色,MCP 规范的分工直白:受保护的 MCP server 扮演 OAuth 2.1 资源服务器,接受并响应携带访问令牌的请求;MCP 客户端扮演 OAuth 2.1 客户端;授权服务器负责与用户交互并签发令牌。授权服务器可以与 server 同体部署,也可以是独立实体,规范明确它的实现细节不在协议范围内。

这个分工是本篇最重要的心智模型:资源服务器只验令牌,不发令牌。你的 server 上没有登录页、没有同意屏、不签发任何令牌,它做的只有一件事——检查每个请求的 Authorization 头,通过则放行、否则挑战。签发侧交给专业选手:生产环境直接对接现成 IdP(Identity Provider,身份提供方),如 Keycloak、Auth0、Entra ID,不要自己写授权服务器。三方在一轮完整授权里的协作如下。

flowchart LR C[MCP 客户端] -->|无令牌请求| S[MCP server] S -->|401 附元数据地址| C C -->|PKCE 授权| A[授权服务器] A -->|签发访问令牌| C C -->|Bearer 令牌| S S -->|验受众后放行| C

解读:整条链从 401 开始。客户端第一次不带令牌打进来,server 在解析任何协议内容之前直接回 401,WWW-Authenticate 头里带 resource_metadata 指向自己的受保护资源元数据文档;客户端取文档、按图索骥找到授权服务器,走授权码流程拿令牌,再带 Authorization: Bearer 头重试原请求。那条 401 响应长这样。

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

解读:元数据文档由 RFC 9728 定义,MCP server 必须实现——它声明"我是哪个资源、信任哪些授权服务器、需要哪些 scope",是授权发现的起点。scope 直接写进挑战头也有讲究:客户端第一跳就知道该申请什么权限,这是规范推荐的最小权限路径。

两条硬约束顺带记下:令牌只走请求头,严禁拼进 URL 查询串——查询串会进访问日志;server 只收明确发给自己的令牌,受众不符一律 401。另外这套模型只服务 HTTP 传输,规范明言 stdio 不应走 OAuth,凭证从环境变量获取,也就是第 6 篇 JSON 配置里 env 字段的用途。

3、PKCE 与 resource 的动机

规范点名要这两样,各自的靶子不同。

PKCE 防授权码截获。MCP 客户端大多是本地应用或 Agent 进程,在 OAuth 语境里是"公共客户端"——装在用户设备上,守不住 client secret。授权码要经浏览器重定向回传,路径上任何能看到重定向 URL 的一方,理论上都能拿码换令牌。PKCE 把授权码和申请者绑死:客户端先交 code_challenge(随机验证器的哈希),换令牌时出示原验证器 code_verifier,对不上则拒发——截获了码也换不出令牌。OAuth 2.1 把 PKCE 从"公共客户端的建议"升为所有客户端必选,MCP 照单全收。

resource 防令牌串门。没有受众绑定时会出两类事故:一是混淆代理人(confused deputy)——恶意 server 诱导客户端申请一枚发给正经 server 的令牌,然后据为己有,借客户端的身份干坏事;二是令牌注入——把 A 家授权服务器签的令牌塞给 B 家的 server 冒充身份。RFC 8707 的解法是让客户端在授权请求与令牌请求两处都带 resource 参数、写明这枚令牌给哪个 server 用,授权服务器把它烙进令牌的受众字段,server 收到时核对——不是发给我的,一律拒收。规范把话说满:客户端必须实现 RFC 8707;server 必须按受众校验令牌,不得接收或转发任何其他令牌;客户端也不得把别家签发的令牌送来。

resource 的取值就是 server 的规范 URI:如 https://mcp.example.com/mcp,小写、不带尾斜杠。第 2 节 401 挑战里的元数据文档同样以它为 resource 字段——同一个标识贯穿授权全程。

4、2026-07-28 认证硬化

协议侧的演化没有停在 2025-06-18。GA 版在客户端注册与响应校验上又拧了两圈,企业场景补了扩展,变化对比如下。

硬化项 之前的做法 2026-07-28 起
响应发行方校验 授权响应不标发行方,多授权服务器混用时有 mix-up 风险 授权服务器应在响应带 iss 参数,客户端按 RFC 9207 逐次校验,未来从 SHOULD 升为 MUST
客户端注册 以 RFC 7591 动态客户端注册(DCR)为主 首选 CIMD:客户端把元数据文档发布在 HTTPS URL 上、以该 URL 充当 client_id;DCR 降为可选并标记废弃
企业授权 无标准方案 EMA 企业托管授权扩展:授权治理收敛到企业统一托管的授权服务器

iss 一句话解读:客户端发起授权前记下元数据里的发行方,授权响应回来先对 iss——发行方对不上,连 error 字段都不许展示,防的就是把回调引向假授权服务器的钓鱼。CIMD(Client ID Metadata Documents)一句话:注册从"向授权服务器申请 client_id"变成"自己发布一份可抓取的元数据文档",客户端身份就是那个 HTTPS URL,授权服务器抓取校验后即认——没有注册端点的轻量授权服务器也能接入。DCR 保留只为兼容存量,新实现按 CIMD 走。EMA 与其他授权扩展都放在可选、可组合的扩展仓库里,按需取用。

5、实操:配置 OAuth 资源服务器

5.1、构造器配 AuthSettings

SDK 侧的接入面出乎意料地小。按官方授权文档,给第 3 篇的知识库 server 加认证,改动全部落在构造器上,代码如下。

mcp = MCPServer(
    "内部知识库",
    token_verifier=KbTokenVerifier(),  # 与 auth 必须成对出现
    auth=AuthSettings(
        issuer_url=AnyHttpUrl("https://auth.example.com"),
        resource_server_url=AnyHttpUrl("https://mcp.example.com/mcp"),
        required_scopes=["kb:read"],
        validate_token_resource=True,
    ),
)

解读:token_verifier 与 auth 必须成对传入,只给一个构造器直接抛 ValueError。AuthSettings 的四个参数各管一件事,说明如下。

参数 作用
issuer_url 签发令牌的授权服务器,写进元数据文档
resource_server_url 本服务公网地址,即 RFC 8707 的 resource 标识
required_scopes 每枚令牌必须携带的 scope 集合
validate_token_resource 校验令牌受众与本服务地址一致

一个值得注意的默认值:validate_token_resource 未显式设置时,当前版本行为是关闭并弹弃用警告,3.0 起默认开启——新代码直接显式写 True。例外场景:IdP 用自己的受众标识(Auth0 的 API ID、Entra 的应用 ID)时把它关掉,回到校验器里自己核对 aud。

5.2、校验器与调用方身份

AuthSettings 声明"信谁",TokenVerifier 决定"怎么验"。它是整个认证集成的全部自定义面——一个异步方法,进令牌串、出令牌对象或 None,写法如下。

class KbTokenVerifier(TokenVerifier):
    async def verify_token(self, token: str) -> AccessToken | None:
        # 验 JWT 签名与受众,或调 RFC 7662 内省端点
        ...

解读:返回 None 即拒识,SDK 自动以 401 加 WWW-Authenticate 挑战回敬,三原语代码一行不用改。验过的令牌被装成 AccessToken——client_id、scopes、resource、过期时间与自定义声明齐全。真实实现有两条主流路线:本地验 JWT 签名,或调授权服务器的 RFC 7662 内省端点,官方仓库的 simple-auth 示例两条都有。配置生效后,服务会多出一条发现路由 /.well-known/oauth-protected-resource/mcp,返回内容如下。

{
  "resource": "https://mcp.example.com/mcp",
  "authorization_servers": ["https://auth.example.com/"],
  "scopes_supported": ["kb:read"],
  "bearer_methods_supported": ["header"]
}

解读:这正是第 2 节 401 舞蹈里客户端要取的 RFC 9728 文档——SDK 按 resource_server_url 与 issuer_url 自动生成,授权发现链路零代码。handler 里拿调用方身份同样是一行,代码如下。

from mcp.server.auth.middleware.auth_context import get_access_token

@mcp.tool()
def whoami() -> str:
    token = get_access_token()
    if token is None:
        return "anonymous"
    return f"{token.client_id} (scopes: {', '.join(token.scopes)})"

解读:get_access_token 从每请求的上下文变量里取当前令牌,工具、资源、prompt 三种 handler 通用。拿 client_id 与 scopes 就能做按调用方的细粒度控制——比如 kb:write 只放行运维客户端,search 人人可用。两条边界提醒:进程内 Client(mcp) 测试直连不经过 HTTP 与认证,第 5 篇的 pytest 套件照常可跑;构造器还有个 auth_server_provider 参数能把整套授权服务器嵌进 server,但它早于授权服务器与资源服务器分离的设计,官方不建议新代码使用。

6、发布到官方 Registry

第二道关的生态侧。官方 Registry 是 MCP server 的应用商店:作者登记元数据,客户端按名字检索、按地址接入。节奏三步走——2025-09-08 开启预览,2025-10-24 冻结 0.1 版 REST API 并承诺不再破坏性变更,2026 年 5 月前后转正。

发布不走 PR:往 Registry 仓库提 server.json 或建目录不会被收录,唯一入口是在你自己的 server 项目里跑 mcp-publisher,命令如下。

git clone https://github.com/modelcontextprotocol/registry
cd registry
make publisher                 # 构建发布器
./bin/mcp-publisher --help     # 回到你的 server 项目里执行发布

解读:publisher 先校验 server.json 是否符合 0.1 冻结版 schema——名称、版本、描述与接入信息都在里面——再以你的身份提交入库。持续发布可以放进 GitHub Actions,用 GitHub OIDC 认证,流水线全自动。

防冒名靠命名空间验证。条目名是反域名记法:io.github.用户名/server 要求你以该 GitHub 账号登录,或在本人仓库的 Action 里运行;想用自有域名(如 me.adamjones/…)要先证明 adamjones.me 归你——DNS TXT 记录或 HTTP 挑战二选一。名字即身份:对调用方来说,条目前缀直接告诉你该信任谁——GitHub 账号,还是域名所有者。

7、运营清单

第三道关收拢成一张日常清单,四个主题如下。

主题 要点
监控 日志按 Mcp-Method 与 Mcp-Name 聚合工具级流量;盯 401 与 403 比率,骤升多为令牌过期或配置漂移
限流 网关按头路由面给 list 与 call 差异化配额(第 2 篇),认证后再按 client_id 细分配额
权限 scope 走最小集,运行时缺权限回 403 加 scope 挑战,客户端补授权重试
版本 新 server 只实现现代路径;存量按旧客户端占比走双时代分流,盯第 2 篇的十二个月废弃窗口

权限行展开一句:这正是规范的 step-up 升级流——令牌 scope 不够时 server 回 403,WWW-Authenticate 里写明 insufficient_scope 与本次操作所需 scope,客户端把它们并入已授权集合申请新令牌重试。server 侧要一次把缺的权限列全,不要挤牙膏式的一条条挑战。另一个容易忽略的细节:server 的元数据与挑战里都不该出现 offline_access——刷新令牌是客户端与授权服务器之间的事,资源服务器对它没有需求。

第 6 篇预告过多租户,认证落地后它不需要额外机制:client_id 就是天然的租户键——scope 定每个调用方的权限边界,配额定用量上限,数据按租户键隔离;第 2 篇的无状态内核保证了任意实例都能服务任意租户,扩缩容照旧。

8、总结

三道关到此合拢。认证关:MCP server 是 OAuth 2.1 资源服务器,只验令牌不签令牌,签发交给独立 IdP;PKCE 把授权码和申请者绑死,resource 把令牌和受众绑死;2026-07-28 再加 iss 校验与 CIMD,客户端注册与响应校验同样焊死。实操面:一个 TokenVerifier 加一组 AuthSettings 装齐,SDK 自动生成 RFC 9728 发现文档与 401 挑战,handler 里 get_access_token 拿调用方身份做细粒度授权。发现关:Registry 反域名命名空间加 DNS 验证,GitHub OIDC 供流水线发布。运营关:头路由聚合观测、按 client_id 配额、scope 最小化加 step-up。留三道练习:

  • 给知识库 server 接一个 Keycloak,用 curl 走完 401 到重试的完整链路,抓下 WWW-Authenticate 逐字段核对
  • 写一个调 RFC 7662 内省端点的 TokenVerifier,对某枚令牌故意返回 None,确认 401 挑战格式与日志路径
  • 把知识库发布到 Registry 的 GitHub 命名空间,再用 REST API 按名字检索出来,对照 server.json 逐字段检查

对于已经按第 6 篇把服务搬上公网的读者,建议顺序走第 5、6 节:半天补认证、半天登记 Registry,服务就从"能用"进到"可托付"。本系列传输与部署层至此收束,下一篇转入源码篇——把 SDK 里传输与认证这套机制的实现代码拆开读。

相关推荐

​Jev 详解:不做生成的判断模型
精选AI

​Jev 详解:不做生成的判断模型

Jev 详解:不做生成的判断模型让 LLM 干"判断"的活,一直是件拧巴的事:它擅长生成文本给人读,你要的却是结构化决策给代码用——于是提示词约束、JSON 解析、重试兜底一层层糊上去。TypeSafe AI 的答案是干脆换一类模型:Jev,首个 System One 模型——不做文本生成,专职快速、结构化的判断:输入状态与类型化问题,输出带概率与置信度的结构化答案,类型错误在数学上不可能发生,因

762
网站被注入恶意脚本排查实录:AI 辅助安全分析实战
置顶 精选AI

网站被注入恶意脚本排查实录:AI 辅助安全分析实战

网站被注入恶意脚本排查实录:AI 辅助安全分析实战某天收到华为云监管反馈,称个人博客网站存在色情违规界面。作为技术博主,这简直是晴天霹雳——网站一直正常运行,怎么会突然出现这类问题?经过排查发现,网站被注入了恶意跳转脚本。本文记录完整的排查过程,重点分享如何借助 AI 快速定位问题并修复,希望能给遇到类似情况的开发者提供参考。1、问题发现与初步排查收到监管反馈后,第一时间打开网站检查。首页看起来完

451
博客七周年:AI 一天完成整体重构
全站置顶 精选AI

博客七周年:AI 一天完成整体重构

博客从 2019 年国庆用 Xiuno BBS 搭建,到 2026 年国庆整整七年。868 篇文章、53 条评论、6060 个代码块,这次与 AI Agent 结对,一天完成从 PHP 论坛到 Next.js 的整体重构与无损迁移。

430