FastMCP 实测:校验、超时与工具权限
通过真实 stdio 和 HTTP 测试 FastMCP 4.1.6,区分参数转换与严格校验、输出契约、错误隐藏、超时副作用和 JWT 工具权限。
AgentIndex · 发布于 2026-11-07 · 更新于 2026-11-07
FastMCP 把 Python 函数变成 MCP 能力。这次我们验证边界上的实际行为:非法参数是否进入业务函数,返回值由谁校验,超时是否停止已经开始的工作,以及带认证的 HTTP 调用能否按工具 scope 划分权限。
框架生成了可用的 schema,拦住所测非法输入,并通过真实连接传输了结构化结果、资源和提示。但三个区别很重要:默认转换不等于严格校验;声明输出 schema 不表示服务端结果一定符合它;超时报错也不会撤销同步线程留下的日志写入。
固定实现版本与独立客户端
测试日期为 2026 年 11 月 7 日,安装 fastmcp==4.1.6。外层包固定依赖同版 fastmcp-slim,实际实现位于后者。我们核验两个 PyPI wheel,并把选定的八个实现文件与发布提交 1302563111a0e72176174cdb5ac19838cb0687c3 比较。slim wheel 的 SHA-256 为 d25691ae70a7f2b9d8197d6261bdd0f4b9ff33064087cd35c20539b0b48bb1ca。固定发布版本
环境为 macOS 26.6.2、Apple M1 Pro、x86_64 Python 3.13.1、Pydantic 2.14.3、MCP Python SDK 2.3.0。仅使用预编译包的安装与 pip check 均通过,复现目录固定了 62 个依赖包。
人工应用包含报价、错误和超时工具,以及使用本站六条冻结公开记录的资源与提示。报价计算和日志由我们定义,FastMCP 负责注册、schema、校验与传输。参考 SDK 驱动两个 stdio 服务和一个回环 HTTP 服务,建立四个客户端会话,发送了含预期失败在内的 42 次工具请求;另有五次 HTTP 认证负向探测被拒绝。
源码指纹、测试应用与原始结果 保留了操作过程。没有模拟 MCP 响应,没有调用模型、生产服务或外部身份服务。四个进程的 Python 连接审计只记录到回环地址,更新检查和遥测均关闭。
| 验证项目 | 实际结果 |
|---|---|
| 参数 schema | 包含必填字段和数量范围,不包含注入的 Context |
| 缺失、空字符串或越界输入 | 在报价函数进入前被拒绝 |
| 整数字段收到数字字符串 | 默认配置转换,严格输入校验拒绝 |
| 故意错误的返回对象 | 原始服务端结果为 isError=false,SDK 输出校验拦住 |
| 错误详情隐藏 | 隐藏内部标记,保留显式 ToolError 信息 |
| 异步与线程超时 | 异步任务取消,同步完成标记仍然出现 |
| 资源与提示 | 所测请求保留冻结记录与中文内容 |
| HTTP JWT 与工具 scope | 无效认证被拒绝,只读令牌不能执行写工具 |
输入校验保护了函数入口
报价函数声明商品名不能为空,数量必须为 1 至 50 的整数。生成的 schema 包含这些约束,并排除了调用方不应提供的注入参数 Context。
我们通过底层协议调用发送数量零、51、缺少数量和空商品名,均返回工具错误。独立业务日志表明,这些请求没有进入报价函数。有效请求则返回了预期的结构化对象和中文备注。这里验证的是参数进入函数的所测边界;价格计算本身属于测试应用逻辑。
字符串 "3" 展示了配置差异。默认配置下,它以整数 3 进入函数;启用 strict_input_validation=True 后则被拒绝,函数没有新增进入记录。两种配置的 JSON Schema 都声明整数类型。需要严格限制 JSON 类型时,应明确选择并验证该配置,不能只根据 schema 推断。输入执行路径
负向用例的输出校验发生在客户端
我们故意把函数标注为返回 Pydantic Receipt,实际却返回普通字典,其中整数位置是字符串,总价为负。这是刻意构造的业务契约错误,用来观察谁负责拦截。
先通过参考会话的底层 send_request 查看服务端结果,它不会执行 call_tool 的输出检查。两种配置下,服务端都把错误结构原样返回,并标记 isError=false。独立对照输出 schema 后,确认内容不符合声明。
再通过 SDK 的 ClientSession.call_tool 调用同一工具,客户端抛出结构化内容不合法的 RuntimeError。严格输入选项并没有把返回值校验变成服务端保证。应保留客户端检查;若业务约定返回模型,也应在代码中真正构造经过校验的模型。有效报价函数返回构造后的 Receipt,负向函数则没有。返回结果转换
这个结果只覆盖所测“标注模型、实际返回错误字典”的路径,不能推广为所有输出类型和集成都没有服务端检查。
错误隐藏与超时改变的是不同契约
默认错误处理会在响应中显示人工 ValueError 的内部标记;启用 mask_error_details=True 后,该标记消失。显式抛出的 ToolError 在两种配置下都保留,供业务提供有意向调用方展示的信息。本次验证的是这两条响应路径,不是通用脱敏保证。配置定义
两个超时工具都设置 0.15 秒执行期限。异步工具等待一秒,留下取消记录,没有完成记录。同步工具使用默认工作线程,休眠 0.4 秒并写入完成标记;客户端收到超时报错后检查日志,仍能看到该标记。
因此,超时不能作为业务什么都没做的证据。这个受控用例支持在写入类工具中核对业务状态,并围绕幂等性设计重试;它不是超时精度、数据库事务或全部取消路径的性能基准。
资源、提示与 HTTP 权限也实际运行
两种 stdio 配置下,静态资源和参数化资源均返回了预期的冻结公开记录;提示接口在我们的模板中包含了所选记录的中文描述。没有让模型基于提示生成回答,所测的是协议上的数据交付,不是检索质量或推理能力。
HTTP 部分生成临时 RSA 密钥,使用发布包的 JWTVerifier 配置静态公钥、issuer、audience 和必需的 catalog:read scope。缺少认证、错误签名、过期令牌、错误 audience,以及缺少全局 scope 的令牌,五种情况均返回 HTTP 401。
有效只读令牌可以调用普通工具,但工具列表不包含使用 require_scopes('ledger:write') 保护的动作;直接指定该名字也返回错误,没有写入标记。拥有两个 scope 的令牌则能看到并执行它,留下恰好一次受保护操作记录。工具级 scope 检查在这个开源包中可用,所选路径通过了实测。JWT 验证器、scope 检查
这只是本地签名令牌验证,没有测试 OAuth 登录、SSO、密钥轮换或生产环境安全性。
如何判断是否适合
需要把 Python 函数、资源和提示开放给 MCP,同时愿意明确业务契约时,值得用自己的应用评估。该发布版声明 Python 3.10+。锁定外层与实际实现包的版本,明确选择参数转换、错误隐藏行为,并保留独立客户端检查。
FastMCP 自带 Client API、Apps、任务扩展、远程身份服务、其他操作系统、迁移、持续并发、速度优势和模型自主调用均未测试。另一个 MCP 结果契约案例可看 Headroom 压缩与取回实测;浏览器工具的状态与失败恢复可看 Playwright MCP 工作流实测。
文档入库工具还有另一层验收边界:Xberg PDF 与 OCR 实测 展示了成功提取中的数字错误,以及需要显式处理的批次部分失败。