内置 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-dirpi mcp listpi mcp add 写入配置;pi mcp list 会实际连接所有已启用的服务器,包括启动 stdio 程序或访问远程服务,不是纯粹读取配置。连接失败或配置无效时,list 以非零状态退出。
远程服务示例:
pi mcp add docs --url https://example.com/mcp --bearer-token-env-var DOCS_TOKENpi 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> |
| 本次禁用内置 MCP | pi --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 官方文档为准。