MCP——将 Claude Code 连接到一切

MCP 工具加载如何工作

当 Claude Code 会话启动时，每个已配置的 MCP server 都会连接并暴露其工具定义。这些定义——名称、描述、参数 schema——会立即加载到上下文窗口中。这就是 MCP 的代价：你在使用任何工具之前，就已经为每个工具定义支付了上下文 token。

工具搜索系统缓解了这个问题。它默认启用，将大约 10% 上下文容量以内的工具定义直接加载。其余的会被延迟加载——它们的描述被索引，但完整的 schema 不会保存在上下文中，直到 Claude 判断需要它们。当 Claude 遇到可能需要延迟加载工具的任务时，它会搜索索引、加载相关 schema，然后继续。

这种延迟加载是 MCP 能够扩展到数十个 server 而不会立即消耗整个上下文窗口的原因。但它引入了一个隐性代价：搜索步骤本身也消耗上下文并增加延迟。对于你每次会话都会使用的工具，即时加载更好。对于 40 个工具目录中你每次只用 5 个的情况，延迟加载则是必需的。

你可以通过 ENABLE_TOOL_SEARCH 环境变量来控制这一点。禁用它将强制所有工具定义即时加载，如果你只有少量 MCP server 并且希望零搜索延迟，这样做没问题。但如果你有多个 server 和大量工具目录，这样做将是灾难性的。

衡量你的 MCP 上下文代价

/mcp 斜杠命令会显示每个 server 的 token 消耗。运行它。如果你的 MCP server 在你输入任何提示之前就消耗了 15% 的上下文窗口，那你就存在配置问题。要么减少连接的 server 数量，要么确保工具搜索延迟了大部分工具。

上下文代价不仅仅是工具定义。每个工具的 JSON schema——参数类型、描述、枚举、嵌套对象——都会累积。一个文档完善、参数描述丰富的 MCP tool 比一个简洁的工具消耗更多上下文。如果你正在为团队构建 MCP server，请保持 schema 精确但简洁。参数描述中的每个词都是 Claude 在每次请求中需要支付的 token。

MCP 资源

MCP server 不仅能暴露工具，还能暴露资源——你可以使用 @ 引用来引用的结构化数据，就像引用文件一样。语法是 @server:protocol://resource/path：

能否分析 @github:issue://123 并建议修复方案？

请查看 @docs:file://api/authentication 处的 API 文档

将 @postgres:schema://users 与 @docs:file://database/user-model 进行比较

在提示中输入 @ 即可查看所有已连接 MCP server 的可用资源。资源与文件一起出现在自动补全菜单中。当你引用资源时，它会自动获取并作为附件包含在对话中。

这很重要，因为它将外部数据提升到与本地文件同等的地位。你不需要让 Claude "使用数据库 MCP tool 获取用户表 schema"，而是直接引用 @postgres:schema://users，它就会出现在上下文中。单个提示中可以引用多个资源。模型将它们视为结构化输入而非 tool 调用输出，这通常会产生更好的响应，因为数据在推理开始之前就已经存在，而不是在对话中途才被获取。

集中化配置

MCP server 在项目根目录的 .mcp.json 中配置。此文件应该提交到版本控制。一个人搞定 MCP 配置，整个团队受益。

{
  "mcpServers": {
    "analytics": {
      "command": "node",
      "args": ["./mcp-servers/analytics/index.js"],
      "env": {
        "DB_CONNECTION": "${ANALYTICS_DB_URL}"
      }
    }
  }
}

环境变量插值让配置可以引用凭据而无需嵌入它们。.mcp.json 文件包含结构；实际的秘密信息存在于每个开发者的环境中。

托管 MCP：允许列表、拒绝列表和自动批准

对于企业，托管设置可以限制允许哪些 MCP server。允许列表（托管设置中的 allowedMcpServers）指定唯一可以配置的 server。拒绝列表（deniedMcpServers）阻止特定 server。这防止开发者将任意外部服务连接到他们的 Claude Code 会话——当组织有数据分类策略时，这是一个有意义的控制。

允许列表/拒绝列表在配置层面运作。如果某个 server 不在允许列表上，Claude Code 将不会连接它，无论项目的 .mcp.json 中写了什么。这与第二章中描述的权限范围层级的覆盖模式相同：托管设置优先。

三个用户级设置控制项目定义的 MCP server 的批准流程：

enableAllProjectMcpServers 自动批准项目 .mcp.json 文件中的所有 MCP server。当你信任你工作的代码仓库并希望零摩擦时，将其设为 true。当你想逐个批准每个 server 时，将其设为 false（默认值）。

enabledMcpjsonServers 是一个特定 server 名称的自动批准列表：["memory", "github"]。此列表上的 server 连接时不会提示。不在列表上的 server 仍然需要批准提示。

disabledMcpjsonServers 是一个特定 server 名称的拒绝列表：["filesystem"]。此列表上的 server 永远不会连接，即使项目的 .mcp.json 定义了它们。

这些设置对组织部署很重要。团队可以将 .mcp.json 提交到版本控制，包含项目所需的所有 server，然后配置托管设置来允许列表中的 server 并拒绝列表以外的所有内容。新团队成员克隆代码仓库后自动获得 MCP 配置，而托管设置确保没有恶意 server 连接。

MCP 哪里会出问题

MCP 连接不如本地 tool 调用可靠。了解故障模式可以防止当事情悄然出错时的困惑。

静默断开连接

MCP server 可能在会话中途断开连接。当它断开时，它提供的工具会直接消失。Claude Code 不会抛出错误。它不会通知你。工具就是不见了。如果 Claude 正在依赖该 server 的某个工具，它要么找不到该工具，要么尝试一种可能不是你期望的回退策略。

症状是微妙的：Claude 停止使用它刚才还在使用的能力，或者开始手动做之前通过工具做的事情。如果 Claude 突然开始编写原始 HTTP 请求而不是使用你的 API 连接器，检查你的 MCP 连接。

/mcp 命令显示当前连接状态。当行为意外变化时，让它成为你的本能反应。

Server 启动失败

MCP server 可能在会话开始时无法启动。缺少依赖、错误的环境变量、端口冲突——这些都可能阻止 server 初始化。Claude Code 会在没有这些工具的情况下启动会话，你可能直到需要它们时才会注意到它们的缺失。

诊断路径：在会话开始时运行 /mcp。确认所有预期的 server 都已连接且其工具数量符合预期。这需要五秒钟，却能防止三十分钟的困惑。

同名工具

如果两个 MCP server 暴露了同名工具，行为是未定义的。一个会遮蔽另一个。哪个胜出可能取决于 server 初始化顺序，而你无法控制这个顺序。使用 server 特定的前缀命名工具以避免冲突。

Subagent 中的 MCP

MCP tool 在前台 subagent 中可用，但在后台 subagent 中不可用。这是一个硬性架构约束，而非配置选项。

后台 subagent 并发运行且无法与用户交互。MCP server 可能需要交互式身份验证，可能有与并行访问冲突的速率限制，可能产生需要人工审查的输出。与其引入具有不可预测行为的部分支持，这个约束是二元的：前台获得 MCP，后台没有。

实际影响：如果你正在设计 subagent 需要查询外部服务的工作流，这些 subagent 必须在前台运行。如第四章所述，这会影响你的并行策略——前台 subagent 会阻塞主对话。

需要外部数据的后台 subagent 的变通方法：让主 agent 先通过 MCP 获取数据，然后将结果作为任务描述的一部分传递给后台 subagent。这以放弃实时数据访问换取了并行性。

插件中的 MCP

插件可以打包 MCP server 配置，在插件启用时自动启动。从用户的角度来看，插件的 MCP tool 显示为标准工具——与内置能力无法区分。

这是 MCP 的分发机制。与其要求每个团队成员手动配置 MCP server，不如由插件将 server 二进制文件、其配置和自动启动逻辑打包成只需一个启用步骤即可激活的东西。

自动启动行为意味着插件 MCP server 从插件激活的那一刻起就消耗上下文。禁用未使用的插件可以回收这些上下文。如果你的上下文预算紧张，审查哪些插件处于活动状态以及它们的 MCP tool 是否真的被使用。

MCP Tool Hook

Hook 通过命名约定与 MCP tool 交互：mcp__servername__toolname。此模式允许 PreToolUse 和 PostToolUse hook 使用与其他任何工具相同的基于正则表达式的匹配来拦截特定 MCP tool。

匹配 mcp__analytics__.* 的 hook 会拦截你的 analytics MCP server 的每个工具。匹配 mcp__.*__write.* 的 hook 会拦截所有 MCP server 中的任何写操作。匹配 mcp__memory__.* 的 hook 会专门捕获 memory server 上的所有操作。模式匹配足够灵活，可以表达 server 级别、tool 级别或跨 server 的策略。

双下划线约定（mcp__server__tool）并非随意——它是 Claude Code 内部用于为 MCP tool 命名空间的精确格式。当 Claude 调用你的 analytics server 中名为 get_price_history 的工具时，内部工具名为 mcp__analytics__get_price_history。你的 hook 匹配器针对这个完整的命名空间名称，这意味着你可以编写 hook 来区分不同 server 上同名工具。

日志记录

最直接有价值的 MCP hook 是日志 hook。每次 MCP tool 调用——server、tool、参数、时间戳——写入文件或发送到监控服务。这为原本不可见的外部服务访问创建了审计跟踪。

对于受监管的行业，这不是可选的。如果你的 MCP server 连接到金融数据源或客户数据库，Claude 执行的每次查询的可审计日志是合规要求。一个对 mcp__.* 的 PreToolUse hook 加上日志命令，几行配置就能搞定。

转换

PostToolUse hook 可以在 Claude 处理之前转换 MCP tool 的输出。当 MCP tool 返回的数据多于 Claude 需要的时候，这很有用。一个将大型 API 响应过滤为相关字段的 hook 可以减少上下文消耗，并提高 Claude 专注于重要内容的能力。

相反的转换同样有价值：用额外上下文丰富稀疏的 MCP 输出。一个在工具输出中追加元数据或格式化的 hook 可以改善 Claude 的解读，而无需修改 MCP server 本身。

验证

MCP tool 上的 PreToolUse hook 可以在请求到达外部服务之前强制执行输入验证。一个检查数据库查询 MCP tool 是接收到 SELECT 语句（允许）还是 DROP TABLE 语句（拒绝）的 hook，可以在不修改 MCP server 代码的情况下防止灾难性错误。

这是纵深防御。MCP server 应该有自己的输入验证。hook 是捕获 server 可能遗漏问题的第二层防线。

领域特定的连接器模式

最具启发性的 MCP 部署在于具有丰富外部数据需求的领域。金融数据分析提供了一个有用的案例研究，因为它涉及多个数据源、实时数据源、结构化和非结构化数据，以及严格的安全要求。

连接器生态系统

金融服务中的生产分析平台可能通过 MCP 集成十多个数据连接器类别，每个类别是包装特定数据提供者的独立 server：

• 基本面股票数据：公司财务、排名、筛选工具
• 另类数据：从多种来源聚合的非传统数据集
• 基金研究：评级、分析、基金比较数据
• 私募市场数据：风险投资、私募股权、并购情报
• 财报电话会议记录：实时电话会议记录和投资者活动报道
• 专家情报：访谈记录、公司研究、行业分析
• 文档治理：具有权限控制的安全数据室访问
• 实时市场数据：固定收益、外汇、股票、宏观指标的实时定价
• 信用评级：跨数百万实体的实体评级和研究
• 新闻源：实时的全球多资产新闻
• 监管文件：SEC 文件、国际监管提交

每个连接器是一个 MCP server，暴露用于查询其特定数据源的工具。模式在所有连接器中是一致的：

• MCP server 包装数据源的 API 客户端。
• 工具暴露领域特定的查询（获取价格历史、搜索文件、获取基本面数据）。
• 身份验证在 server 级别处理，不通过 Claude 传递。
• 响应 schema 结构化，便于 Claude 直接解读而无需额外解析。

这种架构将凭据排除在 Claude 的上下文之外（它们存在于 MCP server 的环境中），提供了结构化的访问模式而非原始 API 调用，并使每次数据访问可通过 hook 审计。

面向领域工作流的预构建 Agent Skill

除了原始连接器，一些领域已经开发了预构建的 agent skill，将 MCP 数据访问与标准化分析工作流结合。例如在金融服务中，存在用于可比公司分析（估值倍数和运营指标生成基准数据集）、贴现现金流建模（预测、折现率计算、敏感性分析表）、尽职调查数据处理（从文档室提取结构化数据）、财报分析（从电话会议记录中提取指标、指引变化和管理层评论）和覆盖 initiation 报告（带有估值框架的行业分析）的 skill。

这些 skill 本身不是 MCP server——它们是打包的工作流，消费 MCP 连接器的数据并产生结构化输出。这个模式是通用的：任何具有重复分析任务的领域都可以构建 skill 来标准化工作流，同时从 MCP 连接器拉取数据。MCP server 处理数据访问；skill 处理分析流程。

主权财富基金：机构规模的 MCP

公开记录中最引人注目的 MCP 部署涉及一家管理超过万亿美元资产的主权财富基金。该基金构建了自定义 MCP 集成，将 Claude 连接到内部投资组合公司数据系统。大约 9,000 名投资组合经理每天查询这些集成，接收关于投资组合公司表现、指标和趋势的 AI 生成洞察。

这个规模很有启发意义。这不是开发者工具或原型。它是在受监管金融环境中服务数千名用户的基础设施。MCP 架构之所以奏效，是因为凭据和数据访问策略在 server 端，每次查询都可审计，集成点是结构化的——投资组合经理与 Claude 交互，Claude 与 MCP tool 交互，MCP tool 查询基金的内部系统。没有凭据穿越对话上下文。没有非结构化的 API 调用对生产数据库产生格式错误查询的风险。

生产级神经交易平台：41 个 MCP Tool

MCP 集成可能达到的上限在一个将神经预测与实时市场分析相结合的生产交易平台中可见。该系统跨多个领域集成了 41 个 MCP tool：

• 实时分析：市场数据源、价格历史、成交量分析
• 神经预测：GPU 加速预测模型的接口
• 回测：蒙特卡洛模拟和历史策略评估
• 风险管理：仓位大小、回撤分析、相关性监控
• 新闻与情绪：实时新闻分析和情绪评分

神经预测引擎运行最先进的时间序列模型，预测延迟低于 10ms，通过 CUDA 优化实现 6,250 倍的 GPU 加速。Claude Code 生成了预测引擎代码和 MCP 集成层。MCP tool 提供了 Claude 的推理与 GPU 加速推理之间的结构化接口——Claude 决定预测什么以及如何根据预测采取行动，而繁重的数值计算在 GPU 加速重要的 server 端运行。

在这种规模下，本章前面描述的每个配置纪律都成为强制要求。按领域分组的 server 隔离了故障。延迟加载防止了上下文耗尽。命名约定使 41 个工具保持可导航。健康监控在断开连接级联之前捕获它们。

Prompt Router 模式

生产 MCP 部署中一个反复出现的架构模式是 prompt router：一个位于用户输入和 MCP tool 调度之间的分类层。当用户发送消息时，router 在调度到适当的处理管道之前对意图进行分类。

这个模式在实践中是这样的：一个入站请求到达。router 判断用户是想创建什么、分析什么、查询数据，还是执行某个操作。根据分类结果，系统以结构化序列调用特定的 MCP tool。"创建策略"意图触发一个管道：创建投资组合对象、循环创建策略、分解条件、构建结构化对象并发送结果。"分析"意图触发另一个管道：通过 MCP 获取数据、运行分析、返回结果。

这不特定于任何领域。任何向 Claude 暴露许多 MCP tool 的系统都受益于在 Claude 开始推理之前缩小工具集的 router。与其让 Claude 在每个回合从 41 个工具中选择，router 将候选集缩小到与分类意图相关的 5-8 个工具。这既减少了 token 成本（上下文中更少的工具描述），也降低了错误率（更少的不相关工具被误调用）。

三层架构

一种将 MCP 与面向用户应用相结合的生产部署模式使用三层：

第一层：AI 驱动的创建。 用户用自然语言描述他们想要什么。Claude 处理意图、调用 MCP tool 访问数据和计算，并产生结构化输出。这一层 token 消耗大但处理了最难的部分：将人类意图转化为结构化数据。

第二层：可视化展示。 第一层的结构化输出在标准 UI 中呈现。用户以可读格式查看结果、配置和数据。这一层 AI token 成本为零——纯粹的前端渲染。

第三层：无代码精调。 用户通过可视化界面手动调整 AI 生成的输出——切换参数、调整阈值、微调配置。这一层同样 AI token 成本为零。变更反馈到第一层产生的相同数据模型中。

经济逻辑很清晰：AI 处理创意生成（昂贵但高价值），UI 处理展示（免费），无代码编辑处理精调（同样免费）。MCP 位于第一层，提供 Claude 生成结构化输出所需的数据访问和计算。三层分离意味着你只在创建阶段支付 AI token，而非整个用户工作流。

为什么不直接用 Curl？

开发者可以通过给 Claude bash 访问权限并让它对数据 API 运行 curl 命令来完成同样的事情。这可行，但在每个可衡量的维度上都更差。

通过 bash 使用 curl，凭据出现在命令字符串中（在上下文、日志以及可能发送给模型提供商的 API 调用中可见）。访问模式是非结构化的（解析 curl 输出是脆弱的）。审计日志记录需要解析 bash 命令字符串。速率限制必须依赖模型的判断而非 server 端逻辑。

使用 MCP，凭据在 server 端。访问是结构化的。通过 hook 自动记录日志。速率限制由 server 强制执行。初始设置成本更高。运营安全性则是根本性更好的。

架构模式

Go + JavaScript 模式

生产 MCP 部署中一个反复出现的架构使用 Go 处理繁重计算，使用 JavaScript 作为 MCP server 接口。其理由是实用的、由实践者驱动的：Go 处理并发数据处理、复杂算法和性能敏感操作。JavaScript 是 Claude Code 在生成 MCP server 代码时最擅长的语言。

一位实践者直截了当地描述了理由：Go 用于繁重工作是因为现有基础设施专业知识，JavaScript 用于 MCP server 是因为它是 Claude 最容易编写的语言。架构是这样工作的：Go 后端暴露本地 API（HTTP 或 gRPC）。JavaScript MCP server 在 MCP 协议和 Go API 之间进行转换。Claude 与 MCP server 交互；MCP server 委托给 Go。

节省 token 的角度很重要。使用这种架构构建的代码库分析工具报告称，与让 Claude 直接分析代码相比节省了 80-90% 的 token。Go 后端完成繁重的解析和分析，通过 MCP server 返回结构化结果。Claude 接收预消化的信息而非原始源文件，仅消耗一小部分上下文。

这不是唯一有效的架构。Python MCP server 可行。Rust MCP server 也可行。但 Go + JavaScript 的分工利用了一个特定优势：当你要求 Claude Code 构建或修改你的 MCP server 时，它生成的 JavaScript 比 Go 更干净。如果你的 MCP server 是一个薄转换层，AI 生成代码的质量对接口比对计算更重要。

MCP 超越工程领域：营销活动分析

MCP 不仅限于开发者工具和数据 API。一个增长营销团队构建了一个 MCP server，集成了主要社交媒体广告平台的 API，直接在 Claude 中查询营销活动表现、支出数据和广告效果。他们无需在广告平台仪表板和 Claude 之间切换进行分析，而是在一个地方查询所有内容。

MCP server 包装广告 API，暴露获取营销活动指标的工具，并返回 Claude 可以推理的结构化数据。团队使用它来回答诸如"本周每次获客成本最高的营销活动是哪些"或"比较所有活跃营销活动中标题变体 A 与变体 B 的表现"之类的问题。每次查询都可通过 hook 审计，API 凭据永远不会进入 Claude 的上下文。

这是 MCP 模式超越工程领域的泛化：任何涉及查询外部服务、分析响应并基于分析做出决策的工作流都是 MCP 集成的候选。构建 server 的努力是一次性成本。持续收益是从 Claude 的推理循环内对外部数据进行结构化、安全、可审计的访问。

扩展到 41+ 工具

存在跨多个 server 的超过 40 个 MCP tool 的生产部署。在这种规模下，配置纪律变得不可妥协。

使大型集成可行的模式：

• 按领域分组的 server：每个数据领域或服务一个 MCP server。分析工具在一个 server 上，投资组合工具在另一个上，回测工具在第三个上。这使得故障隔离——崩溃的分析 server 不会拖垮投资组合管理。
• 默认延迟加载：有 40+ 工具时，即时加载会消耗令人无法承受的上下文比例。必须启用工具搜索。
• 命名约定：每个工具都带有其领域前缀：analytics_price_history、portfolio_current_holdings、backtest_run_strategy。当名称自文档化时，Claude 能更好地推理工具选择。
• 最小化 schema：每个工具的参数 schema 精确描述所需内容，不多不少。丰富的描述放在 skill 或 CLAUDE.md 参考中，而不是每次会话都加载到上下文中的 schema 里。
• 健康监控：一个启动 hook 或脚本，在开始工作之前验证所有 MCP server 都在响应。三十秒的验证防止一小时的调试来找出工具为什么缺失。

出于数据安全选择 MCP 而非 CLI

MCP 相比原始 CLI 访问的安全性论点值得强调，因为它与"直接用 bash"的直觉相悖。

Bash 是通用的。任何有 CLI 客户端或 curl 端点的 API 都可以通过 bash 访问。MCP 需要构建和维护 server。工作量差异是真实的。

但安全性属性是不等价的。当 Claude 运行 bash 命令时，完整的命令——包括任何嵌入的凭据、API key 或 token——存在于对话上下文中。该上下文被发送到模型提供商的 API。你的凭据经由第三方服务传输。

当 Claude 使用 MCP tool 时，工具名称和参数存在于上下文中。凭据存在于 MCP server 的环境中，永远不会离开你的机器。MCP server 在本地发出经过身份验证的请求。只有响应数据进入 Claude 的上下文。

对于有数据分类策略的组织，这个区别很重要。这是"我们的 API key 出现在第三方 API 调用中"和"我们的 API key 留在我们的基础设施上"之间的区别。如果你的安全团队对凭据可以存在于哪里有意见——他们应该有——MCP 是满足这些意见的架构。

这不是关于对任何特定模型提供商的信任。这是关于架构卫生。凭据属于 server 环境，而非对话上下文，无论另一端是谁。

一个数据基础设施团队简明扼要地说：对敏感数据使用 MCP server 而非 CLI，以维持更好的安全控制，特别是对于有日志记录和隐私关注的数据。CLI 方法适用于内部、非敏感操作。对于任何有合规要求的——对生产数据库的查询、对金融数据提供商的 API 调用、对客户数据系统的访问——MCP 是满足审计员要求的架构。

企业数据隐私模式

在受监管的环境中，MCP 是更广泛的数据处理策略的一个组成部分：

本地文件系统用于敏感数据。 金融数据、客户记录和专有数据集保留在本地机器上。Claude Code 通过标准文件操作访问它们。数据除了模型提供商 API 对对话上下文所需的之外，不会经由外部 API 传输。

MCP 用于受限系统集成。 当 Claude 需要查询数据库、访问内部 API 或与受治理的数据平台交互时，MCP server 介导连接。凭据保留在 server 端。访问模式是结构化且可审计的。MCP server 可以在结果进入 Claude 上下文之前强制执行速率限制、查询限制和数据过滤。

上下文窗口用于非敏感研究。 大型上下文窗口（100,000+ token）对于处理非敏感文档很有用——研究论文、公开文件、开源文档。这些可以直接加载而无需 MCP 开销。

模式是：首先对你的数据进行分类，然后根据敏感度选择访问架构。不是所有东西都需要 MCP。不是所有东西都应该绕过它。分类决定架构，而不是反过来。