Code Mode MCP Tool Interface Improvement Pattern

传统的模型上下文协议（MCP）方法直接将工具暴露给大语言模型（LLM），会造成严重的令牌浪费与复杂度问题。我们已经从直接指令LLM执行任务，转变为教它们自主编写指令——就像“层层嵌套编写代码”的模式（类似“世界驮在乌龟背上，乌龟之下仍是乌龟”的经典隐喻），这一逻辑适用于所有领域。[^1]

多步骤操作中的令牌浪费

经典MCP会催生这种低效模式：

LLM → 工具#1 → 大型JSON响应 → LLM上下文
LLM → 工具#2 → 大型JSON响应 → LLM上下文
LLM → 工具#3 → 大型JSON响应 → LLM上下文
→ 最终答案

每个中间结果都必须回传至模型上下文，每一步都会消耗令牌并增加延迟。对于需要5-10次工具调用的复杂工作流，这种模式的成本会变得极高。

大规模扇出操作的低效性

传统方法在批量场景下会彻底失效：

为个性化触达处理100封邮件：

• 传统MCP方案：100次独立工具调用，每次都需往返LLM上下文
• 每封邮件的抓取操作会向上下文注入1000+令牌的元数据
• 上下文总膨胀量：实际工作开展前就已突破10万令牌
• 结果：上下文溢出、性能衰减，甚至直接执行失败

**代码模式替代方案：**对100条条目执行简单的for循环，全程在沙箱内处理，仅将最终结果同步至LLM上下文。

核心接口局限性

• LLM难以高效驾驭复杂的工具接口
• 与海量的代码训练数据相比，“工具调用”相关的训练数据十分匮乏
• 直接API调用会让多步骤工具交互变得繁琐
• 复杂的工具组合需要多次来回交互才能实现
• 扇出场景（处理大量条目）会超出上下文限制，或成本高得令人望而却步

核心洞见：相比直接调用MCP工具，LLM更擅长编写代码来编排MCP工具。

Code Mode 是对 MCP 服务器的补充（而非替代），它新增了一个临时执行层，可消除消耗大量令牌的往返通信：

职责划分

MCP 服务器（持久层）负责：

• 凭证管理与身份认证
• 速率限制与配额执行
• Webhook 订阅与实时事件
• 连接池与持久化状态
• API 密钥与安全策略

Code Mode（临时层）负责：

• 单执行流程中的多步骤工具编排
• 复杂数据转换与业务逻辑处理
• 消除 LLM context 中冗余的中间 JSON 数据
• “一次编写，立即消亡”的执行模型

核心架构

1. 模式发现（Schema Discovery）：Agent SDK 在运行时动态获取 MCP 服务器的模式
2. API 转换：将 MCP 工具模式转换为带有文档注释的 TypeScript API 接口
3. LLM 工具感知：LLM 接收可用工具的完整 TypeScript API 文档
4. 临时代码生成：LLM 生成可在单个脚本中编排多工具调用的代码
5. V8 隔离环境执行：轻量级、安全的沙箱，执行完成后立即销毁（无持久化状态）
6. 受控绑定：与 MCP 服务器的安全桥接，真实凭证与核心逻辑由 MCP 服务器持有

核心洞察：LLM 清楚应编写何种代码，并非靠猜测，而是因为它能获取由 MCP 服务器模式生成的完整 TypeScript API——它被赋予了强类型接口与配套文档。

增强能力

• 验证机制：编译时校验可在执行前捕获错误
• 语义缓存：通过类型化 API 签名复用已成功的工作流
• 幂等性：利用键值（KV）存储实现检查点/恢复模式，支持部分故障下的恢复

这种方案实现了“两全其美”：MCP 服务器处理运维复杂度，而 Code Mode 则消除了多步骤工作流中通信频繁、令牌消耗高昂的环节。

1. 工具API设计：为你的工具创建便于代码生成的TypeScript接口
2. 绑定实现：开发用于管控外部资源访问权限的安全绑定机制
3. 沙箱环境配置：为V8隔离环境配置恰当的安全约束
4. 代码执行流程：

• LLM 基于提供的API生成TypeScript代码
  • 代码在独立的V8隔离环境中运行
  • 绑定机制提供对工具的受控访问
  • 执行结果返回至Agent，供后续处理

优势：

• 令牌消耗大幅降低：多步骤工作流中令牌使用量减少10倍以上
• 扇形扩展效率显著提升：通过遍历100+条目的for循环替代100+次工具调用，大幅提升大规模场景下的速度与可靠性
• 执行速度更快：消除往返通信环节，缩短整体执行耗时
• 安全性增强：凭证始终存储在MCP服务器内，绝不会传入LLM
• 复杂编排能力：LLM擅长编写编排代码，可高效胜任复杂工作流的编排任务
• CaMeL风格自调试：Agent可借助错误处理与重试逻辑，自行调试生成的任务代码
• 类型验证与语义缓存：支持编译时校验，同时提供工作流复用的可能性
• 保留MCP原有优势：现有MCP服务器无需任何修改即可兼容使用
• 原生幂等性模式：结合状态存储实现检查点/恢复功能，具备天然的幂等特性

劣势/注意事项：

• 基础设施复杂度高：依赖V8隔离运行时基础设施，部署与维护成本增加
• 依赖LLM代码生成质量：执行成功与否完全取决于LLM生成的代码质量
• 不适用于动态研究循环：当工作流的下一步操作需在每个阶段动态决策时，该方案表现受限
• 中间层智能难题：若执行过程中需要调用LLM，会直接违背该方案减少LLM交互的核心设计目的
• 调试难度大：生成代码出现的运行时错误需要额外的专属处理机制
• API设计成本高：需为LLM的代码生成环节设计直观易用的TypeScript接口
• 部分故障处理复杂：需要精心设计状态管理与故障恢复模式，应对部分节点故障的场景