按完整的 mcp__ 名把关 MCP 工具,并把注解当作提示
一个远程工具以 mcp__<server>__<tool> 到来,所以一个以名称为键的关卡必须使用完整名称,而暴露方式决定模型是否被告知它存在。
一个 MCP 服务器的工具以 mcp__<server>__<tool> 到来,所以一个以裸工具名为键的 tool_call 关卡会放行每一次远程调用。这个示例是一个以完整名称为键的拒绝清单关卡,是一对为一个会话添加服务器的注册调用,也是服务器就自身声明的注解与决定模型是否被告知该工具存在的暴露方式之间的区别。只有远端和模型是假的;命名、暴露方式和关卡都是 Pi 的。
运行它
使用 Pi 1.0.4 和示例仓库的测试运行器之一。拒绝清单 mcp-gate.ts 如下:
const MUTATING = new Set([
"mcp__jira__transition_issue",
"mcp__jira__delete_issue",
"mcp__github__create_pull_request",
]);
export default function (pi: ExtensionAPI) {
pi.on("tool_call", async (event, ctx) => {
if (!MUTATING.has(event.toolName)) return undefined;
if (!ctx.hasUI) {
return { block: true, reason: `${event.toolName} blocked — no UI to confirm` };
}
const ok = await ctx.ui.confirm(
"Allow MCP tool call?",
`${event.toolName} (from ${event.toolName.split("__")[1]})`,
);
return ok ? undefined : { block: true, reason: `${event.toolName} was not approved` };
});
}注册是每个会话的——registerMcpServer 添加,unregisterMcpServer 移除,而两者都活不过一次重载(register-server.ts):
// Registrations are not saved: register again on every load.
pi.registerMcpServer("jira", {
url: "https://mcp.example.com/jira",
exposure: "codemode",
});
pi.registerCommand("jira-off", {
description: "Remove the jira MCP server for this session",
handler: async () => {
pi.unregisterMcpServer("jira");
},
});
}预期结果
| 情形 | 结果(已观察) |
|---|---|
以 transition_issue 为键的关卡 |
从不匹配;调用到达服务器,工单被关闭 |
| 全名拒绝清单,无 UI | 调用被阻止,服务器从未听到它 |
| 全名拒绝清单,有 UI | 由人决定:批准放行,拒绝阻止 |
服务器在 delete_everything 上声明 readOnlyHint: true |
通过一个注解关卡;调用到达服务器 |
| 工具不声明任何提示 | 被当作危险处理;无 UI 时被阻止 |
暴露方式 direct |
工具被声明给模型 |
暴露方式 codemode(默认)或 hidden |
不声明;hidden 不可达 |
机制与局限
有文档记载: mcp.md 用一条清理规则把每个服务器工具命名为 mcp__<server>__<tool>,把扩展的 tool_call/tool_result 处理器(包括许可关卡)应用于 MCP 工具,并说明"这些提示未经核实,但一个许可扩展可以用它们来决定确认哪些调用"——缺失 readOnlyHint 意味着该工具不是只读的。注册不会被保存:每次加载都要重新注册。已观察: mcp.test.ts 用一个脚本化的模型,把 Pi 自己的 MCP 客户端对着一个内存假服务器运行:裸名关卡匹配失败,全名拒绝清单在服务器听到任何东西之前阻止,一个 UI 让人来做决定,一个撒谎的 readOnlyHint 通过了,而注册/注销让一个工具先变得可调用、再变得不可达。tool-allowlist.test.ts 补充了 1.0.4 规则:一个只点名内置工具的允许清单,让一个 codemode 暴露方式的工具仍可从脚本调用,而一个被保留但没有被点名的 direct 工具是惰性的——模式负责过滤,暴露方式负责决定。
这个示例不展示真实模型使用 MCP 工具。Pi 进程和服务器进程是一道协议边界,不是遏制:一个 stdio 服务器继承启动它的那个账户的权限;一个 HTTP 服务器可被任何有其 URL 的东西触达。
完整源码与测试 。
Understand this example
Copy this prompt into your AI tool. No code runs here.
Apply this example
Copy this prompt into your AI tool. No code runs here.