给 MCP 工具加上人工审批
文章用 MCP TypeScript SDK 演示如何把写文件、发消息等操作先放入待审批队列。服务端通过独立渠道向人工审批者交付一次性令牌,验证通过后才执行操作。
AI 深度解读
给 MCP agent 接上 write_file 或 send_message 后,「先问我再执行」要由服务端落实。confirm: true 是模型自己能填的字段,系统提示同样拦不住所有误调用。原文给出了一套 TypeScript 实现,把写操作拆成提案、人工批准和执行三步。
模型提交要改什么,人通过独立渠道批准这一次操作,执行器再动手。对正在给 AI 编程工具加写权限的人,这个设计最实用的地方是能用集成测试验证。走一次真实的 MCP 调用,就能检查批准前文件有没有被写入。
为什么 confirm: true 拦不住模型
假设你给 write_file 加了一个必填的 confirm 字段,工具只在它为 true 时写盘。这个条件确实会被代码检查,但字段的值仍由发起工具调用的模型决定。模型误判了用户意图,或者读到网页里诱导它调用工具的指令,都可能自己填上 true。服务端收到这个值时,依然没有证据表明真人看过这次变更。
作者把写操作先做成一张待审批票据(ticket)。完整票据记录工具名、原始参数、参数摘要 argsHash、预览、风险级别、创建时间、过期时间和状态。服务端用 randomBytes(16) 生成票据 ID,用 randomBytes(32) 生成审批令牌,两者都编码成十六进制。队列里的票据只存令牌的 SHA-256 摘要 tokenHash,明文另外写入权限为 0600 的本地凭据文件,供同一系统用户运行的 CLI 读取。过期时间由创建时间加 ttlMs 得出,文章没有给出默认值。
模型收到的是经 toPublicTicket 转换过的 PublicTicket,其中保留可读预览和 argsHash,剔除原始参数与 tokenHash。示例靠解构排除两个字段,作者建议生产环境显式列出允许返回的字段。以后给内部票据新增字段时,公开响应就不会跟着多出一项。
调用 write_file 时,服务端到底做了什么
这段代码用官方 MCP TypeScript SDK v2 的 @modelcontextprotocol/server 注册工具,用 zod/v4 校验 path 和 content,并把一次文件写入请求变成待审批票据。
import { McpServer } from "@modelcontextprotocol/server";
import * as z from "zod/v4";
server.registerTool(
"write_file",
{
title: "Write file (approval required)",
description:
"Propose writing a text file inside the workspace sandbox. " +
"The file is not written until a human approves the action.",
inputSchema: z.object({
path: z.string().describe("Path relative to the workspace sandbox"),
content: z.string().describe("Full file contents"),
}),
},
async (args) => {
const { ticket, token } = queue.propose({
tool: "write_file",
args,
preview: previewWriteFile(args),
risk: "write",
});
// For the human only. stderr is not part of the MCP response.
console.error(`[checkpoint] pending ${ticket.id} (write_file) token=${token}`);
return {
content: [{
type: "text",
text: JSON.stringify({
...ticket,
instructions:
"This action has not run. A human must approve it. " +
"The approval token is never included in tool results. Do not invent a token.",
}, null, 2),
}],
};
}
);
看 console.error 那一行。使用 stdio 传输时,stdout 承载 JSON-RPC,令牌走 stderr,工具响应只展开公开票据。响应里的 instructions 用来让模型知道该停下来等人,实际约束由审批代码落实。
同样的结构可以用在 send_message 和 http_request 上。作者的套件允许 GET 在目标主机通过允许列表检查后直接运行,把 POST、PUT、PATCH 和 DELETE 放进审批队列。换成 Streamable HTTP 时,服务端还要验证请求方。原文的 HTTP 实现使用单个共享 bearer token,团队成员的身份和审批权限需要另外处理。
人批准之后,哪段代码才有权执行
人在本地运行 checkpoint pending 查看公开票据,用 checkpoint show <id> 查看预览和本地令牌,再用 checkpoint approve <id> 校验令牌并触发执行。下面这段代码负责把一张仍然有效的 pending 票据推进到 approved。
import { timingSafeEqual } from "node:crypto";
approve(id: string, token: string): Ticket {
const ticket = this.require(id);
const a = Buffer.from(ticket.tokenHash, "hex");
const b = Buffer.from(sha256(token), "hex");
if (a.length === 0 || a.length !== b.length || !timingSafeEqual(a, b)) {
throw new ApprovalError("Invalid approval token.");
}
if (Date.now() >= Date.parse(ticket.expiresAt)) {
ticket.status = "expired";
throw new ApprovalError("This action has expired.");
}
if (ticket.status !== "pending") {
throw new ApprovalError(`Action ${id} is ${ticket.status}, not pending.`);
}
ticket.status = "approved";
this.save(ticket);
return ticket;
}
timingSafeEqual 那行比较的是两个等长的摘要。后面的 pending 状态检查负责拦截重复批准,即使旧令牌仍能通过摘要校验,也过不了这一关。
执行入口按工具名选择执行器,从已批准的票据读取原始参数。完成后,队列把票据记为 executed,返回脱敏结果,并删除本地令牌。executeWriteFile 仍要拒绝通过 .. 或符号链接逃出工作区的路径。异常响应和审计日志也要处理敏感信息,意外错误可以只返回 Tool failed.,日志用 argsHash 和脱敏预览追踪,避免再存一份可能带密钥的消息正文或请求头。
我的判断
这篇最值得借鉴的是把「谁能批准」落实到服务端,再用真实 MCP client 测它。相比提示词和布尔字段,这条路径能给出明确的验证结果。作者建议写一条集成测试,分别检查审批前、审批响应和审批后的状态。文章没有展示这条测试的运行记录,也没有给出与客户端原生确认弹窗的对照数据。作者披露这套模式来自自售的 Checkpoint Agent Kit,手写约 150 行,商品售价为 $29,采用 MIT 许可,基于 @modelcontextprotocol/server 2.4.0,并称套件有 21 项无需供应商 API key 的测试。这些是作者披露的实现信息。
本地方案成立的前提是模型无法读取 stderr 日志或凭据文件。0600 允许文件所属用户读写,如果另一个 agent 工具能以同一系统用户读这个文件,令牌就可能回到模型上下文。原文还提议加一个可选的 approve_action(id, token) 工具。如果实际客户端会把人为粘贴的令牌保留到对话或工具轨迹里,我会保留独立 CLI 审批。已有服务端强制确认能力的宿主,也可以复用其确认流程,前提是执行入口确实会校验绑定到本次参数的批准结果。
另一个问号是重复执行。示例展示了审批时必须处于 pending,也展示了执行前调用 takeApproved,但没有交代两个执行请求并发时能否原子地认领同一张票据,也没有说明外部请求已经成功、executed 状态却没写回时怎么恢复。写一份本地草稿和发送一条可能重复投递的消息,对重试的要求不同。套件里的 send_message 写入本地 outbox,接真实消息服务时还得验证对方的幂等能力。
能拿来做什么
- 给本地 Node MCP 服务加
write_file时,先让它只返回票据。审批预览展示工作区相对路径和可读的变更摘要,执行器按票据里的参数落盘,并再次检查路径是否留在工作区内。 - 用真实的 MCP client 跑一次完整流程。调用工具后断言文件不存在、工具响应没有明文令牌,批准后再检查实际文件内容。若服务有多个执行进程,再补一次并发执行测试。
- 给
http_request接入有副作用的接口时,先挑一个POST验证流程。让审批人看到目标主机、路径和请求摘要,对鉴权头脱敏,再用该接口支持的方式验证重试会不会重复提交。