MCP Python SDK · 技术教程

MCP Python SDK · 技术教程

官方 Python SDK 的硬核拆解——从「类型即契约」到「传输分离」,讲透一个把任意能力暴露给大语言模型的工程框架

这本教程讲什么

本教程是模型上下文协议(Model Context Protocol, MCP)官方 Python SDK 的体系化中文教程。MCP 是一套让大语言模型(LLM)标准化连接外部工具与数据源的协议——你可以把它理解成「专门为 AI 应用设计的 Web API」:任何一个宿主(Claude Desktop、Cursor、各类 IDE 或 Agent 运行时)都能用同一套协议,接入你写好的服务端,获取它暴露的工具、资源与提示词。

这个 SDK 解决的核心矛盾是:协议本身是 JSON-RPC,握手、能力声明、分帧、版本协商一应俱全,但写服务端的人不该被这些拖住。所以 SDK 做了一件关键的事——让一个普通 Python 函数的类型注解,自动变成模型能理解的工具契约。你写 def add(a: int, b: int) -> int,SDK 替你生成输入 Schema、输出 Schema、能力声明、请求分发;你不写一行协议帧,模型就能调用它。

本教程的版本策略需要先讲清楚:全程基于 v2 版 API(对应 2026-07-28 协议规范)。网上大量旧教程还在用 FastMCP 这个名字,它在 v2 里已改名为 MCPServer,且配套出现了第一类的 Client、新的 Resolve 依赖机制。这些差异会在附录里集中说明,正文一律用 v2 写法,以免你被旧资料带偏。

本教程客户端与服务端并重。服务端一侧讲透「如何写一个 MCP 服务」(三大原语、上下文、传输、认证),客户端一侧讲透「如何用 Client 连接并编排 MCP 服务」(会话、会话组、缓存、订阅)。两边共用架构、传输、认证等横切章节,共同构成一张完整的协议工程地图。

学习路径一览

本教程按「跑起来 → 看懂架构 → 写服务端 → 写客户端 → 拔高」的递进逻辑组织,共十二章加一个附录:

第 1 章 环境准备与首次跑通 ── 5 分钟拿到第一次工具调用
   安装 · 最小服务端 · 内存客户端 · MCP 检查器
        │
第 2 章 核心概念与整体架构 ── 建立全局地图(承前启后)
   Host/Client/Server 三角 · 两层服务端模型 · 一次调用的生命周期
        │
第 3 ~ 8 章 服务端主线 ── 把能力暴露出去
   三大原语 · 工具契约 · 资源/提示词 · 上下文/依赖 · 交互式能力 · 传输
        │
第 9 ~ 10 章 客户端主线 ── 把能力消费起来
   Client 与会话 · 传输/会话组/缓存/订阅
        │
第 11 ~ 12 章 横切拔高 ── 从会用到能改
   OAuth 全链路 · 低层 API/扩展/中间件/可观测性
        │
附录 A 术语表 · 速查 · 排错(含 v1→v2 迁移要点)
​

如果你只想快速试用,看第 1 章就够;想理解整体设计,第 2 章是地图;想知道一个工具怎么从函数走到模型可调用,重点读第 4 章;对「工具执行中途怎么向用户反问」感兴趣,第 7 章是全书最有意思的部分;要部署生产级 HTTP 服务或接认证,直接翻第 8、11 章。

章节目录

第 1 章 环境准备与首次跑通
版本要求与安装方式、依赖解读、最小可运行服务端(一个工具加一个资源模板)、用内存客户端验证、用 MCP 检查器(Inspector)可视化调试。读完你能写出一个三装饰器服务端并亲手调通。

第 2 章 核心概念与整体架构(全书地图)
Host/Client/Server 三角的职责边界、三大原语按「谁决定调用」的划分、两层服务端模型(MCPServer 装饰器层构建于低层 Server 之上)、SDK 的模块分层、一次完整调用的端到端生命周期。读完你能画出整张架构图并解释每个抽象的存在理由。

第 3 章 服务端入门:MCPServer 与三大原语
MCPServer 的构造、三个装饰器(@mcp.tool() / @mcp.resource(uri) / @mcp.prompt())如何替代手写 JSON Schema、能力声明如何自动产生、命名约定与错误处理。读完你能不写一行协议就暴露出三类能力。

第 4 章 工具:类型即契约(硬核)
函数元数据如何从类型注解推断出输入 Schema、结构化输出(返回类型注解即输出 Schema)、ToolAnnotations 元信息、错误与异常如何回传模型、富 Schema 用 pydantic.Field。读完你能讲清一个工具的契约是怎么生成与校验的。

第 5 章 资源、模板与提示词
资源(应用控制,类比 GET)与资源模板(URI 带参数)、提示词(用户控制,命名调用的消息模板)、补全(Completions)如何为模板参数提供自动建议。读完你能区分三类原语的边界并各得其所地使用。

第 6 章 上下文、依赖与请求生命周期
Context 对象如何按类型注解注入、一次请求里读取资源/上报进度/写日志、Resolve(fn) 依赖解析机制(对模型不可见的参数注入,类比 FastAPI 的 Depends)、生命周期(Lifespan)上下文。读完你能写出与请求环境和用户状态交互的工具。

第 7 章 交互式能力:引导、采样与多轮往返(全书最有意思)
引导填写(Elicitation)——工具执行中途向用户反问、两种模式(表单与 URL)、Resolve 返回 Elicit 的现代写法、采样(Sampling)与根(Roots)及其弃用趋势、多轮往返(MRTR)机制。读完你能让一个工具在执行中途安全地获取用户输入。

第 8 章 传输层:stdio、流式 HTTP 与 SSE
stdio(子进程,本地默认)、流式 HTTP(Streamable HTTP,生产级)、SSE(旧版,已弃用)、内存传输(测试/嵌入)、传输安全(DNS 重绑定防护)、选型取舍。读完你能为不同部署场景选对传输并理解各自的工作机制。

第 9 章 客户端入门:Client 与会话
第一类 Client 的构造(按参数类型自动选传输)、async with 生命周期、核心方法(call_tool / list_tools / read_resource / get_prompt)、协议版本协商(mode 参数)、与低层 ClientSession 的关系。读完你能用十几行代码连上一个 MCP 服务并消费它的能力。

第 10 章 客户端进阶:传输、会话组与缓存
客户端的三种传输接入方式、ClientSessionGroup 编排多个服务端、响应缓存(CacheHint / CacheMode)、订阅(Subscriptions)与资源更新通知、断线重连。读完你能用客户端做生产级的编排与性能优化。

第 11 章 认证与授权:OAuth 2.1 全链路
服务端授权服务器(Authorization Server)的组成、客户端 OAuth 提供者(OAuthClientProvider)、客户端凭证与身份断言扩展、传输安全与本地回调。读完你能为你的 MCP 服务加上完整的 OAuth 保护并在客户端侧接通。

第 12 章 进阶:低层 API、扩展、中间件与可观测性
装饰器糖之下的低层 Server(直接处理协议对象)、自定义方法与扩展(Extension)、中间件(Middleware)、Apps(从服务端提供 UI)、OpenTelemetry 可观测性。读完你能在不改协议的前提下扩展 SDK 的能力边界。

附录 A 术语表 · 速查 · 排错
全书术语词典(中英对照)、高频 API 速查、报错→原因→排查三列表,以及 v1(FastMCP)→v2(MCPServer)迁移要点。

适合读者

本教程适合想让大语言模型安全、标准化地调用自己代码的工程师:

• 在做 AI 应用,想让 Claude / Cursor / 自研 Agent 接入自己业务系统的后端工程师
• 想把内部工具、数据库、API 暴露给 LLM 使用的平台开发者
• 在构建 Host 或 Agent 运行时,需要消费多个 MCP 服务的架构师
• 对「协议设计如何为 LLM 交互量身定做」感兴趣的研究者
• 维护存量 v1 代码、想迁移到 v2 的开发者

前置知识:

• 熟悉 Python,理解类型注解(type hints)与异步(async / await)
• 了解 JSON、HTTP 请求、JSON-RPC 的基本概念
• 对「大语言模型(LLM)」「工具调用(Tool Use / Function Calling)」有基本认识
• 用过 Pydantic(非必需,但有帮助;教程会在用到时点拨)

教程说明

• 本教程对照的 SDK 是官方 Python SDK 的 v2 版本(MIT 协议)。若你使用的版本与本教程有差异,请以本地源码与官方文档站点为最终依据。
• 网上大量旧资料使用 FastMCP、旧版 ClientSession 等 v1 写法,本教程正文一律用 v2,迁移差异集中在附录,避免读者被旧资料误导。