跳转到内容

内置 MCP:连接、授权与工具暴露

MCP(Model Context Protocol)让 Pi 连接外部服务,把服务提供的工具与资源交给模型使用。例如,连接文档检索服务或团队内部工具。Pi 从 0.99.0 起内置 MCP 支持;不是 1.5 才开始支持。1.5 改进了 OAuth 注册、搜索和若干安全问题。

连接是有副作用的

本地 MCP 服务是会运行的程序,远程服务会收到请求;工具可能修改文件、访问网络或操作外部账户。安装和连接前审查服务来源、权限及凭据。Pi 的项目信任和工具暴露设置都不是操作系统沙箱。

先理解三个部分

Pi 会话 → MCP 客户端 → 你配置的 MCP 服务器 → 外部工具 / 资源
├─ stdio:启动本地子进程
└─ streamable HTTP:访问远程 URL
  • 服务器配置决定连接哪个程序或 URL。
  • OAuth 或环境变量决定服务器能用哪些凭据。
  • exposure 决定模型如何发现和调用工具,而不是限制服务器进程的系统权限。记成:exposure 管模型看见什么,不管进程能做什么。

Pi 支持 stdio 和 streamable HTTP,不支持旧版 SSE transport。已有服务只给出 /sse 时,先查服务商是否提供 streamable HTTP 地址,而不是假定可以直接替换。

第一步:添加可信服务器

下面是上游示例形式。npx -y 可能下载并执行 npm 包;先审查包,将 <reviewed-version> 替换为你信任的固定版本,并把路径改为允许访问的目录。

终端窗口
pi mcp add filesystem -- npx -y '@modelcontextprotocol/server-filesystem@<reviewed-version>' /path/to/allowed-dir
pi mcp list

pi mcp add 写入配置;pi mcp list 会实际连接所有已启用的服务器,包括启动 stdio 程序或访问远程服务,不是纯粹读取配置。连接失败或配置无效时,list 以非零状态退出。

远程服务示例:

终端窗口
pi mcp add docs --url https://example.com/mcp --bearer-token-env-var DOCS_TOKEN
pi mcp list

这里 example.com 是占位地址;DOCS_TOKEN 应由受控环境注入,不要把真实 token 写入命令、仓库或聊天。若服务使用 OAuth,可省略 bearer token 并按下文登录。

项目专用配置使用 -l:

终端窗口
pi mcp add -l tools --env API_KEY='${TOOLS_KEY}' -- uvx tools-mcp

单引号使配置保留 ${TOOLS_KEY},由 Pi 在运行时读取;tools-mcp 是示意名称,需替换为已审查的实际程序。项目配置只有在项目受信任后才加载。

配置存在哪里

位置作用域
~/.pi/agent/mcp.json当前用户,所有项目可用
.pi/mcp.json当前项目,需要项目信任
Extension 的 pi.registerMcpServer()当前会话;命令行 pi mcp 看不到它

同名项目条目通常覆盖用户条目。只包含 enabled、exposure、toolExposure 的项目条目则可以覆盖这些字段,保留用户配置中的连接方式和认证。

例如,仅在当前项目关闭一个用户级服务器:

{
"mcpServers": {
"internal-tools": { "enabled": false }
}
}

command 是单个可执行文件,参数放在 args;不要把完整 shell 命令放进 command。环境变量和 header 可引用 ${NAME}。配置也支持 !command,这会执行命令,应像扩展代码一样审查。

日常查看、移除与排错

在运行中的 Pi 输入:

/mcp

选择服务器后可以查看状态与工具、登录、重连、启停或调整暴露方式。会话外的常用命令:

操作命令
查看配置并实际测试连接pi mcp list,或 pi mcp list --json
移除用户配置pi mcp remove <server>
移除项目配置pi mcp remove -l <server>
OAuth 登录 / 登出pi mcp login <server> / pi mcp logout <server>
本次禁用内置 MCPpi --no-mcp

移除服务器配置不会自动删除已保存的 OAuth 凭据;需要清除时先登出。会话外添加或修改配置后,在 Pi 中运行 /reload。日志位于 ~/.pi/agent/mcp.log,分享前检查内部地址和业务信息。

如果 /mcp 的行为和这里不同,检查是否安装了注册同名 /mcp 的第三方扩展:它会替换会话中的内置 MCP。--no-mcp 不会禁用这样的替代扩展;会话外的 pi mcp 命令仍使用内置实现。用 pi config 检查 Built-in 与已加载资源。

OAuth 登录与 1.5 变化

远程服务器要求登录时,可以在 /mcp 中选择服务器并登录,或运行:

终端窗口
pi mcp login <server>

按提示在浏览器授权;远程终端需要时,把完整回调 URL粘回登录界面。不要在聊天、日志或 Issue 中分享回调 URL。Pi 将 MCP OAuth 凭据保存在 ~/.pi/agent/mcp-auth.json;服务器名称和 URL 一起决定凭据归属。

1.5.0 的默认 oauth.clientRegistration: "auto" 行为:

  • 授权服务器支持公共客户端的 Client ID Metadata Document(CIMD)时,使用 Pi 的文档标识。
  • 否则使用动态客户端注册(DCR);配置了 clientName 或非默认 callbackUrl 时也会注册。
  • 已经注册的客户端只要回调 URI 仍匹配,会继续使用;不会因为升级自动重新注册。
  • 需要排查兼容性时,可设为 "dcr" 强制动态注册,或设为 "cimd" 强制使用文档。后者需要服务器支持,且存在字段组合限制。

例如,在已审查的用户级 mcp.json 中:

{
"mcpServers": {
"example": {
"url": "https://example.com/mcp",
"oauth": { "clientRegistration": "dcr" }
}
}
}

URL 仍是占位符。强制切换不是通用修复,应以服务端支持和 Pi MCP OAuth 文档为准。1.5 也拒绝非 HTTP(S) 授权端点;不要通过手工配置绕过来源审查。

四种工具暴露方式

exposure模型如何接触工具适合
codemode(默认)用 Codemode 搜索、描述并通过脚本调用大型或需要组合、筛选结果的工具集
deferred由 tool_search 搜索后,向后续模型调用声明希望按需发现、之后直接调用的工具集
direct像普通工具一样直接声明,也可从 Codemode 调用少量高频工具
hidden注册但不可由这些机制调用暂时不向模型开放

codemode 与 deferred 都可以被 Codemode 或工具搜索间接发现;它们不是两套互相隔离的权限。direct 并不自动代表安全或只读。服务器可以用 toolExposure 为具体工具覆盖默认值,例如:

{
"mcpServers": {
"example": {
"url": "https://example.com/mcp",
"exposure": "deferred",
"toolExposure": {
"search": "direct",
"delete_*": "hidden"
}
}
}
}

确切名称优先于通配模式,多个模式按配置顺序匹配。以上只是示意,必须以真实服务器暴露的工具名为准;hidden 不是对服务器程序、凭据或网络的隔离。

重要:--tools 不会自动排除 MCP

在 1.5 中,像下面这样的命令不能单独证明只有只读工具:

终端窗口
pi --tools read,grep,find,ls

除非 --tools 的某个条目以 mcp__ 开头,MCP 工具不会因此被移除;它们仍可能通过 Codemode 或工具搜索到达。需要在本次运行禁用内置 MCP 时,使用:

终端窗口
pi --no-mcp --tools read,grep,find,ls

这仍不是安全沙箱。检查是否有替代 MCP 的第三方扩展,以及其他 Extension 是否执行代码或注册工具。更严格的无扩展基线可加 --no-extensions,但它也会禁用内置扩展。想按服务器过滤时,可使用 mcp__<server>__* 模式;具体组合见官方工具选项。

资源、自动连接和 SDK

  • 服务器提供资源时,Pi 可添加 list_mcp_resources、list_mcp_resource_templates 和 read_mcp_resource。Pi 不渲染 MCP Apps 的 ui:// 页面。
  • 已启用的服务器在会话启动时后台连接;有 direct 工具的服务器会影响首个请求的等待。按需工具在搜索或调用时等待相关连接。
  • MCP 工具调用经过 Pi 的工具事件管线;权限扩展可以增加护栏,但服务返回的只读等 annotations 不是可信安全证明。
  • CLI 默认加载内置 MCP、Codemode 和工具搜索扩展;SDK 会话不会自动加载这些内置扩展。需要在 DefaultResourceLoader 中加入工厂并绑定扩展,见自动化与程序集成。

下一步:了解 Codemode 怎样组合工具,或查看权限与安全边界。完整配置与 OAuth 细节以 Pi MCP 官方文档为准。