| 版本 | 内容 | 时间 | | ---- | ---- | ------------------- | | V1 | 新建 | 2026-08-13 00:06:02 | ## 从一个真实的焦虑开始想象这样一个场景：你给自己的 AI 编程助手接了 30 个 MCP Server—— 文件系统、数据库查询、Sentry 错误追踪、Slack 消息、Jira 工单、GitHub PR、Confluence 文档…… 加起来将近 500 个工具。很多简易 Host 的错误实现：每次打开一个新的对话会话，系统做的第一件事，就是把这 500 个工具的定义 —— 每个工具的 JSON Schema、参数说明、返回值类型，一股脑塞进大模型的上下文窗口。结果是什么？**用户还没打一个字，上下文窗口已经被工具定义吃掉了一大半。** 模型在阅读用户问题之前，就要在几百个不相关工具的描述里，处理数万的 Token。官方给出实测对比：一次性全量加载全部工具定义，会消耗约 **150000 token**；采用渐进式发现之后，仅需要约 **2000 token**，下降幅度接近 99% Model Cont...。这个不是纸上推演的理论问题。当 MCP 从演示 Demo、少数几个插件，走向数十个 MCP Server 聚合的生产环境，这是每一个 MCP Host 开发者都必须直面的现实问题。官方文档把这个问题拆成了两层，并给出了两个对应的解决模式： - **Token 爆炸问题**：工具定义本身占满上下文。对策 → **渐进式工具发现** - **中间结果轰炸问题**：链式工具调用时，每一步的中间结果都流过模型上下文。对策 → **程序化工具调用 / 代码模式** 这两个模式可以组合使用，是本篇文章的核心。但在深入这两大模式之前，我们需要先理解 2026-07-28 版 MCP Client 的底层架构变化——不理解这些，就无法理解最佳实践的前提。 ## 2026-07-28 版本：Client 的「新宪法」如果你上一次读 MCP 规范还是 2025 年的版本，那么 Client 层的变动可以概括为一句话：**从「有状态握手式」变成了「无状态自证式」**。具体来说是这 5 个关键变化： ### 取消 `initialize` 握手 → 每请求自证身份旧版协议里，Client 启动后第一件事是发 `initialize` 请求，和 Server 协商协议版本和能力——这是一次连接级的握手，后续所有请求都基于这次握手的约定。 **2026-07-28 彻底取消了这个机制**。协议变为完全无状态：处理每个请求所需要的全部信息——协议版本、Client 身份、能力声明——都必须携带在请求本身的 `_meta` 字段里。Server 不得依赖同一连接上先前请求的任何状态。 ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": { "_meta": { "io.modelcontextprotocol/protocolVersion": "2026-07-28", "io.modelcontextprotocol/clientCapabilities": { "elicitation": { "form": {}, "url": {} } } } } } ``` > 为什么重要：无状态设计意味着 Server 可以水平扩展——任意实例处理任意请求，不需要 sticky session。对于 stdio 本地模式，这似乎无关紧要；但对于 Streamable HTTP 远程 Server，这是架构的基础前提。 ### 新增 `server/discover`（Server MUST 实现）一个请求就能获取 Server 的完整元信息：支持的协议版本列表、能力声明、身份信息（`serverInfo`，仅用于展示/日志，不可用于安全决策）。`server/discover` 同时承担了版本探测的职责——在 stdio 模式下，它是探测 Server 是否支持 modern 协议的首选手段。 ### MRTR（多轮往返请求）取代服务器主动请求旧版中，Server 在处理 Client 请求期间可以反过来向 Client 发 JSON-RPC 请求（比如请求 LLM 补全）。2026-07-28 把这个流程改成了 **MRTR 模式**：Server 返回 `InputRequiredResult`（`resultType: "input_required"`），Client 收集所需输入后，**重新发起同一个方法的新请求**，附上 `inputResponses` 和逐字节回显的 `requestState`。 > 为什么重要：这改变了 Client 的请求处理模型——Client 不能再简单地「发请求→等结果」，必须实现重试循环，每次重试用新的 JSON-RPC `id`，且不能擅自修改 `requestState`。 ### 弃用 Roots、Sampling、Logging - **Roots**：旧的目录边界声明机制，改为通过工具参数、资源 URI 或 Server 配置传路径。 - **Sampling**：旧的 Server 通过 Client 请求 LLM 补全的能力，建议新实现直接集成 LLM provider API。 - **Logging**：旧的协议级日志机制，迁移到 stderr（stdio 模式）或 OpenTelemetry。 ### Elicitation 并入 MRTR 流程 Elicitation（2025-11-25 版本引入的向用户收集信息机制）在本版并入 MRTR 流程，并移除其完成通知 `notifications/elicitation/complete`。它支持两种模式： - **Form 模式**：Client 构建输入表单，数据经 Client 传回 Server - **URL 模式**：用户通过 URL 带外交互，数据不经过 Client——适合敏感流程注意 Elicitation 与 Sampling 是两种不同机制：后者是 Server 通过 Client 请求 LLM 补全的能力（已弃用，迁移路径为直连 LLM provider API），并非「向用户要信息」。这是本文后续「安全」章节的重要话题。 --- 以上是新版协议的基本盘。现在我们回到那两个核心答案：怎么处理「大量工具」？怎么处理「中间结果轰炸」？ ## 核心模式一：渐进式工具发现 ### 问题量化假如你有 30 个 Server、每个平均 10 个工具，每个工具定义约 500 token。全量注入的代价是：**15 万 token 只为了描述「模型可以调什么」**——在 20 万 token 的上下文窗口里，这占了 75%。 ### 三层架构：Catalog → Inspect → Execute ```mermaid flowchart LR A[Model收到用户问题] --> B[Layer1 Catalog
调用search_tools
仅返回name+desc，无Schema] B --> C{找到候选工具?} C -->|是| D[Layer2 Inspect
调用get_tool_details
本地缓存读取完整Schema
载入LLM上下文] C -->|无匹配| B D --> E[Layer3 Execute
执行真实业务工具调用] E --> F[任务完成
不需要的工具Schema不驻留上下文] style B fill:#e6f7ff style D fill:#fff7e6 style E fill:#f0fff4 ``` 官方推荐用一个轻量级的 `search_tools` 元工具作为入口，分三层层层递进： **Layer 1 — Catalog（目录）**：模型调用 `search_tools({ query: "更新 salesforce 记录" })`，只返回工具名和一行描述，不返回完整 schema。 ```typescript search_tools({ query: "update salesforce record" }) // → [ // { name: "salesforce_updateRecord", description: "更新 Salesforce 对象字段" }, // { name: "salesforce_upsertRecord", description: "基于外部 ID 插入或更新" } // ] ``` **Layer 2 — Inspect（检查）**：模型锁定候选后，用 `get_tool_details({ name })` 拉取**单个工具**的完整定义（inputSchema、outputSchema）。只有这一步才把几百行的 JSON Schema 载入上下文。 **Layer 3 — Execute（执行）**：模型拿到完整接口定义后正常调用。此时上下文中只有它真正需要的那几个工具的定义，而不是全部 500 个。 > 为什么重要：这个分层的本质是「token 惰性加载」——模型在 Catalog 层用的只是几十个 token 的工具名列表，只有真正需要的工具才付出加载完整 schema 的代价。官方文档指出，该模式可显著降低 token 用量，并提升工具选择准确率。 ### 什么时候使用渐进式工具发现渐进式工具发现 **仅适用于工具定义大量占用上下文窗口的规模化场景**。 - **小规模工具集（默认全量加载）** 当所有工具的描述、Schema 总 Token 量，**仅占上下文窗口极小比例**时，直接一次性全量加载所有工具定义即可，实现简单、模型调用更稳定。 - **大规模工具集（启用渐进式加载）** 当工具定义总量 **显著占用可用上下文窗口**、挤压用户提问与推理空间时，Host 必须自动切换为「渐进式工具发现」模式，避免未交互先耗尽 Token。官方最佳实践：阈值自动切换机制，MCP 官方建议 **Host 必须实现动态阈值开关**：以「工具定义总 Token 占 LLM 上下文窗口的百分比」作为判定标准： - **阈值推荐：1%～5%** - 工具总 Token 占比 **≤ 阈值**：全量加载所有工具 - 工具总 Token 占比 **＞阈值**：自动切换 Catalog → Inspect → Execute 渐进式惰性加载核心设计意图：小规模场景追求**简单稳定**，大规模场景追求 **Token 极致节省 + 降低模型干扰**，通过阈值自动适配两种运行模式，兼顾开发成本与生产性能。 ### 搜索策略选型 `search_tools` 背后选什么检索机制？官方给了四种路径，有明确的优先级建议。另外，若 provider 原生提供工具搜索（如 OpenAI / Anthropic 已支持），优先直接用平台的工具搜索，而不是自己实现： | 策略 | 说明 | 适用场景 | |------|------|---------| | **关键词法**（BM25、正则） | 简单有效 | 工具命名和描述比较规范时效果好 | | **嵌入法**（向量相似度） | 处理同义词和语义匹配 | 工具描述多样化时优于关键词 | | **Subagent**（小模型选工具） | 效果通常最好但更贵 | 对检索质量要求最高时 | | **混合法** | 关键词 + 嵌入结合，互为补充 | 工具规模大、命名与语义都不够规律时 | ### 动态服务器管理渐进式发现的思路可以延伸到 Server 层面： 1. Host 维护可用 Server 注册表 + 高层描述 2. **按需连接**：只在模型判定需要时连接某个 Server 3. **按需断开**：与当前任务无关的 Server 断开，释放上下文 ```mermaid sequenceDiagram participant Model participant Host participant Registry participant Server Model->>Host: search_available_servers("CRM") Host->>Registry: Query available servers Registry-->>Host: Salesforce server (not connected) Host-->>Model: Salesforce server available Model->>Host: enable_server("salesforce") Host->>Server: server/discover Server-->>Host: Supported versions + capabilities Host->>Server: tools/list Server-->>Host: Tool definitions Host-->>Model: Salesforce server connected rect rgb(255,255,200) note over Model: Task complete end Model->>Host: disable_server("salesforce") Host-->>Model: Server disconnected, context freed ``` 这特别适合通用 Agent——用户意图未知时，只保持少量常开 Server，然后根据需要再连接其他 Server ### 与 Prompt Caching 的交互这里有一个容易被忽视的「陷阱」：大多数 LLM provider 会缓存 prompt 前缀（包括 `tools` 数组）。如果你在会话中增删工具定义，缓存就会失效——**一次 cache miss 的 token 代价可能超过你删掉的那些工具定义本身。** 官方给出的两条保住缓存命中的方法： 1. 新发现的工具定义**追加在缓存断点之后**，不要重排 `tools` 数组 2. 所有工具调用统一通过一个永不变化的 `call_tool({name, args})` 元工具路由 > 在 LLM 调用成本敏感的今天，一个「优化工具定义加载」的机制如果反过来破坏了 prompt caching，可能得不偿失。这是实现细节中的魔鬼。 ## 核心模式二：程序化工具调用 / 代码模式 ### 问题描述直接工具调用的工作模型是：**模型生成工具调用指令 → Client 执行 → 完整结果流回模型上下文 → 模型决定下一步 → 再生成调用……** 当你需要链式调多个工具时——比如「读文档 → 解析错误日志 → 分类归纳 → 为每种错误建工单」——每一步的中间结果都会流过模型上下文。即使中间有几千行日志数据、模型完全不需要「看」这些数据，它们还是全部涌入了上下文窗口。 ```mermaid sequenceDiagram title ❌ Direct tool calling — each result flows back through the model participant LLM participant LoggingServer as Logging Server participant TicketingServer as Ticketing Server LLM->>LoggingServer: getLogs({ level: "error" }) LoggingServer-->>LLM: ← 2,000 log entries (~50K tokens) Note over LLM: filter... LLM->>TicketingServer: createIssue({ title: "Error: timeout" }) TicketingServer-->>LLM: { issueId: "T‑101" } LLM->>TicketingServer: createIssue({ title: "Error: null ref" }) TicketingServer-->>LLM: { issueId: "T‑102" } Note over LLM,TicketingServer: ... repeated for each unique error ... Note right of TicketingServer: ~100K+ tokens ``` > [!note] > > 渐进式工具发现解决的是「工具定义 Schema 占用 Token」；代码模式解决的是「**工具返回的业务中间结果占用 Token**」，两者可以组合使用。 ### 解决方案：模型输出脚本，沙箱内执行工具调用 **核心思想**：模型不直接调工具，而是写一段**在沙箱里执行的代码**来调用工具。代码执行完后，只有最终的摘要（一行 `console.log`）回到模型上下文。核心思想：模型不再一轮一轮发起工具调用，而是输出一段业务脚本，在 Host 受控沙箱内部完成多步工具调用、数据过滤、循环聚合。**大批量中间业务数据保存在沙箱内部，不流入大模型上下文；仅最终汇总摘要返回给模型**。这需要三步： **Step 1 — 由 MCP 工具 Schema 自动生成沙箱调用 API** Host 读取各个 MCP Server 的`tools/list`工具定义，基于`inputSchema`、可选的`outputSchema`，自动生成沙箱内部可调用的类型化包装函数。沙箱脚本通过这些代理函数间接调用 MCP 服务。 ```typescript // Host 自动生成，注入沙箱 function logging_getLogs(input: { level: string; since: number }) : Promise<{ entries: LogEntry[] }> { return mcp.callTool("logging_getLogs", input); } function ticketing_createIssue(input: { title: string; priority: string }) : Promise<{ issueId: string }> { return mcp.callTool("ticketing_createIssue", input); } ``` 如果 Server 没有提供 `outputSchema`，两条路：用泛型（`any`/`string`）继续，或借助小模型做类型抽取。 **Step 2 — 模型编写业务处理脚本** 针对任务「读取过去一小时错误日志，为每一类不同错误创建工单」。传统逐轮工具调用会把成千上万条原始日志全部送入模型上下文，代码模式下，模型直接输出完整处理脚本，循环、去重、过滤全部在沙箱内完成。 ```typescript // 模型生成的代码，在沙箱内执行 const logs = await logging_getLogs({ level: "error", since: Date.now() - 3600000, }); // 在沙箱内去重过滤——数据不进模型上下文 const uniqueErrors = new Map(); for (const log of logs.entries) { if (!uniqueErrors.has(log.message)) { uniqueErrors.set(log.message, log); } } for (const [message, log] of uniqueErrors) { await ticketing_createIssue({ title: `Error: ${message}`, priority: "high", }); } // 仅摘要输出返回给大模型 console.log(`Filed ${uniqueErrors.size} tickets from ${logs.entries.length} error logs`); ``` **Step 3 — 沙箱执行脚本，代理转发 MCP 调用** 沙箱拦截脚本内对包装函数的调用请求，Host 代理转发请求到对应 MCP Server；工具返回数据停留在沙箱内存。**只有 console.log 输出的摘要信息，会传回大模型上下文。**
完整流程如下： ```mermaid sequenceDiagram title ✅ Code Mode 程序化工具调用：中间数据停留在沙箱，不回流LLM participant LLM participant Sandbox as Host Sandbox participant LoggingServer as Logging Server participant TicketingServer as Ticketing Server LLM->>Sandbox: 生成处理脚本 Note over Sandbox: 脚本在沙箱内执行 Sandbox->>LoggingServer: getLogs({ level: "error" }) LoggingServer-->>Sandbox: 2000条日志（保留在沙箱内存） Note over Sandbox: 沙箱内部完成过滤、去重、循环 Sandbox->>TicketingServer: createIssue(...) TicketingServer-->>Sandbox: { issueId } Sandbox-->>LLM: 仅返回摘要："Filed N tickets" Note right of Sandbox: 只有少量摘要Token进入LLM上下文 ``` ### 执行架构的三个组件 ```mermaid flowchart LR subgraph MCP_Host[MCP Host] direction LR LLM[LLM] Sandbox[Sandbox] MCP_Client[MCP Client] LLM-- 生成代码 / writes code -->Sandbox Sandbox-- 函数调用 / function call -->MCP_Client MCP_Client-- 返回值 / return value -->Sandbox Sandbox-- 执行摘要 / console output -->LLM end MCP_Client-- tool call -->MCP_Server_A[MCP Server A] MCP_Server_A-- result -->MCP_Client MCP_Client-- tool call -->MCP_Server_B[MCP Server B] MCP_Server_B-- result -->MCP_Client ``` - **沙箱**：隔离运行模型生成的代码，无直接网络访问，唯一对外接口是生成的函数 - **Host**：接收来自沙箱的函数调用 → 映射到 MCP Server → 执行工具调用 → 结果回沙箱。 - **模型**：只看沙箱返回的内容，对进入上下文的内容有精确控制 ### 沙箱选型 | 语言 | 运行时 | 宿主语言 | 特点 | |------|--------|----------|------| | JavaScript | Deno / `isolated-vm` | Rust/Node/CLI | V8 引擎，细粒度权限，可全禁 | | Python | Monty（实验性） | Rust | 为 AI 场景打造的最小 Python 解释器 | | TypeScript | pctx（早期） | Python/Rust | 以库形式融入代码模式 | | 任意（Wasm） | Wasmtime | Rust/C/Go | 编译到 Wasm，capability 安全 | ### 安全注意事项程序化工具调用新增了**代码执行攻击面**，沙箱环节必须做严格安全管控，下面是生产环境必须落实的安全约束。 1. **每次工具调用都要做授权校验** 从协议层面，沙箱发起的工具调用，本质依然是 MCP Host 发起调用，**沙箱产生的调用，必须和普通直接工具调用使用同一套人工审批、鉴权策略**。注意：不能说 “同意运行这个脚本”，就无条件允许脚本运行时随意调用任意工具。可选优化：可以授予脚本**单次运行范围内的分类权限**，例如 “本次脚本运行，允许调用`ticketing_createIssue`”，避免每循环一次就弹一次人工确认。即便授予分类权限，Host 代理依然要对**脚本产生的每一次工具调用**做权限校验，不能直接放行。 2. **跨 MCP Server 数据流安全** A MCP Server 返回的工具结果，交给 B MCP Server 作为入参时，**A 的返回数据属于不可信输入**。 Host 代理转发调用时，跨服务的数据，要执行和普通调用完全一样的输入校验、参数过滤逻辑。 3. **沙箱网络隔离**：沙箱环境**禁止直接访问网络**。脚本所有对外、对 MCP Server 的通信，全部经过 Host 代理中转；所有访问控制、鉴权逻辑统一在 Host 层执行，沙箱本身不能直接发起网络请求。 4. **凭证不能泄露到沙箱** 所有 API Key、Token、密钥统一保存在 MCP Host 层。模型生成的脚本，只能调用 Host 预先注入的封装类型函数；Host 在转发请求到各个 MCP Server 的时候，才自动附加鉴权凭证，**沙箱内运行的代码永远拿不到密钥**。 5. **沙箱资源限制，防止脚本失控**：对沙箱内脚本执行强制资源管控： - 设置最大执行超时时间 - 设置内存上限防止模型生成死循环、耗 CPU / 内存的恶意脚本，避免把整个 Host 服务拖垮。 6. **沙箱输出过滤** 沙箱`console.log`输出返回给大模型之前，必须校验、过滤、截断输出内容。防止沙箱输出超大文本、恶意注入提示词的内容回流进 LLM，引发 Prompt 注入。 ### 程序化工具调用的错误处理 MCP 工具业务错误通过响应字段`isError: true`标识，属于传输层面成功的响应，不会自动抛出异常。 - Host 生成的沙箱代理包装函数，需要检测`isError:true`并主动抛出异常，使模型编写的脚本可以通过`try/catch`捕获工具业务错误。 - 脚本发生未捕获异常而终止时，Host 必须将完整错误信息作为脚本执行结果返回 LLM，支持模型自查、修正代码后重试。 - MCP 不存在事务回滚机制，脚本执行中途报错，已经完成的工具调用产生的副作用会真实留存，**由模型向用户报告任务的部分执行状态**。 ## 两种模式组合使用渐进式工具发现与程序化工具调用可以协同工作，发挥最大收益。模型通过渐进式工具发现，识别当前任务需要用到的工具，仅加载对应工具的 Schema；之后生成一段完整脚本，在沙箱单次运行中完成多次工具调用。这套组合同时削减两部分 Token 开销： - 减少大量工具定义（Schema）带来的上下文占用； - 避免工具返回的大批量中间结果反复流入模型上下文。组合使用同时最小化了「工具定义的 token 成本」和「工具结果的 token 成本」，让模型上下文聚焦推理而非搬运数据。， > [!warning] > > 补充现实边界 > > 1. 不是所有任务都适合这套组合。如果任务中间需要 LLM 做多次语义判断、不能完全流水线化，依然需要回退普通工具调用。 > 2. 渐进式发现负责 “拿到少量需要的工具定义”；Code Mode 负责 “批量执行工具”，二者各司其职，互不替代。 > 3. 安全约束、错误处理对组合模式全部生效：沙箱鉴权、异常转换、副作用报告逻辑依然需要完整实现。 ## 常见陷阱清单根据官方文档和生态实践，下面是最容易踩的 10 个坑： 1. **全量注入**：每个会话把全部 Server 的工具塞进上下文 → token 爆炸（这是渐进式发现要解决的问题） 2. **中间结果过模型**：链式调用把大数据集来回过模型（代码模式的正面对手） 3. **把连接当会话**：依赖连接级别状态（违反无状态协议） 4. **忽视 `isError`**：把工具执行错误当传输失败吞掉 5. **Prompt Cache 破坏**：会话中增删/重排 tools 数组（一次 cache miss 的代价 > 省下的定义） 6. **MRTR 重试用旧 ID**：必须换新 JSON-RPC `id` 7. **`requestState` 被篡改**：Client 不得解析/修改 `requestState`；Server 必须用 HMAC/AEAD 保护完整性 8. **工具名冲突不消歧**：聚合两个 `search` 工具直接冲突 9. **过度依赖通知**：通知是 best-effort（尤其跨重连），须配合轮询保新鲜 10. **用旧协议知识写新 Client**：initialize 握手、Mcp-Session-Id、GET 流、resources/subscribe……全部移除或弃用了 ## 最佳实践检查清单总结全文，一个合格的 2026-07-28 MCP Client 实现应该具备： **架构层面：** - [ ] 每个请求在 `_meta` 中携带 `protocolVersion` 和 `clientCapabilities` - [ ] 通过 `server/discover` 探测 Server 版本和能力 - [ ] 正确处理 `UnsupportedProtocolVersionError` 的降级/重试逻辑 - [ ] 实现 MRTR 重试循环（新 ID、`requestState` 原样回显） **工具管理：** - [ ] 实现渐进式工具发现（阈值触发、三层 Catalog/Inspect/Execute） - [ ] 多 Server 工具名消歧 - [ ] 缓存工具定义 + `list_changed` 时刷新 - [ ] 配合 prompt caching 策略（追加不重排 / 统一元工具） **代码模式（可选）：** - [ ] 沙箱实现（无网络、无凭证暴露、资源限制） - [ ] `isError` → 异常转换 - [ ] 按调用授权（非脚本级一刀切） **安全：** - [ ] 敏感工具用户确认 - [ ] 调用前展示工具输入 - [ ] Elicitation 安全约束（form 禁敏感信息、URL 同意后打开） - [ ] 图标/URI 白名单、`$ref` 默认禁用 ## 结语 MCP Client 的实现质量，决定了用户对 MCP 生态的第一印象。一个糟糕的 Client 会让「百工具」从「能力」变成「负担」——模型在工具定义的汪洋中迷失，延迟飙升，token 成本失控。而一个遵循最佳实践的 Client，能让模型在任何场景下都只看到它真正需要的那几个工具，中间数据在沙箱内高效流转，安全边界清晰，用户体验流畅。随着 MCP 协议走向无状态化（2026-07-28）、工具数量从「十几个」膨胀到「几百个」、代码模式从「实验」走向「生产」，Client 的角色只会越来越重。它不再只是一个「协议翻译器」，而是一个集工具发现、调用编排、安全防护、用户体验于一体的**智能能力交换机**。 --- *本文基于 MCP 协议 2026-07-28 版本及官方 Client Best Practices 文档撰写。协议细节以官方规范为准。*

04-MCP-MCP Client 最佳实践：工具渐进式加载与沙箱模式.

Dylan Kwok

04-MCP-MCP Client 最佳实践：工具渐进式加载与沙箱模式