FastMCP 同发 4.0.11 与 3.4.8：一批传输层与鉴权修复，官方建议尽快升级

MCP 服务框架 FastMCP 于 2026 年 10 月 4 日同时发布 v4.0.11 与 v3.4.8 两个版本，官方说明写明「包含重要的安全与错误修复，建议所有用户升级」。修复集中在 SSE 传输的 Host/Origin 校验、Windows 命令行包装器的参数传递、Schema 嵌套与缓存边界、组件管理器路由的鉴权这几处。

这次发布的是什么

FastMCP —— 一个用 Python 写 MCP（Model Context Protocol）服务器与客户端的开发框架 —— 于 2026 年 10 月 4 日在官方 GitHub 仓库同时发布了两个版本：v4.0.11（代号「Fort Knocks」）与 v3.4.8（代号「Long Arm of the Patch」）。官方 release 说明的第一句写得很直接：本次发布包含重要的安全与错误修复，建议所有用户升级。

两条分支同一天发版，是因为 3.x 与 4.x 处于并存维护状态，同一批权限与传输层修复被一起移植到了旧分支，让还没跨大版本的团队也能拿到这批修补。仓库现位于 GitHub 的 PrefectHQ 组织之下，旧路径 jlowin/fastmcp 会跳转到新地址，拉地址时不必怀疑自己打开错了项目。

影响谁：把 MCP 服务器对外暴露的团队——尤其是用 SSE 或 HTTP 传输远程接入、把服务器挂到别人机器上安装、或是用 OpenAPI 组件把既有 HTTP 接口包装成工具的场景；在 Windows 上通过命令行包装器拉起服务器的团队也在这批修复的覆盖范围内。

可用性与限制

• 升级必要性：官方写明「建议所有用户升级」；是否真的受影响取决于你用的传输方式、是否开放远程接入、以及是否用到组件管理器与 OpenAPI 组件。
• 两条分支：4.x 请升到 4.0.11，仍在 3.x 的项目升到 3.4.8 即可拿到同一批修复，不必强行跨大版本。
• 获取渠道：Python 包从 PyPI 安装（包名 fastmcp）；是否提供容器镜像、镜像标签怎么打，以官方说明为准。
• Python 版本区间：本次过程中曾有一个「支持 Python 3.15」的改动被合入后又被回滚，所以当前到底支持哪些版本，请以项目元数据与 CI 配置为准，不要照着中间过程的提交标题去配环境。
• 行为变更：4.x 里有一条「OpenAPI 组件只发送已声明的参数」，属于有意的收敛——升级后如果发现少传了参数，多半是它生效了，而不是升级坏了。
• 网络环境：pip 源、GitHub 与容器镜像 registry 在国内的连通速度因人而异，以各自网络环境为准。

主要功能

• 让 SSE 传输套用 Host 与 Origin 保护设置
• 按字面传递 Windows .cmd 包装器的客户端参数
• 限制客户端类型转换前的 Schema 嵌套深度
• 让组件管理器路由改用服务端鉴权提供器
• 给 dev apps 预览加启动 URL 会话要求
• 让哈希工具查找也走启用状态与鉴权

技术原理

从官方列出的变更条目看，这批修复集中在四个方向，都属于「让外部输入进到本地处理之前先有边界」。

一是传输层的来源校验。SSE 传输此前没有完全套用 Host/Origin 的保护设置，而 SSE 正是服务器与客户端之间长连接的通道，请求来源一旦不做校验，跨站场景就可能把外部请求当作本地调用处理。4.x 的 #5427 与 3.x 的 #5428 是同一处修补，另外 3.x 还多了一条：转发 HTTP 头时排除 Cookie。

二是 "把远程 Schema 变成本地类型" 这一步的资源边界。MCP 客户端拿到工具的 JSON Schema 之后，需要把它转成可用的类型。当 Schema 里全是嵌套引用时，递归内联既会产生巨大的结构，也会把内存和 CPU 吃掉。4.0.11 的做法是用 create_model 构造客户端类型、给这类缓存加上限，并在类型转换之前就限制嵌套深度；同时在内联会导致结构过大时保留 $ref 指针，缓存键按归一化后的 Schema 计算。

三是子进程与调用参数的传递。Windows 上的 .cmd 包装器如果对环境里的字符串再做一次解析，参数就可能被当成命令的一部分。 #5419 / #5420 改成按字面传递参数，堵的是这一类解析差异带来的风险。

四是附属路由的鉴权口径统一。组件管理器路由改用服务端的鉴权提供器、dev apps 预览要求先有启动 URL 会话、哈希工具查找也要经过启用状态与鉴权——这些是把「走后门的入口」逐一关上。此外 4.x 还在库代码上启用了 ruff 的 flake8-bandit（S）规则，属于把安全检查放进 CI 的流程侧加固。

需要说明的是：以上归类与成因是依据官方变更条目的描述作出的整理，issue 与 PR 之外的细节以官方说明为准。

实际体验

这一段不写主观实测，给一套你自己就能复现的检查步骤。

第一步，确认当前装的是哪个版本：在部署环境的 Python 里打印 fastmcp 的版本，或直接用包管理器查询已安装版本。

第二步，对照两个 release 页面逐条核对你用到的能力：是否开了 SSE 传输、是否用了组件管理器、是否用了 OpenAPI 组件、是否在 Windows 上用命令行包装器启动。只要踩中其中任意一条，就应当安排升级。

第三步，在隔离环境（虚拟环境或容器）里先升级再回归。升级命令按官方安装说明执行，别在生产环境里直接覆盖。

第四步，重点回归三类场景：Windows 上通过命令行包装器拉起服务器是否正常；SSE 远程部署的请求头相关行为有没有变化；用 OpenAPI 组件包装的接口，请求参数是否被按预期收敛到「已声明」的集合里。

第五步，把回归结论和版本号一起记进变更单。这类安全型版本往往不带来可见的功能变化，事后很难靠现象反推「到底升没升」。

项目地址与获取方式

官方仓库位于 GitHub 的 PrefectHQ 组织下：github.com/PrefectHQ/fastmcp；本次两个版本的发布页分别是该仓库 releases 下的 tag v4.0.11 与 tag v3.4.8。Python 包从 PyPI 安装，包名 fastmcp；容器镜像与安装命令以官方文档为准。请通过官方渠道获取，避免安装被篡改的版本；如果是企业内网转发，建议同时核对发布页上的版本号与哈希。

适合谁用

• 已经在内网或公网跑 MCP 服务器、并且开放远程接入的团队：本次的传输层与鉴权条目和你直接相关，建议安排升级窗口。
• 在 Windows 上分发或启动 MCP 服务器命令行的开发者：参数传递那条是冲着这个场景来的。
• 用 OpenAPI 组件把既有 HTTP 接口包成工具的项目：行为变更会体现在请求参数上，需要一次回归。
• 仍停在 3.x 的团队：不用为了这批修复强行跨大版本，升到 3.4.8 即可。
• 暂时不急着动的：只在本地 stdio 模式自用、既不开放端口也不挂载远程组件的场景，这批修复的触发路径大多用不上——但版本本身还是建议跟上。

常见问题

应该升到 4.0.11 还是 3.4.8？

看你当前用的是哪条分支。4.x 的项目升到 4.0.11，3.x 的项目升到 3.4.8；官方把同一批修复分别移植到了两条分支，目的就是让还没跨大版本的人不必为了修复去做一次大版本迁移。如果跨版本的成本可以在这个窗口内消化，再考虑一次性迁到 4.x。

这次修的是哪几类安全问题？

按官方变更条目整理，主要四类：SSE 传输的来源校验缺失、把远程 Schema 转成本地类型时的嵌套与缓存边界、Windows 命令行包装器的参数传递方式、以及组件管理器等附属路由的鉴权口径。此外 3.x 还多了一条转发 HTTP 头时不带 Cookie。具体每一条的触发条件与影响范围，以仓库里的 PR 描述为准。

升级后发现 OpenAPI 组件少传了一些参数怎么办？

先别急着回滚。4.x 有一条目的是让 OpenAPI 组件只发送已声明的参数，并保留配置好的请求头——这是有意的行为收敛。把接口定义里缺失的参数显式声明出来即可；如果配置里有依赖「多传一个未声明参数」的下游逻辑，那才是需要改造的部分。

我在 Windows 上用命令行包装器拉起服务器，需要改什么？

代码层面通常不用改，修复本身在依赖里：参数改为按字面传递给 .cmd 包装器。但如果你的部署脚本依赖了「参数会被再解析一次」的旧行为，就需要按新语义复核一遍；升级后在 Windows 上跑一次完整的启动与调用回归即可确认。

怎么确认自己装的版本已经包含这些修复？

以版本号为准：Python 4.x 应当是 4.0.11 或更高，3.x 应当是 3.4.8 或更高。在部署环境里打印实际安装的版本号，而不是依赖编排文件里写的版本范围——范围写法（例如允许自动取次版本）常常让实际装上的并不是你以为的那个。

相关工具与内容

MCP 这一层管道的用处是把外部系统接进对话式工作流，本站相关的入口可以先从AI 智能体和AI 编程两个分类看起；具体到落地环境，Claude Code是目前接 MCP 服务器最常见的宿主之一，Dify则偏向把整套流程编排起来再对外提供服务。想补一点背景，可以看给智能体接上网搜索能力与Claude Code 的 mods 自定义机制这两篇。