企业官网建设流程全解析

1. 从一次多工具调用的崩溃说起

上周帮一个做智能客服的朋友排查问题，他们的 Agent 在单 Server 场景下跑得好好的，一接入第二个 MCP Server 就开始出现工具调用串台、参数丢失、响应超时。日志里最诡异的一条是：明明请求的是订单查询工具，返回的却是天气接口的数据。这不是玄学，是典型的多 Server 场景下工具命名空间冲突加上握手阶段能力协商不完整导致的。

MCP（Model Context Protocol）这两年在 AI Agent 圈子里热度飙升，从 IDE 插件到设计工具再到数据库客户端，几乎每个想"让 AI 真的下地干活"的产品都在往 MCP 上靠。但大多数人停留在"能连上就行"的阶段，一旦涉及多个 Server 协同、LangGraph 编排、流式输出这些真实生产场景，坑就一个接一个冒出来。这篇内容我打算把 MCP 从协议握手到 LangGraph 多 Server 调用的完整链路拆开讲，包括握手阶段到底交换了什么、多 Server 的工具怎么隔离、LangGraph 里怎么编排、以及我在实测中踩过的那些文档里不会写的坑。

适合谁看？如果你已经写过简单的 MCP Client 或 Server，想搞清楚多 Server 场景下的工程化问题，这篇对你有用。如果你还没接触过 MCP，建议先补一下基础概念再回来，因为下面会直接进入协议细节和代码层面。

2. MCP 协议握手阶段到底交换了什么

2.1 握手不是"打个招呼"，是能力清单的互相交底

很多人以为 MCP 的握手就是建立连接确认存活，实际上initialize请求和响应里携带的信息量远超想象。Client 发给 Server 的initialize请求包含三个核心字段：protocolVersion、capabilities、clientInfo。Server 返回的initialize响应则包含protocolVersion、capabilities、serverInfo，以及可选的instructions。

这里的关键在于capabilities字段。Client 端声明自己支持什么，比如roots（文件系统根目录列表变更通知）、sampling（允许 Server 请求 Client 执行 LLM 采样）。Server 端声明自己提供什么，比如tools（工具列表变更通知）、resources（资源订阅）、prompts（提示模板）。这个协商过程决定了后续通信中哪些消息类型是合法的。

我见过最常见的错误是：Client 没有声明sampling能力，但 Server 在某个工具执行过程中发起了sampling/createMessage请求，结果直接报错断开。这不是 bug，是握手阶段就没谈拢。

// Client 发起 initialize 请求 { "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": { "protocolVersion": "2024-11-05", "capabilities": { "roots": { "listChanged": true }, "sampling": {} }, "clientInfo": { "name": "my-langgraph-client", "version": "1.0.0" } } }

// Server 返回 initialize 响应 { "jsonrpc": "2.0", "id": 1, "result": { "protocolVersion": "2024-11-05", "capabilities": { "tools": { "listChanged": true }, "resources": { "subscribe": true, "listChanged": true } }, "serverInfo": { "name": "order-service-mcp", "version": "2.1.0" }, "instructions": "本 Server 提供订单查询、物流跟踪、退款申请三类工具" } }

2.2 协议版本不匹配时的降级策略

protocolVersion用的是日期字符串格式，比如2024-11-05。如果 Client 和 Server 声明的版本不一致，规范建议 Client 断开连接。但实际工程中，很多 Server 实现会选择兼容旧版本，这时候就需要在 Client 侧做降级处理。

我的做法是在 Client 初始化时维护一个支持版本列表，按优先级排序。发起握手时用最高版本，如果 Server 返回的版本不在支持列表里，就回退到次高版本重试。这个逻辑在 LangGraph 的多 Server 场景下尤其重要，因为你可能同时连接一个最新版的官方 Server 和一个半年没更新的第三方 Server。

SUPPORTED_VERSIONS = ["2024-11-05", "2024-10-07", "2024-09-01"] async def initialize_with_fallback(session, client_capabilities): for version in SUPPORTED_VERSIONS: try: result = await session.initialize( protocolVersion=version, capabilities=client_capabilities, clientInfo={"name": "langgraph-mcp-client", "version": "1.0.0"} ) if result.protocolVersion in SUPPORTED_VERSIONS: return result except Exception as e: continue raise RuntimeError("无法与 Server 协商出兼容的协议版本")

2.3 握手完成后的 initialized 通知不能省

握手成功后，Client 必须发送notifications/initialized通知，告诉 Server "我准备好了，可以开始正常通信了"。这个通知没有响应，是单向的。很多简易实现会漏掉这一步，导致某些严格的 Server 拒绝后续的tools/list请求。

注意：initialized通知必须在收到initialize响应之后、发送任何其他请求之前发出。顺序错了，部分 Server 会直接关闭连接。

3. 多 Server 场景下的工具命名冲突与隔离方案

3.1 为什么两个 Server 的工具会"串台"

回到开头那个案例。他们的两个 MCP Server 分别提供订单查询和天气查询，但两个 Server 都定义了一个叫query的工具。LangGraph 在构建工具节点时，把两个query都注册进了同一个工具列表，LLM 在选择工具时看到两个同名工具，随机选了一个，参数结构还不一样，于是出现了"订单查询返回天气数据"的诡异现象。

MCP 规范本身没有强制要求工具名全局唯一，因为规范假设的是 Client 与单个 Server 之间的通信。但 LangGraph 作为编排层，需要把多个 Server 的工具聚合到一个可调用的工具集里，这时候命名冲突就成了必须解决的问题。

3.2 命名空间前缀：简单但有效的隔离手段

最直接的方案是给每个 Server 的工具加前缀。比如订单 Server 的工具变成order_query、order_track，天气 Server 的变成weather_query、weather_forecast。这个前缀在 LangGraph 的工具注册阶段加上，在调用时再剥离，映射回原始工具名。

class NamespacedMCPTool: def __init__(self, server_name, original_tool, session): self.server_name = server_name self.original_name = original_tool.name self.name = f"{server_name}__{original_tool.name}" self.description = f"[{server_name}] {original_tool.description}" self.input_schema = original_tool.inputSchema self.session = session async def ainvoke(self, args): # 调用时使用原始工具名 return await self.session.call_tool(self.original_name, args)

用双下划线做分隔符而不是单下划线，是因为很多工具名本身就含单下划线，双下划线在视觉上更容易区分命名空间和工具名。这个细节在调试时能省不少事。

3.3 工具描述里的 Server 上下文注入

光改名字还不够。LLM 选择工具时主要看描述，如果两个 Server 都有"查询"类工具，描述里不体现差异，LLM 还是可能选错。我的做法是在工具描述前面加上 Server 的领域标签，比如[订单系统] 根据订单号查询订单详情和[天气服务] 根据城市名查询当前天气。

更进一步，可以在 Server 的instructions字段里写清楚这个 Server 的职责边界，然后在 Client 侧把这段说明注入到系统提示词里。这样 LLM 在做工具选择时，不仅能看到单个工具的描述，还能理解每个 Server 的整体定位。

3.4 工具数量爆炸时的分组路由策略

当接入的 Server 超过三四个，工具总数可能突破五十甚至上百。这时候把所有工具一股脑塞给 LLM，不仅 token 消耗大，选择准确率也会下降。我试过一个折中方案：先用一个轻量级的路由节点判断用户意图属于哪个 Server 领域，然后只加载那个 Server 的工具列表。

这个路由节点本身可以用一个简单的分类提示词实现，不需要复杂的模型。实测下来，在工具数量超过 40 个的场景下，分组路由能把工具选择准确率从 70% 左右提升到 90% 以上，同时每次请求的 token 消耗降低约 60%。

4. LangGraph 中编排多 MCP Server 的实战结构

4.1 为什么选 LangGraph 而不是简单的链式调用

多 Server 场景下，用户的一个请求可能需要跨 Server 协作。比如"帮我查一下上周买的那个订单到哪了，如果延迟了就看看目的地天气"，这需要先调订单 Server 查订单和物流，再根据物流状态决定是否调天气 Server。这种条件分支和状态传递，用简单的链式调用写起来会非常别扭。

LangGraph 的核心优势在于它把 Agent 的执行过程建模成状态图，每个节点可以读写共享状态，边可以带条件。这正好匹配多 Server 协作的需求：每个 Server 的工具调用是一个节点，节点之间的跳转由 LLM 或预设规则决定。

4.2 状态设计：跨 Server 的数据怎么传递

LangGraph 的状态是一个 TypedDict，所有节点共享。在多 Server 场景下，状态设计要解决两个问题：一是不同 Server 返回的数据结构不同，怎么统一存放；二是工具调用的中间结果怎么传递给后续节点。

我的做法是在状态里放三个核心字段：messages（对话历史，用 LangGraph 的add_messagesreducer）、tool_results（按 Server 名分组的工具返回结果）、active_server（当前活跃的 Server，用于路由）。

from typing import Annotated, TypedDict from langgraph.graph.message import add_messages class MultiServerState(TypedDict): messages: Annotated[list, add_messages] tool_results: dict # {server_name: [results]} active_server: str | None next_action: str | None

tool_results用字典按 Server 分组，而不是平铺成一个列表，是为了后续节点能快速定位到某个 Server 的返回结果，不用遍历整个列表。这个设计在 Server 数量多的时候优势明显。

4.3 工具节点的动态构建

LangGraph 的ToolNode默认接收一个静态的工具列表。多 Server 场景下，工具列表是动态的，需要在运行时根据已连接的 Server 构建。我的做法是在图构建阶段先完成所有 Server 的握手和工具发现，然后把工具列表传给ToolNode。

async def build_multi_server_graph(servers_config): sessions = {} all_tools = [] for cfg in servers_config: session = await connect_and_initialize(cfg) sessions[cfg["name"]] = session tools = await session.list_tools() for tool in tools: all_tools.append(NamespacedMCPTool(cfg["name"], tool, session)) tool_node = ToolNode(all_tools) # ... 构建图的其他部分 return graph, sessions

这里有个坑：connect_and_initialize是异步的，如果 Server 数量多，串行连接会很慢。我改成用asyncio.gather并发连接，但要注意每个 Server 的连接超时时间要单独设置，不能用一个全局超时，否则一个慢 Server 会拖垮整个初始化过程。

4.4 条件边：根据工具返回结果决定下一步

多 Server 协作的精髓在条件边。比如订单查询工具返回"已发货"，条件边就路由到物流跟踪节点；返回"未发货"，路由到退款建议节点。这个判断逻辑可以写在条件函数里，也可以让 LLM 来决定。

def route_after_order_query(state: MultiServerState): last_result = state["tool_results"].get("order", [{}])[-1] status = last_result.get("status") if status == "shipped": return "track_logistics" elif status == "pending": return "suggest_refund" else: return "ask_user"

条件函数的返回值对应图中的边名称。这个设计让跨 Server 的流程控制变得非常清晰，每个分支的触发条件一目了然。

5. 流式输出与多 Server 响应的合并处理

5.1 MCP 的流式通知机制

MCP 支持通过notifications/tools/list_changed和资源订阅来实现服务端推送，但工具调用的结果本身默认是一次性返回的。如果你想让工具执行过程中的中间状态流式输出到前端，需要在 Server 侧实现进度通知，Client 侧监听notifications/progress。

这个机制在多 Server 场景下会变得复杂：多个 Server 可能同时发送进度通知，Client 需要根据progressToken区分是哪个请求的进度。我的做法是在发起工具调用时生成一个全局唯一的progressToken，并在状态里维护一个 token 到 Server 名的映射。

5.2 多 Server 响应的合并顺序问题

当 LangGraph 并行调用多个 Server 的工具时，返回顺序是不确定的。如果直接把结果按到达顺序推给前端，用户看到的可能是"天气结果先于订单结果出现"这种逻辑颠倒的输出。

解决方案是在状态里给每个工具调用分配一个序号，合并输出时按序号排序。LangGraph 的SendAPI 支持并行分发任务，但结果合并需要自己控制。我通常会在工具节点后面加一个聚合节点，等所有并行分支完成后统一排序输出。

提示：如果某个 Server 响应特别慢，不要无限等待。给每个工具调用设置独立的超时，超时的结果标记为timeout并继续后续流程，避免一个慢 Server 阻塞整个图。

5.3 流式输出到文件的工程实践

有些场景需要把 Agent 的完整执行过程流式写入文件，用于审计或回放。这里的关键是保证写入的顺序和完整性。我的做法是用一个异步队列作为缓冲区，所有 Server 的流式输出先入队，再由一个单独的写入协程按序出队写文件。

import asyncio import json class StreamWriter: def __init__(self, filepath): self.queue = asyncio.Queue() self.filepath = filepath self.task = None async def start(self): self.task = asyncio.create_task(self._write_loop()) async def _write_loop(self): with open(self.filepath, "a", encoding="utf-8") as f: while True: item = await self.queue.get() if item is None: break f.write(json.dumps(item, ensure_ascii=False) + "\n") f.flush() async def push(self, data): await self.queue.put(data)

这个模式在多个 Server 并发推送时特别有用，队列天然保证了写入的串行化，不会出现两个 Server 的日志交错写在同一行的情况。

6. 实测中踩过的坑与排查链路

6.1 工具调用参数被静默丢弃

有一次调试发现，LLM 明明生成了完整的工具调用参数，但 Server 收到的参数少了一个字段。排查链路是这样的：先看 LangGraph 的ToolNode日志，确认参数在进入节点时是完整的；再看 MCP Client 的发送日志，发现call_tool请求里的arguments确实少了一个字段。

根因是NamespacedMCPTool的ainvoke方法里，我用了args直接透传，但 LangGraph 传给ainvoke的参数结构是{"name": ..., "args": {...}, "id": ..., "type": "tool_call"}，我误把整个字典当成了工具参数。修复方法是取args["args"]再传给call_tool。

这个坑的教训是：LangGraph 的工具调用参数结构和 MCP 的call_tool参数结构不是一回事，中间需要做一次转换。文档里不会写这个，因为它是两个框架的边界问题。

6.2 Server 断连后的状态恢复

MCP 连接是长连接，网络抖动或 Server 重启都会导致断连。LangGraph 的图执行到一半断连，状态就卡住了。我的处理方案是在工具节点外面包一层重试逻辑，检测到连接错误时先尝试重连 Server，重连成功后重新执行当前工具调用。

但重试有个前提：工具调用必须是幂等的。查询类工具天然幂等，重试没问题；但下单、支付这类写操作，重试可能导致重复执行。对于非幂等工具，我的做法是在状态里记录一个executed_tools集合，重试前先检查这个工具是否已经执行过，避免重复。

6.3 多 Server 并发时的连接池耗尽

当 LangGraph 并行调用多个 Server 时，如果每个调用都新建一个 MCP 连接，很快就会耗尽连接池。正确做法是在初始化阶段建立好所有 Server 的连接，后续调用复用这些连接。MCP 的ClientSession本身是支持并发请求的，不需要为每个请求新建 session。

但要注意，某些 Server 实现不支持并发请求，收到第二个请求时会阻塞直到第一个完成。这种情况下需要在 Client 侧加一个信号量，限制对单个 Server 的并发请求数。

6.4 排查多 Server 问题的通用思路

踩了这么多坑之后，我总结了一个排查顺序：先确认单个 Server 单独调用是否正常，排除 Server 本身的问题；再确认 LangGraph 的工具注册列表里工具名和描述是否正确，排除命名冲突；然后看 MCP 层的请求和响应日志，确认协议层面的数据是否完整；最后看状态在节点间的传递是否符合预期。

这个顺序的核心逻辑是从外到内、从单到多。很多问题在单 Server 场景下不会暴露，一旦多 Server 并发就冒出来，所以隔离变量是关键。

7. 几个容易被忽略的工程细节

7.1 Server 的 instructions 字段要充分利用

initialize响应里的instructions字段是 Server 向 Client 自我介绍的最佳位置。我通常会在里面写清楚这个 Server 的职责范围、工具之间的调用顺序建议、以及常见的参数格式说明。Client 侧把这段说明注入到系统提示词里，能显著提升 LLM 的工具选择准确率。

比如订单 Server 的 instructions 可以写："本 Server 提供订单相关工具。查询订单前需要先通过order_search获取订单号，再用order_detail查询详情。日期格式统一为 YYYY-MM-DD。" 这种上下文信息比单个工具的描述更有全局指导意义。

7.2 工具列表变更的动态处理

MCP 支持notifications/tools/list_changed通知，Server 可以在运行时动态增删工具。Client 收到这个通知后，需要重新调用tools/list获取最新列表，并更新 LangGraph 的工具节点。

这个机制在 Server 热更新时很有用，但实现时要注意：更新工具列表不能影响正在执行中的图。我的做法是用一个版本号标记工具列表，图执行时锁定当前版本，新版本在下一个请求周期生效。

7.3 日志与可观测性

多 Server 场景下，日志是排查问题的生命线。我建议在三个层面加日志：MCP 协议层记录所有请求和响应（注意脱敏）、LangGraph 节点层记录状态变化、工具调用层记录参数和结果摘要。

日志格式要统一，每条日志带上server_name、tool_name、request_id三个字段，方便过滤和关联。用request_id把一次用户请求涉及的所有 Server 调用串起来，排查跨 Server 问题时能快速定位。

7.4 超时与重试的参数选择

超时时间不能拍脑袋定。我的经验值是：握手阶段 5 秒，工具列表获取 3 秒，工具调用根据工具类型区分——查询类 10 秒，写操作 30 秒。重试次数最多 2 次，且只对幂等工具重试。重试间隔用指数退避，初始 500 毫秒，倍数 2。

这些参数不是固定的，要根据实际 Server 的响应延迟分布来调整。建议先在测试环境跑一批请求，统计 P95 和 P99 延迟，再据此设置超时阈值。

8. 关于多 Server 编排的一点个人体会

从单 Server 到多 Server，表面上是数量变化，实际上是工程复杂度的跃升。单 Server 时你可以忽略命名冲突、连接管理、状态隔离这些问题，多 Server 时它们全都会变成必须解决的硬问题。

我现在的做法是尽量让每个 Server 的职责边界清晰，工具命名带领域前缀，描述里写清楚适用场景。LangGraph 的图结构也按 Server 划分节点，跨 Server 的协作通过条件边显式表达，而不是让 LLM 自由发挥。这样虽然前期设计成本高一些，但后期调试和维护省心很多。

另外一点体会是，MCP 协议本身还在演进，不同 Server 实现的完整度参差不齐。接入新 Server 时，先花十分钟把它的initialize响应和tools/list结果看一遍，比直接跑起来再排查问题效率高得多。握手阶段暴露的信息，往往能提前告诉你这个 Server 值不值得接。