Pi Agent 1.0 的 MCP 集成源码解析：工具发现、代码编排与提示词压缩
内容提要
Pi Agent 1.0 通过 MCP 工具按需发现、Codemode 脚本编排和提示词压缩来降低上下文开销：MCP 工具默认不预先声明，模型可用 searchTools 或 tool_search 按需加载；脚本在 QuickJS 沙箱中调用工具，仅将筛选后的结果返回模型；提示词合并重复说明并复用工具 schema，官方称约减少 40%。同时修复了 OAuth 权限合并、多账号隔离和会话恢复工具丢失问题。
延伸解读
按需发现如何降低上下文开销
Pi 1.0 默认不把 MCP 工具 schema 预先放入模型请求，而是通过 exposure 控制工具可见性。codemode 和 deferred 工具注册后即可被脚本调用，但完整声明不进入请求；模型需要时用 searchTools 或 tool_search 按需加载。这样大量工具可以留在运行时，同时控制每次请求携带的声明数量，直接减少上下文占用。
Codemode 脚本编排与结果过滤
Codemode 让模型生成 JavaScript，在 QuickJS 沙箱中通过 tools.<name>() 调用 MCP 工具。嵌套调用仍经过正常工具流水线，参数校验和权限扩展继续生效。脚本可以并行取数、筛选、聚合，只把 text() 或 return 输出的部分交给模型，避免每个 MCP 结果全文进入对话。但脚本失败不会撤销已完成的调用，且 MCP 的 isError 可能正常 resolve，脚本需自行检查。
提示词压缩的实际幅度与边界
官方样本显示，默认工具加 Codemode 开启时，GPT-5.6 请求约从 5300 降到 3300 prompt tokens，减少约 37.7%，发布说明概括为约 40%。压缩主要来自合并重复解释、复用工具 schema、把完整 API 参考移到按需读取的文档。这个数字只描述请求中的提示词，不能直接推成所有 MCP 任务的总费用或耗时都下降 40%。
OAuth 与会话恢复的修复重点
1.0 修复了 OAuth 权限合并、多账号隔离和会话恢复工具丢失问题。stepUpScope() 合并已有权限和本次要求，避免补权限后丢失原有权限；凭据存储键改为 server name 加 URL，使同一 URL 的不同账号拥有独立 token。恢复会话时，_pendingToolNames 先保存尚未注册的工具名，待服务器重连后再加入 active tools，减少工具丢失。
Q&A
Pi Agent 1.0 的 MCP 工具默认是怎么暴露给模型的？
默认采用 codemode 曝光，工具可从脚本调用，但完整声明不会预先进入模型请求；MCP 配置中的 codemode 会被映射为通用工具层的 deferred。
searchTools 和 tool_search 有什么区别？
searchTools 是 Codemode 脚本内的查询函数，返回匹配工具的名称和描述，数据先进入脚本，只有通过 text() 或 return 输出的部分才进入模型上下文；tool_search 是模型可直接调用的工具，它把匹配项加入 active tools，从下一次模型请求开始声明。
Codemode 脚本执行 MCP 调用的流程是怎样的？
模型生成 JavaScript，在 QuickJS 沙箱中运行，通过 tools.<name>(args) 调用 ctx.executeTool()，再请求 MCP 服务器，完整结果回到脚本，脚本筛选聚合后通过 text() 或 return 输出给模型。
Pi Agent 1.0 的提示词压缩具体删减了哪些内容？
合并了重复的执行规则和 helper 说明，把完整 API 参考移到按需读取的文档，已声明工具的完整 TypeScript 声明改成调用与返回字段速览，服务器段按实际路径生成，系统提示中的使用建议也缩短了。
Pi Agent 1.0 在 OAuth 方面修复了哪些问题？
补权限时合并已有权限和本次要求，避免新 token 丢失旧权限；用 server name 加 URL 作为存储键，实现同一服务地址多账号隔离；加入 RFC 9207 的 iss 检查；将可选字段的空串和 null 按未提供处理。
恢复会话时工具丢失的问题是怎么解决的？
1.0 增加 _pendingToolNames，让恢复的工具名先进入待处理集合，注册工具、重建运行时时再把这些名字加入下一组 active tools，避免因 MCP 服务器重连未完成而被过滤掉。
Pi Agent 1.0 的工具搜索对中文查询支持吗？
不支持。分词逻辑只保留 ASCII 字母和数字，纯中文 query 会没有词项，BM25 返回空匹配。中文对话仍可由模型转换成英文关键词、使用工具标识符，或改走 describeNamespace()、describeTool() 和 ALL_TOOLS。
Pi Agent 1.0 的 MCP 传输层支持哪些方式？
支持 stdio 和 Streamable HTTP。stdio 用于启动本地进程，Streamable HTTP 用于远程服务器。1.0.0 不支持旧式 SSE transport，也不渲染 MCP Apps 的 ui:// 资源。
