MCP 服务器
通过 stdio 和 HTTP 连接 Model Context Protocol 服务器,控制它们的工具如何到达模型,以及一个许可扩展能从它们那里了解到什么、了解不到什么。
那个 guard 扩展会拦截 write 和 edit。它工作得很好。然后团队里有人装上了一个 Jira MCP 服务器,模型通过 mcp__jira__transition_issue 关掉了一个工单,而守卫从头到尾没有被征询过。
它没有被征询,是因为守卫从未宣称那条路径归它管——更重要的是,因为那条路径是否真被它覆盖,结果是一个有文档记载答案的真问题。本章讲的是注册 MCP 服务器、控制它们的工具如何到达模型,以及一个许可扩展能从它们那里了解到什么、了解不到什么。
两种传输方式,一个配置文件
mcp.md 说得很直白:Pi 连接 Model Context Protocol 服务器,“通过 stdio 或流式 HTTP,并把它们的工具和资源提供给模型”。
Stdio 服务器使用 command、args、env 和 cwd。HTTP 服务器使用 url、headers 和 oauth。旧的 SSE 传输不受支持——mcp.md 说 sse 会被拒绝,还说文档里写着 SSE 端点的服务器通常也提供流式 HTTP,常见位置是 /mcp 而不是 /sse。如果你从另一个客户端移植一份配置,这一个事实能省下你一个小时。
这个文件是 mcp.json,里面有一个 mcpServers 对象:
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
},
"docs": {
"url": "https://example.com/mcp",
"headers": { "Authorization": "Bearer ${DOCS_TOKEN}" },
"description": "Search and read the product documentation"
}
}
}
有文档记载,其中有两个细节值得读两遍。相对的 cwd 值相对会话目录解析,而 command、某个参数或 cwd 里开头的 ~/ 指向主目录。而 headers 的值可以使用诸如 ${GITHUB_TOKEN} 这样的环境变量,或者用 !command 运行一条命令——其中"命令必须构成整个值",所以 "Authorization": "!echo Bearer $(gh auth token)" 可行,而嵌在更长字符串里的命令不行。
这个文件放在哪里,以及为什么那是一个安全决策
用户级服务器住在 ~/.pi/agent/mcp.json。项目级服务器住在 .pi/mcp.json。mcp.md 说项目配置"只有在项目信任被授予之后才会被读取",还说一个同名的项目条目会替换用户级条目。
从 1.0.1 起,这一点有了一个部分例外,而它是更有用的那一半。一个没有 command、没有 url、也没有 type 的项目条目是一个覆盖,而不是替换:它只改用户级服务器上的 enabled、exposure 和 toolExposure,其他一切照留,包括 env、headers 和 auth。
{
"mcpServers": {
"internal-tools": { "enabled": false }
}
}
这一行为一个仓库关掉一个个人服务器,不必重新声明它的命令,也不必让项目文件变成凭据的栖身之处。达到同一状态的交互路径是"Enable in this project"和"Disable in this project";一旦覆盖存在,后续的更改会保存到覆盖里,而不是用户级文件里。
所以现在,对于一个给定的项目,一个服务器可以处于三种状态,而它们不是同一回事:在用户级声明、按项目覆盖,或者被一个确实带着 command 的项目条目整个替换。覆盖是那个窄的,也是默认值得伸手去用的那个。
OAuth 面也在 1.0.1 中多了一个选项:"oauth": { "clientRegistration": "cimd" } 让 Pi 通过它在 pi.dev 上的 Client ID Metadata Document 标识自己,而不是执行动态注册,适用于那些按文档 URL 允许客户端的授权服务器。有文档记载的约束很具体——它不能与 clientId 或 clientName 组合使用,一个 callbackUrl 必须使用 localhost 或 127.0.0.1 并带路径 /callback,而一个既没有宣告 Client ID Metadata Document 支持、也没有公开客户端的服务器会在登录时失败。值得知道,主要是因为它是一次隐私削减,而 Pi 把它做得显式且需主动选择。
mcp.md 还给出了那条应当支配你把东西放在哪里的规则:“把个人服务器和带凭据的服务器放在用户级文件里。项目文件只用于项目需要的服务器,而且只用于受信任的项目。” 那是一条有文档记载的指令,不是风格偏好。一个项目里的 mcp.json 是可执行配置,从一个你可能控制不了的文件夹到来。
这些 shell 命令覆盖常见的编辑,并且不需要会话就能工作:
pi mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem .
pi mcp add docs --url https://example.com/mcp --bearer-token-env-var DOCS_TOKEN
pi mcp list
pi mcp list 同时也是诊断手段。mcp.md 说它会连接每一个已启用的服务器,打印它的状态、工具和错误,并且"在某个条目无效或某个已启用的服务器未连接时以状态码 1 退出"。那个退出码正是你在 CI 检查里想要的东西。
命名已经替你定好了
每个服务器工具都以 mcp__<server>__<tool> 的形式到来。mcp.md 给出了清理规则:除字母、数字和 _ 之外的每个字符都变成 _,而冲突的名字都会加上一个哈希后缀。
有一条冲突规则会让人吃惊:“只在 - 和 _ 上有区别的服务器名算作同一个服务器:第二个会被拒绝。” 所以 dev-radius 和 dev_radius 是一个服务器,不是两个。
暴露方式决定模型是否看得见这个工具
这是会改变你对 MCP 的看法的部分。注册一个服务器并不会把它的工具交给模型。由 exposure 决定。
| 暴露方式 | 行为 |
|---|---|
codemode(默认) |
可从 codemode 脚本调用,但不向模型声明,也不列在 codemode 的描述里。脚本用 searchTools()、describeTool() 或 ALL_TOOLS 找到它们。 |
deferred |
直到 tool_search 为下一次模型调用加载到匹配项之前,都不声明。 |
direct |
像内置工具一样向模型声明,同时也可从 codemode 调用。 |
hidden |
已注册,但不可达。 |
codemode-deferred 被接受为 codemode 的别名。
默认值是那个有意思的。一个通用 MCP 服务器的工具,默认不在模型的工具列表里。它们是可达的,但只能通过模型写的一个脚本。对于一个大型服务器,这是正确的默认;对于一个你确实希望被直接调用的、只有两个工具的服务器,你设 direct。
toolExposure 按工具覆盖服务器默认值,精确名优先于模式,而在模式之中第一个匹配的优先:
{
"mcpServers": {
"github": {
"url": "https://api.githubcopilot.com/mcp/",
"exposure": "deferred",
"toolExposure": {
"search_code": "direct",
"get_*": "codemode",
"delete_*": "hidden"
}
}
}
}
hidden 那一行是承重的。它是你让一个破坏性工具根本无法被任何东西触达的方式,用的还是连接同一个服务器的那个文件。mcp.md 指出"一个 hidden 暴露方式的服务器仍然可以只暴露选中的工具",这意味着服务器级的 hidden 加上 toolExposure 是一个可行的允许清单。
工具的允许清单不是 MCP 工具的允许清单
这是唯一一个必须改掉 CLI 习惯的地方,而它是 1.0.4 才有的。--tools 不会移除 MCP 工具,除非它的某个条目以 mcp__ 开头。在那个版本之前它会移除,而 --tools codemode 给你留下 codemode,却没有服务器可调用。
所以,对着一个已配置的服务器跑 pi --tools read,grep,find,ls,并不会得到一个被限制在四个内置工具上的智能体。MCP 工具仍然注册着,而什么仍然可达取决于 exposure:
| 暴露方式 | 没有条目命名或匹配该工具 | 某个 mcp__… 条目命名了它 |
|---|---|---|
codemode |
可从脚本调用,未声明 | 同上 |
deferred |
可从脚本调用;tool_search 可以加载它 |
同上 |
direct |
已注册但惰性:未声明,不可调用 | 已声明,如同一个内置工具 |
hidden |
不可达 | 不可达 |
direct 那一行是文档没有明说的那个。一个 direct 工具在允许清单下活了下来,却拿不到声明,于是它既不能被模型触达,也不能被脚本触达。允许清单不会覆盖暴露方式;它只决定哪些工具被保留,而一个它没有点名的 direct 工具被保留到了一个角落里。这是在 1.0.4 上已观察到的。
当你的意思是某一个服务器时,伸手用模式:
pi --tools read,bash,codemode,'mcp__radius__*'
--exclude-tools 是另一个方向,而且不需要 mcp__ 前缀:它接受模式,并且同样作用于 MCP 工具,所以 --exclude-tools 'mcp__*' 是钝的那一版,而 --no-mcp 是更钝的那一版——没有服务器连接,那次运行没有 MCP 工具,也没有 /mcp。第 42 章需要以上全部,因为"一个不存在的能力无法被调用"这句话,在一个会话里有了 MCP 服务器之后,比它听起来要弱。
从扩展中注册
pi.registerMcpServer(name, config) 为当前会话添加一个服务器。config 具有"mcp.json 中某个 mcpServers 条目的形状",外加 exposure、toolExposure、description、enabled 和 timeout。
pi.registerMcpServer("jira", {
url: "https://mcp.example.com/jira",
exposure: "codemode",
});
pi.unregisterMcpServer("jira");
有四个有文档记载的行为要在设计时绕着走。扩展加载期间注册的服务器,会在会话开始时与 mcp.json 里的服务器一起连接;之后注册的服务器立刻连接。注册不会被保存——每次加载你都必须重新注册。mcp.json 里一个同名的服务器优先,而 /mcp 会显示覆盖。而由另一个扩展注册过的名字、无效的名字和无效的配置都会抛错。
最后那一点有一个设计后果:在工厂里注册是安全的,而在一个命令处理器里注册,一个拼写错误就能让用户的会话崩掉。调用之前先验证你自己的输入。
如果另一个扩展替换了内置的 MCP 支持,extensions.md 说每次注册都会被"报告为一个扩展错误"——你不会悄无声息地得到一个没有服务器的局面。那条规则在 1.0.4 中的补充值得知道,因为它是作用范围为一次运行的那一个:--no-mcp 为一次调用禁用内置支持,并且刻意"不影响一个替换了内置 MCP 支持的扩展"。
守卫能看到什么
这就是本章开篇提出的那个问题。mcp.md 的"Permissions"一节:
每一次 MCP 调用都会经过 Pi 的工具流水线。因此,扩展的
tool_call和tool_result处理器,包括许可关卡,也作用于 MCP 工具。从 codemode 脚本发起的调用,会把 codemode 调用 ID 作为parentToolCallId带上。
有文档记载,而它的形状是:
flowchart LR
subgraph P["Pi 进程"]
M["模型请求一个工具"] --> T["Pi 工具流水线"]
T --> G["守卫:tool_call 决定"]
end
subgraph S["MCP 服务器:另一个进程"]
J["mcp__jira__transition_issue"]
end
G -->|"放行"| J
J --> C["工单在 Jira 中被关闭"]
仔细读这两个方框,因为它们之间的空隙就是本章的全部要点,也是最容易被过度解读的地方。它们是两个进程。那是一道协议边界,是一个挂超时、日志和重试的地方——它不是遏制。security.md 对其余部分说得很直白:“扩展、包安装器、语言服务器和其他子进程都以同样的权限运行,除非有一道操作系统或虚拟化边界限制它们。” 一个从 mcp.json 启动的 stdio 服务器,继承启动 Pi 的那个账户的权限,而一个 HTTP 服务器可以被任何能访问那个 URL 的东西触达。隔离是在第 42 章里被妥善解决的。
一个以工具名为键的 tool_call 关卡,也必须把 mcp__ 前缀纳入键中,否则它会悄无声息地漏掉每一个 MCP 工具:
const MUTATING = new Set([
"mcp__jira__transition_issue",
"mcp__jira__delete_issue",
"mcp__github__create_pull_request",
]);
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` };
});
那就是拒绝清单的形状。允许清单的形状改用注解,而注解是你在 MCP 上必须理解的第二件事。
注解是提示,不是许可
MCP 工具带有 readOnlyHint、destructiveHint、idempotentHint 和 openWorldHint。pi.getAllTools() 会报告它们。extensions.md 对它们的地位很精确:“这些提示未经核实,但一个许可扩展可以用它们来决定确认哪些调用。”
那句话读两遍。未经核实。服务器是在就自身做出声明。一个恶意或粗心的服务器,可以在一个会删东西的工具上声明 readOnlyHint: true。
Pi 有文档记载了提示缺失时的默认值:“一个工具不是只读的,可能是破坏性的,并能触达一个开放世界。” 所以提示的缺席被当作危险情形处理,这是正确的默认,也正是下面这个模式之所以站得住的原因:
pi.on("tool_call", async (event, ctx) => {
const hints = pi.getAllTools().find((tool) => tool.name === event.toolName)?.annotations;
const needsApproval =
hints?.destructiveHint === true ||
(!hints?.readOnlyHint && ((hints?.destructiveHint ?? true) || (hints?.openWorldHint ?? true)));
if (needsApproval && !(await ctx.ui.confirm("Allow tool call?", event.toolName))) {
return { block: true, reason: `${event.toolName} was not approved` };
}
});
那是 extensions.md 里 Pi 自己的例子。它会确认任何未声明为只读的调用,除非工具自己说明它既不是破坏性的、也不触达开放世界。注意它同样覆盖 MCP 工具,因为 mcp.md 确认 MCP 工具带有其服务器声明的提示,还确认资源类工具被标为只读。
资源,以及工具何时出现
如果一个已连接的服务器提供资源,Pi 会添加 list_mcp_resources、list_mcp_resource_templates 和 read_mcp_resource。MCP Apps 的资源,由 ui:// URI 或 text/html;profile=mcp-app 识别,会被省略,因为 Pi 不渲染它们。
时机对守卫检查的任何东西都重要。mcp.md 说第一个提示词"最多等待 10 秒,只等待那些拥有 direct 工具的服务器,因为它们必须被声明进它的请求里。" 拥有 codemode 或 deferred 工具的服务器,在需要时才会被等待。所以一个想要枚举所有工具的守卫,绝不能假定它们在 before_agent_start 时全都已经在场。
自己验证
pi mcp list
pi mcp add -l issues --url https://mcp.example.com/issues --description "Read and update issues"
pi mcp list --json
在会话里运行 /mcp。它"列出已配置的服务器及其状态、工具数量、暴露方式和配置来源",而需要注意的服务器排在最前面。选中服务器即可检查它的工具,并看到实际生效的暴露方式。
然后确认守卫真的看得见 MCP 调用:让模型去关一个工单,看你的确认对话框是否出现。如果没有,你的处理器只按工具名过滤,而这个工具的名字是 mcp__issues__close。
运行了什么
examples/ch21-mcp/ 把一个真实的 Pi MCP 客户端连到一个小的内存服务器上,所以工具命名、暴露方式和关卡都是 Pi 自己的,只有远端那一头是假的。
- 工具以
mcp__jira__transition_issue到来; - 一个以裸名为键的关卡从未匹配,而工单被关掉了:调用成功了,服务器收到了它;
- 全名拒绝清单在没有 UI 的情况下阻止,服务器什么也收不到;
- 有 UI 时由人决定:批准放行调用,拒绝阻止它;
- 注解是提示,不是许可:一个在一个名为
delete_everything的工具上声明readOnlyHint: true的服务器,通过了那个批准扩展,调用到达了服务器,而一个什么都没声明的工具被阻止了; direct暴露方式向模型声明该工具,而codemode(默认的那个)和hidden不会;- 一个只点名内置工具的
tools允许清单不会移除 MCP 工具:在read, codemode下,一个codemode和一个deferred暴露方式的工具都仍可从脚本调用,服务器听到了调用,而两者都没有向模型声明; - 一个被保留但没有被点名的
direct暴露方式工具是惰性的:已注册、未声明,而一个调用它的脚本失败了,报的是Available: read,所以允许清单救不了它; - 一个
mcp__jira__*条目声明了那个direct工具,却仍然让一个codemode暴露方式的工具未被声明,也没有让一个hidden的变得可达——模式负责过滤,暴露方式负责决定; --exclude-tools 'mcp__*'把这个工具从已注册集合里也拿掉了,而disabledBuiltinExtensions没有动一个被注入的 MCP 扩展;pi.registerMcpServer()让一个服务器的工具变得可调用,而在pi.unregisterMcpServer()之后,服务器不再收到任何调用。
本章没有解决什么
它不解决信任问题。一个项目里的 mcp.json 是可执行配置,一个扩展运行在 Pi 进程内部,而两者都不是安全边界。那是最后一章要好好展开的论证,它需要的是 security.md 和 containerization.md,而不是一个 MCP 章节。
下一篇:包——守卫、命令、UI 和 MCP 注册是四个总是一起交付的资源,而包是让它们不再各自漂移的办法。