在 Model Context Protocol（MCP，模型上下文协议）风靡开发者社区的当下，很多新手团队只要想扩展 Agent 能力，第一反应就是盲目部署几个庞大的 MCP Server。

然而，这种无脑接入往往会带来沉重的工程反噬：

• 原本只需要运行一条 gh pr list 或 kubectl get pods 就能解决的事情，非要拉起一个复杂的容器化 MCP Server；
• 一个原本清晰的业务流程问题，演变成了网络连接超时、stdio 子进程僵死、OAuth 凭据失效和巨大 JSON Schema 撑爆上下文的一连串次生灾害。

Pi 官方在架构上做出了一个非常特立独行且清醒的决定：官方内核坚决不内置 MCP 支持！

官方的建议路线非常坚定：

1. 如果只是团队流程或规范，优先写 Skill；
2. 如果系统已有现成且参数清晰的命令行，优先使用 CLI + Skill；
3. 如果需要一个紧凑的原生能力，优先编写简单的 Extension；
4. 只有当你确实需要跨不同 Agent 平台（如同时供 Claude Desktop、Cursor 和 Pi）复用已有的大型外部工具服务时，才通过第三方适配器 pi-mcp-adapter 接入 MCP。

一、工具 Schema 的隐形杀伤力：Token 与注意力双重踩踏

很多开发者没有意识到：把工具全量暴露给大语言模型是有极高代价的。

为了让模型能够调用一个工具，系统必须在每次请求的上下文中，将该工具的完整定义送给模型：

• 工具唯一标识与详尽的功能描述；
• 每一个参数的 JSON Schema（包含类型、必填项、默认值、枚举约束与字段描述）。

当接入的 MCP Server 包含 30 个工具时，仅工具定义的静态 Schema 就可能消耗 4,000 到 8,000 个输入 Token！
更致命的是：

1. 注意力稀释（Lost in the Tools）：大量的工具描述严重干扰了模型的推理注意力，导致在面对用户指令时出现高频的工具误判或调用幻觉；
2. 破坏 Prompt 缓存：如果某个 MCP Server 支持动态工具列表变化，每次工具增减都会彻底击碎云端大模型的 Prompt Cache，导致接口资费成倍暴涨。

二、pi-mcp-adapter 的两种工具暴露策略

社区成熟的第三方适配包 pi-mcp-adapter 为了攻克这一难题，设计了两种泾渭分明的工具暴露模式：

  flowchart TD
  subgraph ProxyMode ["1. Proxy 代理模式 (默认推荐)"]
    M1["模型上下文仅包含单个通用 mcp 代理工具<br/>(仅占 ~200 Token)"]
    M1 -->|第一步: 搜索| S1["mcp(search='database')<br/>动态检索匹配工具"]
    S1 -->|第二步: 调度| E1["mcp(tool='query_sql', args={...})<br/>代理转发执行底层 Server"]
  end

  subgraph DirectMode ["2. Direct Tools 直出模式"]
    M2["模型上下文直接暴露高频工具完整 Schema<br/>(如 run_browser / take_screenshot)"]
    M2 -->|单步直达| E2["直接发起调用，无需前置检索"]
  end
  

1. Proxy 代理模式（动态按需发现）

• 核心机制：在模型的工具列表中，只注册一个轻量级的 mcp 代理入口。模型如果想调用外部能力，先调用 mcp(search="...") 动态模糊搜索；找到合适工具后，再通过 mcp(tool="...", args={...}) 执行。
• 核心优势：即使后端连接了包含 100 个复杂工具的庞大系统，前端占用的常驻 Token 依然恒定保持在约 200 Token 左右！
• 适用场景：挂载了大量工具但调用频次较低的冷门领域能力。

2. Direct Tools 直出模式（高频快捷注入）

• 核心机制：在配置中通过 directTools 显式圈定少数几个极其核心的原子工具，适配器会将它们直接扁平化注册进模型的原生工具列表中。
• 核心优势：调用路径极短，单步直达，模型拥有最完整的静态 Schema 约束。
• 适用场景：全局核心依赖、高频调用的关键能力（例如截屏、数据库只读快查）。

三、精简的项目级配置实战

在项目根目录下创建 .mcp.json，可以精细化控制每个 Server 的生命周期与暴露范围：

1
2
3
4
5
6
7
8
9
10
11

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@1.0.0"],
      "lifecycle": "lazy",
      "directTools": ["take_screenshot"],
      "includeTools": ["take_screenshot", "get_page_content"]
    }
  }
}

请仔细体味这份配置蕴含的工程推敲：

• lifecycle: "lazy"：采用懒加载策略！只有在任务真正触发该工具时才拉起底层 Node.js 子进程，避免每次打开 Pi 都白白浪费几秒钟去初始化浏览器环境；
• directTools: ["take_screenshot"]：只把截屏这一个高频工具直接暴露给模型；
• includeTools: [...]：显式白名单！只拉取需要的两个工具，坚决阻断该 Server 内部附带的其他 20 多个无用工具进入系统。

四、引入 MCP 后的系统责任激增

将外部协议引入系统，绝不仅仅是多了一个工具，而是意味着你的 Harness 必须承担起全新的运维与生命周期保障责任：

五、Direct 与 Proxy 模式的对照实验设计

要科学评估你的项目到底该用哪种暴露策略，可以设计以下对照实验：

1
2

基准任务：在包含 20 个候选工具的测试服务中，完成“提取指定页面的主标题并生成截图”。
变量控制：分别在 Proxy 模式 与 Direct Tools 模式 下连续跑 5 轮。

记录真实的评估数据矩阵：

结论非常清晰：

• 如果你的工具只有 2 到 3 个，且几乎每个任务都要用，果断使用 Direct 模式；
• 如果工具数量超过 10 个，且大部分处于备选待命状态，必须使用 Proxy 模式守护上下文预算。