MCP Python SDK · 第 11 章认证与授权:OAuth 2.1 全链路

文档摘要

MCP Python SDK · 第 11 章认证与授权:OAuth 2.1 全链路章节摘要:把一个流式 HTTP 服务端暴露到公网,第一个绕不开的问题就是「谁能调」。本章讲透 MCP 的认证授权全链路,核心是一套基于 OAuth 2.1 的双向实现。服务端一侧,SDK 提供了一个完整的授权服务器(Authorization Server)——你只需实现一个「客户端与令牌」的存储接口,SDK 替你处理授权码流、令牌签发、校验、吊销这些标准 OAuth 流程;客户端一侧,SDK 提供了 (OAuth 客户端提供者)抽象,让在连接受保护服务时自动走令牌获取与刷新。两端协同,构成「服务端保护资源、客户端持令牌访问」的完整闭环。

MCP Python SDK · 第 11 章认证与授权:OAuth 2.1 全链路

章节摘要:把一个流式 HTTP 服务端暴露到公网,第一个绕不开的问题就是「谁能调」。本章讲透 MCP 的认证授权全链路,核心是一套基于 OAuth 2.1 的双向实现。服务端一侧,SDK 提供了一个完整的授权服务器(Authorization Server)——你只需实现一个「客户端与令牌」的存储接口,SDK 替你处理授权码流、令牌签发、校验、吊销这些标准 OAuth 流程;客户端一侧,SDK 提供了 OAuthClientProvider(OAuth 客户端提供者)抽象,让 Client 在连接受保护服务时自动走令牌获取与刷新。两端协同,构成「服务端保护资源、客户端持令牌访问」的完整闭环。我们还会覆盖两个扩展——客户端凭证(机器到机器,无用户参与)与身份断言(把外部身份带进 MCP)。读完本章,你能为你的 MCP 服务加上完整的 OAuth 保护,并让客户端接通。

学习目标

阅读完本章,你应当能够:

区分 OAuth 2.1 的角色(资源所有者、客户端、授权服务器、资源服务器),并说明 MCP 服务端如何同时承担后两者。
在服务端实现一个授权服务器——实现「客户端与令牌」存储接口,让 SDK 替你跑授权码流、令牌签发与校验、Bearer 令牌中间件。
在客户端实现一个 OAuthClientProvider——让 Client 在连接受保护服务时自动获取与刷新令牌,处理浏览器跳转与本地回调。
用客户端凭证扩展(Client Credentials) 实现机器到机器的认证(无用户参与),适用于服务间调用。
用身份断言扩展(Identity Assertion) 把一个外部身份(如已登录的 SSO)带进 MCP,避免重复登录。

核心概念速览

整章逻辑可浓缩为一句话:MCP 的认证授权是一套 OAuth 2.1 的双向实现——服务端既当授权服务器(签发令牌)又当资源服务器(校验令牌),客户端用 OAuthClientProvider 自动获取与刷新令牌,两端协同构成「持令牌访问」的完整闭环,你只需实现存储与跳转两件事。

子章节导航

01 OAuth 2.1 角色与 MCP 的承担方式

先理清理论。讲清 OAuth 2.1 的四个角色,以及 MCP 服务端的特殊之处——它同时承担授权服务器(签发令牌)与资源服务器(校验令牌、保护资源)两个职责。用一张图说明「一个 MCP 服务端内含两套 OAuth 逻辑」的架构。

02 服务端授权服务器:实现客户端与令牌存储

讲清 SDK 提供的授权服务器骨架:你实现「客户端注册存储」「令牌存储」「授权码存储」这几个接口,SDK 替你处理授权码流(authorize)、令牌签发(token)、客户端注册(register)、令牌吊销(revoke)、元数据(metadata)这些标准端点。Bearer 令牌中间件(bearer_auth)自动校验每个进来的请求。

03 客户端 OAuth:OAuthClientProvider 抽象

客户端一侧。讲清 OAuthClientProvider 如何让 Client 在连接受保护服务时自动走令牌获取——浏览器跳转授权页、用户同意、本地回调收令牌、后续请求带令牌、过期自动刷新。说明你需要实现的几个回调(发现元数据、跳转、收回调、存取令牌)。

04 客户端凭证扩展:机器到机器

并非所有调用都有用户参与——服务间调用、定时任务、后台编排,都是「机器到机器」。客户端凭证扩展(Client Credentials)让一个客户端用自己的凭证直接换令牌,无需用户授权。讲清它的适用场景与实现方式。

05 身份断言扩展:把外部身份带进来

你已经有一个 SSO、一个公司身份系统、一个第三方登录,不想让用户在 MCP 里再登录一次。身份断言扩展(Identity Assertion)让你把一个已有的外部身份「断言」进 MCP,换得一个 MCP 令牌。讲清它如何避免重复登录,以及它与服务端信任配置的关系。

子章节之间的逻辑关系

本章遵循「理论 → 服务端 → 客户端 → 无人参与 → 外部身份」的递进,先建模型再分别实现两端,最后扩展两种特殊场景:


OAuth 角色 (01) ── MCP 服务端的双重承担
   │
   ▼
服务端 (02)    ── 授权服务器 + Bearer 中间件
   │
   ▼
客户端 (03)    ── OAuthClientProvider 全流程
   │
   ▼
客户端凭证 (04) ── 机器到机器
   │
   ▼
身份断言 (05)   ── 把外部身份带进来
   │
   ▼
第 12 章:最后一章——装饰器糖之下,如何扩展 SDK 本身

理清角色是前提,服务端与客户端是必须成对理解的两半(只看一侧会困惑),客户端凭证与身份断言覆盖两种常见但容易被忽略的特殊场景。本章与第 8 章(传输安全)共同构成「把 MCP 服务公开到公网」的全部安全考量——第 8 章是网络层防护,本章是应用层认证。

前置知识与后续延伸

前置知识:

第 8 章的流式 HTTP 传输(认证跑在 HTTP 传输之上)
第 8 章的传输安全(DNS 重绑定防护是网络层前提)
第 9、10 章的客户端构造与生命周期(本章扩展「带认证的客户端」)
对 OAuth 2.1 / OIDC 的基本概念(非必需,有助理解)

本章为后续章节奠定的基础:

认证机制是部署到生产的必备能力,会被附录速查与排错反复引用
客户端凭证扩展是第 10 章(会话组编排多个服务)在生产环境的认证配套
身份断言思想会在第 12 章(扩展)被引用为「不改协议地引入外部信息」的范例
Bearer 中间件是第 12 章(中间件)的具体实例之一

MCP Python SDK · 第 11 章 认证与授权:OAuth 2.1 全链路

文档摘要