MCP Python SDK · 第 12 章进阶:低层 API、扩展、中间件与可观测性

文档摘要

MCP Python SDK · 第 12 章进阶:低层 API、扩展、中间件与可观测性章节摘要:最后一章,我们回到第 2 章埋下的那个伏笔——两层服务端模型。前面十一章你用的都是 (装饰器层),它把协议细节藏得很好;但当你需要协议层做不到的事——一个自定义方法、一条拦截所有请求的逻辑、一套 OpenTelemetry 追踪——你就得知道装饰器糖之下是什么。本章就是带你看穿这层糖。

MCP Python SDK · 第 12 章进阶:低层 API、扩展、中间件与可观测性

章节摘要:最后一章,我们回到第 2 章埋下的那个伏笔——两层服务端模型。前面十一章你用的都是 MCPServer(装饰器层),它把协议细节藏得很好;但当你需要协议层做不到的事——一个自定义方法、一条拦截所有请求的逻辑、一套 OpenTelemetry 追踪——你就得知道装饰器糖之下是什么。本章就是带你看穿这层糖。我们会先讲透低层 Server:它直接处理协议对象(注册 on_list_tools / on_call_tool 等处理器),没有类型推断、没有装饰器,是 MCPServer 的地基;然后讲扩展(Extension)——如何在不改协议的前提下定义 MCP 未覆盖的方法;中间件(Middleware)——如何拦截整条请求/通知流水线;Apps——如何从服务端提供 UI;最后是 OpenTelemetry 可观测性。读完本章,你将明白 SDK 的能力边界在哪,以及如何在不改协议地扩展它。

学习目标

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

用低层 Server 直接注册协议处理器(on_list_tools / on_call_tool 等),说清它与 MCPServer 在抽象层级上的差异。
用一张「同一功能两种写法」的对照表,把 MCPServer 的装饰器写法翻译成低层 Server 的处理器写法,理解装饰器糖到底替你做了什么。
用扩展(Extension) 定义 MCP 协议未覆盖的自定义方法,并通过 MethodBinding 把它们安全地暴露给客户端。
写一个中间件(Middleware) 拦截整条请求/通知流水线,实现日志、鉴权、限流等横切关注点。
用 OpenTelemetry 为你的服务端加上分布式追踪,理解 SDK 的可观测性钩子如何与标准生态集成。

核心概念速览

整章逻辑可浓缩为一句话:当你把 SDK 用到极致,会发现装饰器糖之下的低层 Server、扩展、中间件、可观测性这四样东西,给了你「不改协议地扩展一切」的能力——这是 SDK 真正的扩展性所在,也是从「会用」到「能改」的分水岭。

子章节导航

01 低层 Server:直接处理协议对象

回到第 2 章的两层模型。讲透低层 Server:它没有装饰器、没有类型推断,你直接注册 on_list_tools、on_call_tool、on_read_resource 等处理器,处理器收协议对象(ServerRequestContext + 参数)、返回协议结果。它是 MCPServer 的地基,也是你需要协议级控制时的逃生口。

02 同一功能两种写法:高层与低层对照

用一张并排对照表,把几个典型功能(定义一个工具、读取资源、声明能力)分别在 MCPServer 与低层 Server 上实现,让你直观看到装饰器糖替你省了什么(类型推断、Schema 生成、错误转换),以及代价是什么(失去细粒度控制)。这一节是理解两层模型的关键。

03 扩展:定义 MCP 未覆盖的方法

MCP 协议定义了标准的工具/资源/提示词等方法,但有时候你需要协议外的东西——一个自定义的状态查询、一个非标准的批量操作。扩展(Extension)让你定义这些方法,通过 MethodBinding 绑定到服务端,让客户端能像调标准方法一样调用它们。讲清它的能力声明与版本兼容考量。

04 中间件:拦截整条流水线

横切关注点——日志、鉴权、限流、指标——不该散落在每个处理器里。中间件(Middleware)让你在请求/通知流水线上叠加拦截层,可任意组合。讲清中间件的链式执行模型、与第 11 章 Bearer 中间件的关系、以及如何写一个自定义中间件。

05 Apps 与 OpenTelemetry:从服务端提供 UI 与可观测性

收尾性的两块。Apps 让你从一个 MCP 服务端同时提供 UI(HTML 页面),适用于需要给用户一个管理界面的场景。OpenTelemetry 让你的服务端产生分布式追踪数据(Span),与标准可观测性生态集成。讲清它们的接入方式与典型用法。

子章节之间的逻辑关系

本章遵循「下沉地基 → 对照理解 → 协议外扩展 → 横切拦截 → 观测与 UI」的递进,从「看穿装饰器糖」一路走到「扩展 SDK 边界」:


低层 Server (01) ── 装饰器糖之下的协议对象层
   │
   ▼
两种写法 (02)   ── 对照表,看清糖替你做了什么
   │
   ▼
扩展 (03)       ── 协议外的自定义方法
   │
   ▼
中间件 (04)     ── 横切关注点的拦截层
   │
   ▼
Apps + OTel (05) ── UI 与分布式追踪
   │
   ▼
附录 A:全书术语 · 速查 · 排错(含 v1→v2 迁移)

低层 Server 是理解一切的钥匙,两种写法的对照让你真正「看穿」装饰器糖,扩展与中间件让你改与扩展,Apps 与 OpenTelemetry 让你把服务做成产品。本章是全书的收尾升华——把前面十一章「会用」的内容,提升到「能改、能扩展、能观测」的层次。

前置知识与后续延伸

前置知识:

第 2 章的两层服务端模型(本章是其兑现)
第 3~7 章的高层 MCPServer 写法(用于与低层对照)
第 11 章的 Bearer 中间件(作为中间件的实例)
对 JSON-RPC 请求/响应结构有概念

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

低层 Server 与高层的对照是附录 v1→v2 迁移的参考(v1 更接近低层风格)
扩展与中间件思想适用于所有需要「不改协议地扩展」的二次开发场景
OpenTelemetry 接入是生产部署的标配,会被附录速查收录
Apps 机制为「把 MCP 服务做成完整产品」提供了方向

MCP Python SDK · 第 12 章 进阶:低层 API、扩展、中间件与可观测性

文档摘要