AI SDK 的 MCP 指纹漏检只读标记变化
Vercel AI SDK 的 MCP 工具指纹覆盖描述、输入结构和标题,忽略了 `readOnlyHint` 等注解。实测发现,32 台服务器上的 91 个工具将只读标记从真改为假,而这些服务器在对应观测中没有任何工具指纹变化。
AI 深度解读
Vercel AI SDK 能检查 MCP 工具定义有没有变,但它的指纹没有覆盖 readOnlyHint。一个工具从「声明只读」改成「声明可能写入或破坏数据」,detectToolDrift 仍可能返回三份空列表。应用如果把这个提示用于免审批,工具定义的可信基线就少记了一项会影响授权的字段。
作者用单工具服务器验证了这一行为,又用 HISTOR 的 14,009 台服务器记录估算它出现的频率。最值得带走的问题是,应用用哪些字段决定放行,就该用哪些字段判断是否需要重新审批。
为什么工具的只读声明变了,SDK 却没报
工具指纹从 Vercel AI SDK 7.0.19 开始提供。首次信任 MCP 服务器时,应用调用 fingerprintTools 生成基线并保存。以后连接时,detectToolDrift 比较两份指纹映射,列出新增、删除和变更的工具。ai 包在 2026 年 11 月 12 日至 18 日一周内有 4,830 万次下载。这个数字反映包的下载量,实际启用漂移检查的应用数量没有统计。
作者查阅的是 ai 7.0.177 和 @ai-sdk/mcp 2.0.101 的源码。在自动生成 schema 的路径上,SDK 按字段键排序,对 description、inputSchema 和 title 做 SHA-256,再编码成 base64url。工具名是映射的键。服务器没提供 title 时才会取 annotations.title。客户端还会给缺失的 properties 补 {},并把输入 schema 顶层的 additionalProperties 强制设为 false。所以服务器只把这个入口从 false 改成 true,哈希也会保持原样。

描述和输入 schema 是模型使用工具时会读到的内容,覆盖它们能发现一类会影响模型行为的改动。readOnlyHint 和 destructiveHint 的影响则取决于宿主应用怎么用。AI SDK 文档展示过按 readOnlyHint: true 免审批的策略,也提醒这些是来自服务器的非可信提示。只要应用拿它来决定是否询问用户,它就属于审批时需要记住的定义。
作者用 Node.js 22 或更新版本,固定 ai 7.0.177、@ai-sdk/mcp 2.0.101 和 zod 4.1.8,通过 SDK 自己的客户端读同一个 stdio 服务器三次。运行入口是 npm install 和 node check_ai_sdk.mjs。单改两个提示时,added、removed、changed 都为空。单改描述时,changed 列出 list_orders。对完整定义做指纹时,提示改动也会列出 list_orders。
真实记录里,有多少次连一条提醒都没有
HISTOR 的统计窗口是 2026 年 10 月 23 日至 11 月 16 日。readOnlyHint 从 true 变成 false 的有 189 台服务器上的 524 个工具。其中 348 个工具自己的指纹会变,85 个只会看到同一台服务器上的其他工具被报变更,剩下 91 个分布在 32 台服务器上,整次读取没有任何指纹变化。destructiveHint 从 false 变成 true 的有 314 台服务器上的 1,075 个工具,三组分别是 355、490 和 230 个。

一个例子很直观。某台远程服务器的四个工具同时把 readOnlyHint 和 idempotentHint 从 true 改为 false,其余字段没动。按旧声明,这些工具被标为只读,重复调用也应与调用一次效果相同。这看起来像维护者在纠正标注。此前按旧声明放行的应用,同样需要知道这次更正。
把范围扩大到所有字段,103,657 次定义发生变化的读取里,有 6,338 次预计不会改变任何 SDK 指纹,占 6.1%,涉及 14,009 台服务器中的 2,014 台,占 14.4%。其中 _meta 变化出现了 3,861 次,outputSchema 变化出现了 2,171 次,同一次读取可能涉及多个字段。单个宿主就贡献了 2,805 次。作者还排除了 174,484 次仅供应商工具版本字段变化的读取。

单工具实验跑过 SDK,批量统计则是按源码规则推算。HISTOR 从一个地址匿名读取官方注册表里的远程服务器,对 npm 和 PyPI 包按发布版本比较。它看不到登录后或按用户返回的列表,也会错过两次轮询之间出现又撤回的改动。遇到 annotations.title 变化、摘要截断或同次读取有工具增删等难以判断的情况,作者按已能察觉变化处理,因此估计偏保守。这些数据衡量的是指纹覆盖范围,攻击发生率和按提示免审批的应用比例都未测量。
用原始定义做指纹,还能复用 SDK 的漂移比较
detectToolDrift 比较的是两份映射。应用可以用 listTools() 取得原始定义,再以工具名为键生成自己的指纹。下面这段代码通过递归排序对象键,让仅有对象字段顺序不同的定义得到相同哈希。
// pin.mjs
import { createHash } from 'node:crypto';
function canonical(value) {
if (value === null || typeof value !== 'object') return JSON.stringify(value);
if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`;
const keys = Object.keys(value).filter(k => value[k] !== undefined).sort();
return `{${keys.map(k => `${JSON.stringify(k)}:${canonical(value[k])}`).join(',')}}`;
}
export function pinDefinitions(tools) {
return Object.fromEntries(tools.map(tool =>
[tool.name, createHash('sha256').update(canonical(tool)).digest('base64url')]));
}
留意 canonical(tool) 这一行。传进去的是整份工具定义,所以提示和输出 schema 都会进入哈希。首次审核后保存基线,后续连接时把当前指纹放在第一个参数,已审核的基线放在第二个参数。
const reviewed = pinDefinitions((await client.listTools()).tools); // store this
// on a later connect
const drift = detectToolDrift(pinDefinitions((await client.listTools()).tools), reviewed);
第二次 listTools() 取的是当前定义,reviewed 要从之前保存的基线读取。基线存储和发现变化后怎么处理,由应用决定。
对于通过 .mcp.json 等项目文件配置的服务器,作者还在 11 月 19 日实测了 WARDEN 0.31.0。审核后运行 npx -y @aimarket/warden@0.31.0 scan --project --lock warden.lock.json --update-lock 更新锁文件,CI 中运行 npx -y @aimarket/warden@0.31.0 scan --project --lock warden.lock.json。服务器定义没变时退出码为 0,只读提示翻转后以 1 退出,并报告 TOOL_DEF_DRIFT。
我的判断
文章最有说服力的地方,是把字段覆盖和应用策略放在一起看。只要 readOnlyHint 参与免审批,提示变化就应该触发对旧审批的复查。原文的单工具实验确认了 SDK 会漏掉这种变化。至于完整定义锁在普通团队里会增加多少审核量,作者给了字段变更次数,没有给实际告警处置或人工复审的对照数据。按需过滤 _meta 是经验建议,适不适合取决于应用是否读取其中的字段。
FastMCP 从 3.0.0 开始提供的指纹配方,默认只覆盖工具键和 inputSchema,用来给服务端作者在 CI 里检查自己的工具。作者推算,消费端直接照搬会错过 4,191 台服务器上的 10,742 次仅描述变化。宿主需要关注模型读到的描述,也需要关注自己用于审批的提示。完整定义锁覆盖最广,代价是版本字段或元数据更新也可能触发复审。作者同时维护 HISTOR、开发 WARDEN,文中的 WARDEN 结果来自他们自己的单工具实验。
能拿来做什么
- 在 Node 的 MCP 接入层检查免审批逻辑。若
readOnlyHint参与放行,把它纳入已审核的定义基线,并在提示变化时让该工具重新走审批。 - 如果前端按
outputSchema渲染工具结果,把这个字段也纳入漂移检查。发现变化时,让应用检查旧渲染逻辑还能否处理新结构。 - 如果团队在仓库里维护
.mcp.json,可以一并提交审核后的warden.lock.json。让 CI 运行检查命令,把--update-lock留给确认过定义变化的更新。