课程大纲
课程大纲系列主页
学习进度已完成 0/7
05MCP 集成与 Tool Search：从工具污染到懒加载

MCP 集成与 Tool Search：从工具污染到懒加载

进阶进行中

MCP 集成与 Tool Search：从工具污染到懒加载

本文基于 Florian BRUNIAUX 的英文原版改编，原文地址：https://cc.bruniaux.com/guide/architecture 许可：CC BY-SA 4.0

这篇你能拿走什么

MCP（Model Context Protocol）是 Claude Code 扩展工具的官方通道——但很多人接了 5 个 server 之后会发现"还没说话呢，已经吃掉 5-6 万 token 了"。这篇带你看清 MCP 的协议结构、能做和不能做的边界、SEP-1865 MCP Apps 的新交互范式，以及 v2.1.7 之后的 Tool Search 懒加载怎么把上下文从 55K 压到 8.7K。

前置条件

  • 已完成本系列前面的章节
  • 至少接过一个 MCP server（stdio 或 streamable-http 都行）

MCP 架构总览

MCP 把"思考"、"控制"、"执行"分成三层：

  • 黄色层（LLM）：只负责推理，没有数据访问权
  • 橙色层（MCP Server）：安全控制点（策略、验证、日志）
  • 灰色层（真实系统）：受保护数据，对 AI 隐藏
text
┌─────────────────────────────────────────────────────────────┐
│ MCP INTEGRATION                                             │
├─────────────────────────────────────────────────────────────┤
│  CLAUDE CODE                                                │
│    Native Tools          MCP Tools                          │
│    ┌─────────┐         ┌─────────────────────────┐          │
│    │ Bash    │         │ mcp__serena__*          │          │
│    │ Read    │         │ mcp__context7__*        │          │
│    │ Edit    │         │ mcp__playwright__*      │          │
│    │ ...     │         │ mcp__custom__*          │          │
│    └─────────┘         └───────────┬─────────────┘          │
│                                    │ JSON-RPC 2.0           │
│                                    ▼                        │
│                           MCP SERVER                        │
│                           stdio/HTTP transport              │
│                           Tool definitions (JSON Schema)    │
│                           Tool implementations              │
└─────────────────────────────────────────────────────────────┘

关键事实：

方面行为
协议通过 stdio 或 HTTP 使用 JSON-RPC 2.0
工具命名mcp__<server>__<tool> 约定
上下文共享只通过工具参数和返回值共享
生命周期server 在首次使用时启动，会话期间保持存活
权限与原生工具同一系统

MCP 不能做什么

这几条非常重要：

限制解释
访问对话历史只看到工具参数，不看到完整上下文
跨调用维持状态每次调用都是独立的（除非 server 自己实现缓存）
修改 Claude 的系统提示只有工具，没有 prompt injection
绕过权限与原生工具同一安全层

如果你在设计 MCP server，记住：它是工具，不是 agent 的延伸大脑。把"记住用户偏好"、"会话连续推理"这种事放 server 里几乎都会出问题，应该走 Claude Code 的 memory 系统或者由 client 维护状态。

MCP Apps（SEP-1865）

状态：稳定（2026-01-26）。规范：GitHub 上的 SEP-1865。共同作者：OpenAI、Anthropic、MCP-UI creators。

它解决什么问题

传统的文本响应会给"需要探索"的 workflow 带来摩擦——每次排序、过滤、下钻都需要新一轮 prompt 循环。MCP Apps 让 MCP server 可以在对话中直接渲染交互式 UI，消除这种 context gap。

两个核心原语

  1. 带 UI 元数据的工具定义：
json
{
  "name": "query_database",
  "description": "Query customer database",
  "_meta": {
    "ui": { "resourceUri": "ui://dashboard/customers" }
  }
}
  1. UI Resources（ui:// scheme）：server-side HTML / JavaScript bundle；由 host 在 sandboxed iframe 中渲染；通过 postMessage 进行双向 JSON-RPC 通信。

安全模型

层级保护
Iframe sandbox受限权限（不能直接访问系统）
Pre-declared templateshost 在渲染前审查 HTML / JS
Auditable messaging所有 UI 到 host 的通信经 JSON-RPC 日志
User consentUI 主动发起工具调用前需要用户同意
Content blockinghost 可在渲染前拒绝可疑资源

平台支持

平台MCP Apps 支持
Claude Desktop现在可用
Claude Cowork即将推出
VS CodeInsiders build 支持
ChatGPT2026-01-26 那一周开始推出
Goose现在可用（开源 CLI）
Claude Code CLI不适用（终端文本环境，不能渲染 iframe）

也就是说，Claude Code CLI 用户不会直接受益，但如果你在写自己的 MCP server，Apps 现在是一个设计选项；如果你做混合 workflow，可以用 Claude Desktop 通过 Apps 探索数据，再切到 Claude Code CLI 做实现。

何时该用 MCP Apps

text
Building a custom MCP server?
├─ Users need to SELECT from 50+ options? → MCP Apps
├─ Users need to VISUALIZE data patterns? → MCP Apps
├─ Users need MULTI-STEP workflows with conditional logic? → MCP Apps
├─ Users need REAL-TIME updates? → MCP Apps
└─ Simple data retrieval or actions only? → Traditional MCP tools

MCP Tool Search：懒加载救命

可信度：100%（Tier 1 - 官方）。来源：anthropic.com/engineering/advanced-tool-use。

它解决的问题

MCP 工具定义会消耗大量上下文。例：仅 GitHub MCP 的 93 个工具就约 46K tokens。开发者 Scott Spence 记录到在输入第一个 prompt 前已经消耗 66,000+ tokens。这种"上下文污染"曾经是限制 MCP 实际采用的最大障碍。

Tool Search 怎么工作

text
WITHOUT Tool Search (eager loading):
  All 100+ tool definitions loaded upfront (~55K tokens)

WITH Tool Search (lazy loading):
  Step 1: Only search tool loaded (~500 tokens)
  Step 2: Claude determines needed capability
  Step 3: Tool Search finds matching tools (regex/BM25)
  Step 4: Only matched tools loaded (~600 tokens each)
  Step 5: Tool invoked normally

Result: 55K tokens → ~8.7K tokens (85% reduction)

Anthropic 官方 benchmark

指标之前之后改进
Token overhead（5-server 设置）~55K~8.7K减少 85%
Opus 4 工具选择准确率49%74%+25 points
Opus 4.5 工具选择准确率79.5%88.1%+8.6 points
Opus 4.6 adaptive thinkingN/A自动校准动态深度

配置（v2.1.9+）

bash
# Environment variable
ENABLE_TOOL_SEARCH=auto       # Default (10% context threshold)
ENABLE_TOOL_SEARCH=auto:5     # Aggressive (5% threshold)
ENABLE_TOOL_SEARCH=auto:20    # Conservative (20% threshold)
ENABLE_TOOL_SEARCH=true       # Always enabled
ENABLE_TOOL_SEARCH=false      # Disabled (eager loading)
阈值推荐场景
auto:20轻量设置（5-10 个工具）
auto:10平衡默认值（20-50 个工具）
auto:5power users（100+ 工具）

引用 Simon Willison 的话："上下文污染是我很少使用 MCP 的原因。现在这个问题解决了，没有理由不把几十个甚至上百个 MCP 接到 Claude Code 上。"（X，2026-01-14）

实战注解

我自己的 MCP 接入策略变了两次：

第一阶段（早期）：能接就接，结果发现单是 GitHub + Slack + Playwright 三个 MCP 加起来 50K+ tokens。每次会话开头就"半饱"。

第二阶段（v2.1.7 后）：开 ENABLE_TOOL_SEARCH=auto:10，能接的都接，但只有真正用到的工具才会进上下文。日常 GitHub MCP 接着，但首条 prompt 的 token 消耗从 60K 降到 9K。

第三阶段（更进一步）：把"做什么"和"怎么做"分开——MCP server 我只放真正需要 server 端权限的工具（比如要 OAuth、要写数据库的），轻量数据访问全部走自己的本地脚本 + Bash。这样 token 预算和权限边界都更清晰。

关于 MCP Apps：CLI 用户暂时用不上，但如果你在做 MCP server，建议从设计第一天就考虑 UI 能力——SEP-1865 已经稳定了，未来在 Desktop / IDE 用户那边的体验会拉开差距。

可信度回顾

  • Tier 1（官方 100%）：MCP 协议结构、工具命名约定、Tool Search 懒加载机制及 benchmark、MCP Apps SEP-1865
  • Tier 2（70-90%）：本篇没有 Tier 2 内容
  • Tier 3（推断）：本篇没有 Tier 3 内容

这一节几乎全部是 Anthropic 与 MCP 联合官方文档级内容，可以放心当行为契约用。

常见问题

Q：MCP server 能记住用户偏好吗？ A：技术上 server 自己可以维护状态，但 Claude 端每次调用都是独立的。正确做法是把偏好写进 CLAUDE.md 或 memory 文件，让 Claude 主动告诉 server 当前偏好，而不是依赖 server 状态。

Q：Tool Search 会不会漏选关键工具？ A：早期版本会，2026-01 后准确率到 88.1%（Opus 4.5）。如果你的工具数 <20，用 auto:20 阈值；>100 用 auto:5。能 hit 的工具都会被加载，只是会延迟一步。

Q：streamable-http MCP 和 stdio MCP 哪个更好？ A：本地工具用 stdio（启动快、零配置）；多人共享或带 OAuth 的用 streamable-http（无状态模式更稳）。Claude Code 两种都原生支持。

来源与许可

  • 原作者：Florian BRUNIAUX；Claude（Anthropic）参与贡献
  • 英文原版地址：https://cc.bruniaux.com/guide/architecture
  • 源文件：FlorianBruniaux/claude-code-ultimate-guide / guide/core/architecture.md
  • 本文基于 CC BY-SA 4.0 改编：保留署名、来源链接，衍生作品同样以 CC BY-SA 4.0 公开
  • 内容版本：原作 v1.1.0 / Claude Code v2.1.34（2026-02）
MCP 集成与 Tool Search：从工具污染到懒加载 | 资讯狗 | Zixungou