pi-mcp-adapter：MCP 配置、惰性启动与 Token 开销

概览

Pi 可通过此扩展接入 MCP 服务。适配器使用 mcp 工具提供发现和调用能力，避免一开始就暴露所有服务的工具 schema。

大量低频工具适合代理发现；少量高频工具可用 directTools 直接注册，在发现调用次数与 schema 上下文开销之间选择。

“约 200 Token”描述什么

README 给出的约 200 Token 是紧凑代理工具定义的估计。本项目没有测量该数字，它不是整次会话或当前全部可选工具的上限。

按需搜索结果和工具描述仍会进入对话，参数、返回内容及选中的直接工具 schema 也占 Token。应在相同任务、启用工具和模型下比较实际用量；直接注册工具越多，初始节省越少。

实际配置格式

安装重启后，在项目 .mcp.json 中使用下面的 mcpServers 结构。这沿用上游 Chrome DevTools 示例并明确指定惰性生命周期，需要 Node/npx 及该 MCP 服务自身的浏览器依赖；固定版本只用于示例，不代表最新版本推荐。

共享全局配置位于 ~/.config/mcp/mcp.json。Pi 专属覆盖使用 ~/.pi/agent/mcp.json 和 .pi/mcp.json。默认不会悄悄采用其他宿主的配置，可通过 /mcp setup 查看并导入。

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@1.6.0"],
      "lifecycle": "lazy",
      "directTools": false
    }
  }
}

惰性启动与缓存行为

惰性是默认模式：Pi 启动不等于配置的所有服务都启动。工具元数据缓存在 ~/.pi/agent/mcp-cache.json，或自定义的 Pi agent 目录，之后的搜索、列表及描述可读取缓存。

新增服务还没有元数据，需要连接一次来发现工具；直接工具随后可从缓存注册，并随实际目录变化刷新。有缓存定义不代表健康检查成功；/mcp reconnect <server> 可刷新在线状态。

按需启用直接工具

服务级 directTools: true 暴露全部工具 schema；数组只暴露列出的原始 MCP 工具名；false 保留代理调用。directTools: "search" 将工具先注册为未激活，mcp 搜索命中后再激活。

先从代理模式开始，发现真实工具名后再选择高频项。直接模式不会绕过服务启动、授权或审批；大量启用 schema 会减少代理原本带来的上下文收益。

先验证发现，再做只读调用

打开 /mcp 检查配置，再在 Pi 中请求下面两次调用。连接可能启动配置的本地进程，并为之后的搜索填充元数据。根据返回 schema 选择一个只读工具，填写它实际要求的参数。

分别确认服务、schema 和真实工具结果。如果只有发现成功，缓存可能掩盖服务不可达。授权与服务部署仍由相应服务决定。本指南核验了源码和配置，未启动第三方 MCP 服务。

mcp({ connect: "chrome-devtools" })
mcp({ search: "list pages" })

何时直接用原生扩展

如果只需要网页搜索及正文提取，pi-web-access 可直接提供 Pi 原生工具，无需配置 MCP 服务。需要接入已有数据库、浏览器或其他 MCP 服务能力时，再使用适配器。