第 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,不要自己写授权服务器。三方在一轮完整授权里的协作如下。
解读:整条链从 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 里传输与认证这套机制的实现代码拆开读。

