Pi-chat实战：用MCP协议为AI Agent接入外部工具

在构建AI Agent应用时，工具接入是绕不开的核心环节。Pi框架此前提供了两种主流的工具接入方式：自定义工具与第三方扩展。但这两种方式都有一个共同的痛点——必须改代码。当业务系统需要接入大量外部工具时，这种模式的维护成本会急剧上升。MCP协议正是为解决这一问题而生。

两种传统工具接入方式的局限

Pi框架早期的工具接入分为两条路径。第一条是纯自定义工具：通过 defineTool 定义一个工具，再借助 customTools 的方式将其注入到Pi的上下文中，Pi随即就能识别并调用这个工具。第二条则是通过 additionalExtensionPath 接入社区提供的扩展，或是自己编写的扩展。

这两种方式的本质弊端在于对代码的强依赖。新增一个系统能力，走自定义工具就得亲手写一套实现；走第三方扩展则要安装对应的包、重新配置扩展路径。在真实的业务系统里，外部工具的数量往往是数十甚至上百个，这种逐一手写接入的模式难以规模化。

工具接入方式的设计考量

MCP协议：标准化的外部工具接入方案

MCP（Model Context Protocol，模型上下文协议）是由Anthropic公司提出的一套标准化外部工具接入协议。它的目标很明确：让Agent以统一的方式发现并调用外部工具，摆脱对硬编码的依赖。想深入了解协议细节，可以查阅其官网的 specification 部分。

在通信协议层面，MCP目前主流采用两种传输方式：

STDIO：适用于本地场景。例如MCP server通过一个CLI工具实现时，STDIO是最合适的选择。
Streamable HTTP：适用于远程（remote）场景。你可以在远端定义一个MCP server，客户端通过连接（connect）到该server后执行 list tool 来枚举可用工具。

协议演进过程中还曾出现过基于SSE的传输方式，但由于相对复杂，现已基本被淘汰。

MCP协议在架构上遵循典型的客户端-服务端模型：MCP Client（通常内嵌在Agent框架中）负责发现和调用工具，MCP Server则是对外暴露工具能力的独立进程或服务。两者之间通过标准化的JSON-RPC 2.0消息格式通信，核心交互包括三类原语：Tools（工具调用）、Resources（上下文资源读取）和Prompts（提示模板）。这种解耦设计意味着同一个MCP Server可以被任意支持MCP协议的客户端复用，工具的开发者和Agent框架的开发者可以完全独立工作，彻底打破此前「工具与框架强绑定」的局面。Streamable HTTP传输方式相较于早期的SSE（Server-Sent Events），增加了双向流式通信能力，服务端可以主动推送进度通知，更适合长耗时工具调用的场景。

Pi默认不内建MCP，但接入极其轻量

需要明确指出的一点是：Pi默认并不支持MCP协议，它没有提供内建的MCP实现。这或许是框架设计上的一种取舍——功能并非越多越好。但在实际使用中，MCP协议往往是刚需。

好在Pi里接入MCP是一个非常轻松的过程。设想自己从零实现接入的流程：先拿到MCP server的配置，通过STDIO或Streamable HTTP连接上server，执行 list tool 获取全部工具，再通过Pi的 register 机制注册这些工具即可。整个链路并不复杂。

而现实中的接入比这还要更简单，因为Pi社区生态里已经有开发者实现了一个 pi-mcp-adapter 适配器。基于这个适配器，在Pi中集成MCP协议变得轻而易举。

一步步接入扩展

实战：pi-mcp-adapter接入流程

安装与配置文件

第一步是安装适配器包。如果是以插件形式使用，按插件方式安装；如果像实战项目一样，直接用 pnpm install 安装对应包即可。以本项目为例，可通过 pnpm --filter 定位并安装 pi-mcp-adapter。安装成功后，package.json 中就会出现该依赖。

关键的配置在于 .mcp.json 文件。pi-mcp-adapter会读取这个文件，其结构就是标准的MCP server写法：最外层是一个承载MCP server的键值对，内部是各个MCP server的具体实现。例如第一个server名为 chrome-devtools，通过 npx 安装其DevTools实现，借助它就能在Agent中实现对Chrome浏览器的自动化控制。

让配置路径可控

适配器自身有一套寻找 .mcp.json 的目录结构逻辑，但在实战项目中我们希望路径完全可控。因此需要在 globalConfig 中把路径显式定义下来，修改 config.ts，在全局配置上暴露一个 mcpConfigPath 字段。这样持久化目录结构就多出了 .mcp.json 这一配置项。

规避type check错误

用extension factory方式初始化

初始化适配器有两种思路。直接在 additionalExtensionPath 中增加配置项虽然可行，但存在两个问题：一是路径不可控（越靠后优先级越高），二是可能引入type check错误。

更推荐的方式是通过 extension factory 接入。这是一个标准的扩展实现，Pi识别到该扩展后会传入扩展的API对象。拿到对象后即可调用Pi Extension API提供的能力。具体流程为：导入pi-mcp-adapter包，执行初始化，显式从 globalConfig.mcpConfigPath 取出配置路径并传入，同时把Pi实例也传递进去，接入流程即告完成。

Extension Factory是Pi框架中一种更灵活的扩展注册机制，区别于静态的additionalExtensionPath路径加载，它允许开发者在运行时通过代码动态构造扩展实例，并在初始化过程中注入自定义参数（如配置路径、运行时依赖等）。这种方式的优势在于扩展的加载顺序、参数来源和生命周期都处于代码的显式控制之下，避免了配置文件排列顺序带来的优先级歧义。对于需要访问globalConfig等运行时上下文的扩展（pi-mcp-adapter正是如此），Extension Factory是唯一能够在初始化阶段完成参数注入的标准路径。

一个易踩的坑：手动触发session start

在返回 agent session 之前，还需要额外调用一次 run extension，用以强制触发 session start 事件。只有执行了这一步，pi-mcp-adapter才会真正初始化各个MCP server。否则在实际执行过程中，很可能报出「MCP server未初始化」的错误。

项目启动成功

Session Start事件是Pi框架扩展生命周期中的关键节点，标志着一次Agent会话正式开始。pi-mcp-adapter依赖该事件来执行MCP Server的连接与工具枚举（list tool）操作——只有在这一阶段完成初始化，后续的工具调用才能找到对应的Server实例。由于Pi框架本身不会在run extension被调用之前自动广播该事件，若跳过手动触发步骤直接进入会话，适配器内部的Server连接池尚未建立，调用任何MCP工具时都会遇到「server未初始化」的运行时报错。这一设计要求开发者在返回agent session之前显式地补发一次事件，是框架扩展机制与懒加载策略共同作用的结果。

实测：12306火车票查询

为验证效果，作者接入了一个查询12306火车票的MCP server，写法与chrome-devtools一致——server名称加上具体实现。重启项目后，向Agent提问「帮我看看今天从南京去上海的高铁票最近一班什么时候发车」。

Agent的执行链路清晰可见：先 list tool 获取可用工具，明确用户想要高铁（G字头开头），随后调用查询ticket的工具。由于这是一个免费工具，首次调用因 request timeout 稍慢，第二次便成功返回结果。当时是3:26，Agent推荐了最近的3:36班次，并同时给出3:40、3:43、3:48等多个备选方案，体验相当流畅。

拥抱MCP生态的更多可能

MCP的价值在于其标准化带来的生态复用能力。目前第三方MCP market相当丰富，除了浏览器控制、火车票查询，还可以连接Atlas、Cloudflare等云服务，甚至接入本地的ffmpeg等CLI工具。

借助Pi的社区扩展生态与MCP标准化的工具接入机制，开发者可以解锁大量标准化玩法，无需为每个工具重复造轮子。对于正在构建AI Agent应用的团队而言，MCP已经从「锦上添花」逐渐变成了「基础设施」。