深入浅出 MCP 系列教程（五）：工程落地与选型

Posted on

本系列完结篇。前四篇覆盖了协议规范、核心原语、传输层和进阶能力，本篇从”协议是什么”转向”怎么在生产环境稳定跑起来”：SDK 上手、安全模型、网关架构、可观测性、限流熔断，最后横向对比 Function Calling、Agent 框架、A2A，给出选型决策与反模式清单。

一、SDK 选型与基础代码骨架

MCP 本身只是协议，手写 JSON-RPC、流分割、重连非常容易出错。生产优先使用官方/社区 SDK，不要裸写协议层。

1.1 主流 SDK

  • TypeScript / Node.js：@modelcontextprotocol/sdk（官方，生态最好，更新最快）
  • Python：mcp（官方），适合数据、脚本、AI 工具快速封装
  • Go：github.com/modelcontextprotocol/go-sdk，适合高性能网关、常驻服务
  • Rust：官方 Rust SDK，适合资源占用低、安全敏感的独立 Server
  • C# / Java：社区第三方实现，版本跟进略慢，适合传统后端集成

原则：业务语言优先官方 SDK；网关、代理、高吞吐组件优先 Go / Rust。

1.2 Node.js 最简 stdio Server 骨架

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
  ListToolsRequestSchema,
  CallToolRequestSchema,
} from "@modelcontextprotocol/sdk/types.js";

const server = new Server(
  { name: "demo-server", version: "1.0.0" },
  { capabilities: { tools: {} } }
);

server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: "echo",
      description: "回显文本",
      inputSchema: {
        type: "object",
        properties: { text: { type: "string" } },
        required: ["text"],
      },
    },
  ],
}));

server.setRequestHandler(CallToolRequestSchema, async (req) => {
  const text = req.params.arguments.text as string;
  return { content: [{ type: "text", text }] };
});

const transport = new StdioServerTransport();
await server.connect(transport);

要点：

  • SDK 自动处理 JSONL 分割、JSON-RPC id 路由、握手、capability 协商；
  • 业务只需要注册各类请求 handler；
  • 如果开启 sampling、roots、resources，在初始化 capabilities 里声明，再注册对应 handler。

1.3 Streamable HTTP 服务骨架要点

HTTP 版本拆成两块：SSE 下行流管理（维护每个 sessionId 对应的 SSE 连接、消息入队）和 POST 上行接收（校验 session、鉴权、投递消息到对应会话）。SDK 一般提供独立的 StreamableHttpTransport，内置会话存储、SSE 推送。

自建 HTTP MCP 最大坑：SSE 断开后消息队列堆积，必须设置单会话消息上限、过期丢弃。

二、完整安全模型

MCP 的安全不是单点，是分层防御，很多人只依赖 Roots，这远远不够。

2.1 分层安全框架

  1. 传输层安全

    • stdio：本机信任边界；不要用 stdio 加载来源不明的第三方 Server；
    • Streamable HTTP：必须 HTTPS，禁止裸 HTTP；使用 Bearer / mTLS，不要把密钥放 query；
    • 代理侧：禁止开放公网无鉴权 MCP 端点。

  2. 身份与鉴权层

    • 每个用户独立会话；鉴权信息和 sessionId 解耦；
    • 多租户场景：所有后端操作带上用户身份上下文，不能共用一个数据库账号；
    • 权限最小化：同一个 MCP Server，不同用户看到不同工具、不同 roots。

  3. Roots（资源沙箱）

    • 只管控 resources/read；它是白名单，不是系统沙箱；
    • 校验逻辑：严格 URI 前缀校验，不能简单字符串匹配（规避 file:///work../etc/ 这类逃逸）；
    • 推荐 Host 侧也做一层同样的 URI 校验，双重防御。

  4. 工具权限隔离（最容易缺失）
    Roots 管读资源；工具的写、删除、执行、SQL、接口调用需要单独权限系统：

    • 工具白名单：用户 A 允许 read_file，不允许 delete_file；
    • 参数校验：高危工具增加参数正则、黑名单；
    • 人工审批策略：匹配高危工具 + 敏感参数，强制弹窗确认；
    • 审批记录永久留存。

  5. Sampling 安全边界

    • Server 提交的 sampling 请求属于不可信输入，统一经过 Host 的内容安全审核；
    • 可配置策略：某些 Server 禁止 sampling，或必须人工审批；
    • Token 配额按用户隔离，防止某个 Server 无限消耗模型额度。

  6. 提示注入防护

    • 外部资源、工具返回内容在送入 LLM 时，做边界封装；
    • 不把外部原始文本直接和系统提示拼接；
    • 高安全场景使用分隔标记、独立消息块、内容摘要替代原文。

2.2 高危操作黑名单（生产建议）

任何下面这类工具，默认不开放，开启必须强审批：

  • 文件删除、覆盖、批量修改；
  • 任意 shell 执行；
  • 无限制 SQL 执行；
  • 发送邮件、短信、企业消息；
  • 访问内部凭证、密钥仓库；
  • 公网出网扫描。

2.3 供应链风险

MCP 生态是”Host 加载外部 Server”，这是核心攻击面：

  • 第三方 MCP Server 拥有你下发的 roots、工具权限；
  • 恶意 Server 可以通过 sampling 诱导 Host 模型泄露信息；
  • 企业内部：维护 MCP Server 准入清单，禁止用户随意加载外部 Server。

三、网关架构（企业主流落地形态）

3.1 网关职责

  • 统一接入：对外只暴露一个 Streamable HTTP 端点；
  • 鉴权 & SSO：对接 OIDC、内部账号；
  • 路由：按请求、用户配置转发到对应的后端 MCP Server（stdio 子进程或远程 HTTP MCP）；
  • 能力聚合：合并多个后端的 tools / resources / prompts，对外统一返回；
  • 权限裁剪：根据用户权限过滤工具、裁剪 roots；
  • 审计、限流、熔断、日志集中采集；
  • 协议适配：后端是 stdio，对外暴露成 Streamable HTTP。

3.2 两种网关模式

  1. 透明代理模式：网关只转发消息，不解析业务原语。实现简单，但无法做工具粒度权限、聚合；
  2. 控制平面网关（智能网关）：网关完整解析 MCP 消息，可以在 tools/list 返回前过滤工具、在 tools/call 之前拦截审批、修改 roots 下发列表、合并多个后端能力集。企业生产首选，复杂度更高。

3.3 网关会话管理

网关侧持有 sessionId，一个网关会话可以绑定多个后端 MCP 会话，负责生命周期管理：

  • 用户登出：批量销毁所有后端会话、杀掉 stdio 子进程；
  • 闲置超时：回收连接、释放文件句柄、数据库连接；
  • 后端 Server 崩溃：网关感知，向上返回错误，可选自动重建后端会话。

3.4 部署拓扑示例

1
2
3
4
5
6
用户 Host（Claude Desktop / 自研 Agent）
        ↓ HTTPS（Streamable HTTP）
        MCP Gateway（鉴权、审计、路由、限流）
        ├─→ 内部 stdio MCP Server（文件、Git）
        ├─→ 远程 HTTP MCP Server（工单、知识库）
        └─→ 内部服务封装 MCP（运维、发布平台）

四、可观测性

MCP 是异步双向协议，链路追踪比普通 REST 更复杂。可观测分三块：结构化日志、指标、链路追踪。

4.1 结构化日志规范

每条日志至少包含：sessionId、user_id、requestId（JSON-RPC id）、method、耗时、状态、错误码、工具名称、URI（脱敏）。

区分几类日志：

  • 审计日志（不可篡改）：所有 tools/call、roots 变更、sampling 请求、审批结果；
  • 运行日志：info / warn / error，用于排障；
  • 访问日志：连接建立、断开、重连、鉴权失败。

不要直接把完整参数明文入库：密钥、敏感内容脱敏。

4.2 核心指标（Prometheus）

  • 连接指标：活跃会话数、新建会话、会话销毁、SSE 重连次数；
  • 请求指标：每个 method 的 QPS、成功/失败计数、P50/P95/P99 耗时；
  • 工具粒度：每个工具调用次数、失败率、平均耗时；
  • Sampling 指标：反向模型调用次数、token 消耗、拒绝次数；
  • 资源指标：resources/read 读取量、订阅数量；
  • 资源水位：子进程数量、消息队列堆积、内存。

告警重点：工具错误率突增、SSE 频繁重连、会话堆积不释放、sampling token 消耗突增、鉴权失败风暴。

4.3 链路追踪

MCP 是异步双向，一条链路可能跨 Host → Gateway → MCP Server → 下游服务，还可能反向 sampling 再回到 Host。方案：

  • 用自定义 header（traceparent，W3C trace）在 Streamable HTTP 上透传；
  • stdio 场景：通过环境变量注入 trace id；
  • 一条 tools/call 生成一条 trace；里面触发 sampling 作为子 span；
  • 进度通知、资源更新通知打上同一个 trace id，串联整个任务。

五、限流、熔断、背压、重试

MCP 双向异步，盲目重试很容易放大故障。

5.1 限流维度

  • 用户级：每个用户总 QPS、sampling token 上限、并发工具调用数；
  • 会话级：单会话消息速率，防止单会话打满服务；
  • 工具级：高危工具单独限流；
  • 网关全局限流。

5.2 熔断

针对后端 MCP Server：连续报错超过阈值就熔断、快速失败；熔断状态下不再转发请求，返回友好错误；配合熔断窗口、半开探测。适合场景：后端数据库挂掉、文件服务宕机、第三方接口超时。

5.3 背压（非常关键）

异步通道天然存在背压问题：发送速度 > 处理速度，消息队列无限堆积，OOM。策略：

  • 每个会话设置消息队列最大长度；
  • 队列满时：拒绝新消息或丢弃旧消息；
  • 长任务配合 progress 通知，同时控制并发；
  • stdio：注意进程管道缓冲区阻塞，Node / Python 尤其容易卡住。

5.4 重试策略

  • JSON-RPC 请求：只有幂等操作才允许重试；删除、发送消息这类非幂等禁止自动重试；
  • 网络断开重连：SSE 按服务端 retry 间隔指数退避；
  • 业务失败（权限不足、参数错误）不重试；只有连接类、临时超时可以重试；
  • 重试必须带最大次数，防止风暴。

六、部署与测试

6.1 部署要点

stdio：进程托管（systemd / supervisor）；监听子进程退出回收僵尸进程；版本升级重启进程即重启会话；用 cgroup 限制 CPU、内存。

Streamable HTTP：容器化部署依赖外部会话存储（Redis）保存会话上下文；不要存在容器本地内存，否则扩缩容、滚动发布会话丢失；如果会话在 Redis，负载均衡不需要粘性会话；如果会话在进程内存，必须会话亲和，生产不推荐。

6.2 测试体系（四层）

  1. 单元测试：单独测试每个 tool、resource、prompt handler；用内存 transport 隔离；
  2. 协议一致性测试：校验握手、capability 协商、消息格式、错误码、通知语义；官方提供部分 conformance test 套件，可接入 CI；
  3. 集成测试：启动真实 transport，覆盖正常调用、参数错误、越界 roots、sampling 往返、SSE 断开重连、工具列表动态变更；
  4. 混沌测试（生产前）：随机断开 SSE、杀掉子进程、注入网络延迟丢包、超限大报文，验证不雪崩。

不要只测”成功路径”；MCP 生产故障大多出在异步、断连、反向调用、权限逃逸。

6.3 排障清单（高频故障）

  1. 握手卡住、JSON parse error：stdio 场景 Server 在 stdout 打印日志；改成 stderr 或协议内 logging/message；
  2. SSE 连上但收不到返回：检查 POST 是否携带正确 sessionId；SSE 是否被代理截断；消息队列是否满了；
  3. roots 下发了仍可读取越界文件：URI 校验实现用了简单 startsWith，存在逃逸；改用 URI 标准库解析后校验；
  4. sampling 请求发出去没有响应：Host 没在 initialize 声明 sampling；或 Host 拦截拒绝没有返回；
  5. 工具列表不更新：Host 没监听 tools/list_changed、没有主动刷新 tools/list；
  6. 会话越积越多，内存泄漏：没有闲置超时；SSE 断开会话没清理；
  7. 重连之后订阅失效：订阅是会话级，重连后需重新 resources/subscribe；
  8. 高并发下请求卡死：背压缺失、无队列上限、同步阻塞 handler 吃掉事件循环。

七、选型对比：MCP 在 AI 生态中的定位

7.1 MCP vs OpenAI Function Calling

二者不是替代关系，而是层级完全不同：

  • Function Calling 是 LLM 厂商的请求参数格式，嵌入在模型请求 payload 内部，绑定模型调用链路；
  • MCP 是独立于模型的双向会话协议，有独立的会话、订阅、反向采样、权限、生命周期。
维度 Function Calling MCP
绑定关系 和模型强绑定 和模型完全解耦
会话状态 无原生会话 原生长会话、订阅、动态能力变更
双向性 单向：LLM → 工具 双向：支持 Sampling
能力发现 每次请求携带或静态配置 运行时动态发现、动态刷新
权限沙箱 没有内置规范 内置 Roots
跨客户端复用 不同客户端需各自封装 同一个 Server 可被多个 Host 接入

选型：简单、一次性、短流程的工具调用优先 Function Calling；工具服务要被多个客户端复用、需要长期资源订阅、需要反向采样、需要统一权限审计 → MCP。

最常见组合：MCP 做工具服务层，Function Calling 做模型调用层——Host 把 MCP tools/list 转换为 function schema 发给兼容 OpenAI 接口的模型。

7.2 MCP vs Agent 框架（LangGraph、AutoGen、CrewAI）

Agent 框架解决编排、记忆、规划、多轮推理；MCP 解决标准化工具接入层。

  • 只用框架、不用 MCP：上手快，但工具和编排代码耦合，新增工具要改代码发版本，很难被其他 Agent 复用；
  • 框架 + MCP：编排逻辑稳定，工具动态插拔，同一工具集可同时服务网页 Agent、桌面客户端、后台批处理；代价是多一层协议和运维体系。

反模式：把复杂 Agent 编排逻辑写在 MCP Server 内部。MCP Server 应该是能力提供者，不是规划器。

7.3 MCP vs A2A（Agent2Agent）

一句话记忆：

  • A2A：Agent 找另一个 Agent 干活（任务委派、状态同步）；
  • MCP：Agent 找工具/系统干活（能力暴露）。

组合架构（联邦 Agent）：

1
2
3
4
主 Agent（Host）
 ├─ MCP → 文件、数据库、业务系统（工具）
 └─ A2A → 子 Agent（另一个独立 Agent）
      └─ 子 Agent 内部再通过 MCP 调用它自己的工具

二者没有竞争关系，大型多 Agent 系统一般同时存在。如果只是让 Agent 读写文件、查内部系统，没有跨 Agent 委派，只用 MCP 就足够。

八、选型决策树与反模式

8.1 决策树

  1. 只是给单一模型网关提供简单工具？→ 优先 Function Calling，轻量够用；
  2. 工具需要被多个客户端复用？→ 倾向 MCP；
  3. 有长生命周期资源（文件仓库、订阅变更）？→ 倾向 MCP；
  4. 需要工具服务反向请求模型做子推理？→ MCP 的 Sampling 是核心卖点；
  5. 是 Agent 和另一个独立 Agent 委派任务？→ 用 A2A，而不是把 Agent 封装成 MCP 工具；
  6. 只在一个编排框架内部使用、不对外暴露工具？→ 可以不引入 MCP，直接本地函数；
  7. 决定上 MCP 后：个人桌面、本地开发 → stdio；内网共享、多用户 → Streamable HTTP + 网关；跨部门联邦 → 多层网关 + 能力注册表。

核心原则：MCP 不是默认答案，它是为「能力可独立部署、可共享、有会话和资源生命周期」而设计的方案。

8.2 经典权衡点

  1. 能力聚合 vs 透明转发网关：透明转发简单但做不到工具粒度权限；智能聚合网关能力强，但要完整解析 MCP 语义，兼容性风险更高；
  2. 本地 stdio 隔离 vs 远程 HTTP 共享：stdio 隔离性好但不能跨机器；HTTP 共享方便但必须处理鉴权、会话存储、网络故障；
  3. Server 内做业务逻辑，还是推到 Host：MCP Server 适合封装外部系统；复杂规划、多轮判断、记忆放在 Host/编排层。Server 逻辑太重会变成隐藏的 Agent，难以审计追踪。

8.3 高频设计反模式

反模式 问题 正解
把完整 Agent 封装成一个 MCP Tool 两层会话状态叠加、生命周期冲突、审计颗粒度变粗 Agent 作为 Host，MCP 调用底层系统；跨 Agent 委派走 A2A
用 MCP 替代普通同步 API 协议开销、会话管理全是额外负担 简单无状态查询直接用 HTTP API
Roots 当成万能安全边界 工具可以绕过 Roots 写文件、执行命令 Roots 只保护 resources/read；工具权限独立管控
在 MCP Server 里硬编码模型 Key 密钥分散、配额审核难统一 走 Sampling，模型收敛在 Host
无限缓存工具列表不刷新 动态变更后客户端看不到最新工具 监听 tools/list_changed 通知并刷新
自定义扩展不用 x- 前缀 未来官方升级直接冲突 私有接口必须 x- 前缀
业务状态存在 Server 本地内存 多实例部署负载均衡后状态丢失 会话外部持久化（Redis）

九、系列总结：MCP 的核心思想

回顾整个系列：

  1. 协议基础：角色、JSON-RPC、会话生命周期、initialize、capability 协商；
  2. 三大原语：Tools（执行动作）、Resources（只读资源）、Prompts（可复用提示模板）；
  3. 传输层：stdio（本地）、Streamable HTTP（远程，POST + SSE）；
  4. 进阶能力：Sampling（反向模型调用）、Roots（资源沙箱）、通知体系、错误、扩展规范；
  5. 生产工程：SDK、分层安全、网关、可观测、限流熔断、部署测试排障；
  6. 选型生态：对比 Function Calling、Agent 框架、A2A；决策树、反模式。

MCP 的核心思想一句话概括：

将外部系统的能力，封装成一套独立于模型、独立于 Agent 编排、可共享、带会话与权限语义的标准化服务。

它不是一个做 Agent 的框架，而是让 Agent 安全、标准地接入真实世界系统的一层基础设施——AI 能力接口的”USB-C”。

系列文章导航

  1. 深入浅出 MCP 系列教程（一）：协议基础与架构设计
  2. 深入浅出 MCP 系列教程（二）：三大核心原语实战
  3. 深入浅出 MCP 系列教程（三）：传输层实战
  4. 深入浅出 MCP 系列教程（四）：进阶能力
  5. 深入浅出 MCP 系列教程（五）：工程落地与选型（本篇）