去年年底我接手了公司内部 Agent 平台的一次改造需求很明确把原来写死在代码里的几十个函数调用换成基于 MCP 协议的工具接入。一开始我以为这事很简单——MCP 嘛无非是给大模型加一个通用外设接口拿到工具列表直接调就是了。结果真正在 LangGraph 里把多个 MCP Server 串起来的时候整个人都麻了握手阶段报协议版本不兼容、stdio 子进程莫名其妙退出、两个 Server 的同名工具互相覆盖还有一个更诡异的——并行分支调用工具结果居然串了台。这篇文章就把我从协议握手到 LangGraph 多 Server 调用的完整实践记录整理出来包括踩坑的排查思路。适合正在用 LangGraph、打算把 MCP 工具批量接入 Agent 工作流的开发者也适合那些已经被 MCP 握手错误折磨过、想搞清楚底层到底发生什么的同学。1. 从一次实际集成说起MCP 协议握手到底在握什么1.1 为什么说 MCP 不是又一个 HTTP 接口很多第一次接触 MCP 的人会习惯性地把它理解成给大模型调用的一套 REST API这个理解不能说全错但会严重误导后续的排障方向。MCP 底层确实经常跑在 HTTP 上但它本质上是基于 JSON-RPC 2.0 的消息协议走的是双向 message 交换不是请求-响应-结束的资源式访问。传输层可以挂 stdio本地子进程也可以挂 streamable HTTP远程服务但上层语义完全一致客户端和服务端建立会话、协商能力、按方法名调用工具。我常用的一个类比是REST API 像是你去便利店买东西问一句拿一件MCP 则更像是两边先签了一份合作意向书然后建立一条双向通道之后可以随时按约定好的方法互相发消息。这条通道建不建得起来关键就在握手阶段。1.2 报文级拆解一次完整的 initialize 握手MCP 的握手流程比很多人想象的更笨没有 OAuth 那种复杂跳转也没有 TLS 加持下的多次往返核心就是三条消息。我用一个实际抓到的报文来拆解大家感受一下。客户端首先发送 initialize 请求-- {jsonrpc:2.0,id:1,method:initialize,params:{ protocolVersion:2025-03-26, capabilities:{ roots:{listChanged:true}, sampling:{} }, clientInfo:{name:my-agent,version:0.1.0} }}服务端收到后返回自己的能力清单-- {jsonrpc:2.0,id:1,result:{ protocolVersion:2025-03-26, capabilities:{ tools:{}, resources:{}, prompts:{} }, serverInfo:{name:math-server,version:1.0.0} }}然后客户端再补一条 notification-- {jsonrpc:2.0,method:notifications/initialized}注意这条消息没有 id因为它是通知类型不需要响应。三条消息走完这个会话才算激活。之后才能发 tools/list、tools/call 这类正常业务请求-- {jsonrpc:2.0,id:2,method:tools/list} -- {jsonrpc:2.0,id:2,result:{tools:[{name:add,description:add two numbers,inputSchema:{...}}]}}如果你用官方 Python SDK这些细节都被封装掉了。比如下面这段from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client server_params StdioServerParameters( commandnpx, args[-y, modelcontextprotocol/server-filesystem, /tmp] ) async with stdio_client(server_params) as (read, write): async with ClientSession(read, write) as session: init_result await session.initialize() print(init_result.protocol_version) print(init_result.server_info) tools await session.list_tools() result await session.call_tool(read_file, {path: /tmp/a.txt})但封装归封装你在 LangGraph 里接多 Server 时碰到的超时、版本不兼容、Server disconnected本质上都是上面这段握手中途卡住了。知道现在卡在哪一步排查速度完全不一样。1.3 版本协商与能力清单握手背后的契约握手阶段最容易被忽略却又最致命的地方是 protocolVersion 协商。MCP 的协议版本不是出来就完事了客户端会在 initialize 里声明自己支持的版本服务端要么接受这个版本要么拒绝。如果服务端比较老它还可能出现直接不认新版本的情况导致 initialize 直接异常。我碰到过旧版 npx 包的 Server它只支持 2024-11-05 这个版本但我的 SDK 默认发的是 2025-03-26握手阶段就炸了。这个坑后面第 4 章详细展开这里先强调一个概念协议版本协商是握手契约的一部分不是随便填的字符串。还有一个容易忽略的点是 capabilities 协商。服务端在 initialize 响应里会返回它支持的能力域tools、resources、prompts、logging 等。如果你的代码假设所有 Server 都支持 tools但某个 Server 只暴露了 resources那后续 tools/list 就会返回空数组。这种问题在集成测试阶段很容易被当成Server 没配好而误判实际上人家只是没在那个域里工作。2. LangGraph 中接入 MCP Server 的三种姿势2.1 姿势一在 Node 内部直接操作 SDK适合固定流程最朴素的接法是在 LangGraph 的某个 Node 内部直接操作 MCP 的 ClientSession。这个方案适合你明确知道这一步就是调用某个工具拿到结果不需要大模型做工具选择的场景。比如定时汇总文件内容、拉取某个 Server 的状态。代码大致长这样async def fetch_node(state): server_params StdioServerParameters( commandnpx, args[-y, modelcontextprotocol/server-filesystem, /tmp] ) async with stdio_client(server_params) as (read, write): async with ClientSession(read, write) as session: await session.initialize() result await session.call_tool( read_file, {path: state[target_path]} ) return {content: result.content}直来直去依赖少。但缺点很明显每次调用都新建连接、自己管生命周期、LLM 无法介入工具选择一旦工具数量涨上去代码会变得又臭又长。所以我在实际项目里只用它做调度节点内部的一个固定动作比如用户提问前先抓一批背景数据。2.2 姿势二langchain-mcp-adapters 批量转工具适合 ReAct 循环如果你走的是 LangGraph 经典的 ReAct 模式——LLM 根据用户问题决定调哪个工具、ToolNode 负责执行——那姿势二才是主流路径。langchain-mcp-adapters 能把 MCP 的 tool 转成 LangChain 的 BaseTool 格式然后直接丢给 ToolNode。from langchain_mcp_adapters.tools import load_mcp_tools from langchain_core.messages import AIMessage from langgraph.prebuilt import ToolNode # 假设 session 已经建立并 initialize 完成 tools await load_mcp_tools(session) tool_node ToolNode(tools)这样省去了大量手写转换。MCP 返回的内容结构TextContent、ImageContent、ResourceLink 等由 adapter 转换成 LangChain 能理解的消息格式。ReAct 循环拿到工具列表后会自动生成 tool_calls再交给 ToolNode 执行结果回填给模型节点。整个过程很顺也是我推荐给大多数团队的方案。2.3 姿势三自研 Async 工具封装适合定制化生产场景姿势二虽然方便但遇到多 Server 鉴权、超时控制、连接复用、流式进度推送这类需求时它不够灵活。这时候我会选择自己封装一个 Async 工具类把 MCP ClientSession 的完整生命周期放进工具内部管理。比如我要接一个需要动态 Token 的远程 Server我会这样包一层from langchain_core.tools import BaseTool from pydantic import BaseModel, Field class McpToolWrapper(BaseTool): name: str description: str args_schema: type[BaseModel] session_getter: callable tool_name: str async def _arun(self, **kwargs): session await self.session_getter() result await session.call_tool(self.tool_name, kwargs) return parse_mcp_result(result)session_getter 可以从全局连接池拿连接也可以创建新连接。好处是控制力强坏处是你要自己处理并发、重连、超时这些事。这个方案适合团队里有专门做基础设施的同事能把连接管理抽象好不然容易变成一个大泥球。2.4 三种姿势怎么选一张表说清楚方案上手成本控制力适用场景Node 内直接调 SDK低低固定流程不需要 LLM 选工具langchain-mcp-adapters 转工具中中ReAct 循环、多工具自动选择自研 Async 工具封装高高多 Server 鉴权、连接池、定制化生产我的建议是先二后三。先用 adapter 把端到端跑通确认业务真的需要更精细的控制再针对性地替换成自研封装。一上来就上自研方案通常会在封装连接管理这件事上浪费大量时间。3. 多 Server 调用连接生命周期与上下文隔离的工程化设计3.1 连接的生命周期怎么管不要把 ClientSession 存进 State多 Server 场景下第一个要面对的问题就是连接怎么管。我见过不少新手直接把 ClientSession 对象塞进 LangGraph 的 State 里然后发现 checkpointer 序列化直接崩溃或者恢复会话时连接早就失效了。原因很简单LangGraph 的 State 是要被持久化的而连接对象是运行时资源两者生命周期完全不同。正确的做法是State 里只存 Server 的配置和标识不存连接实例。连接的管理交给独立的 ClientManager 来处理。Manager 负责创建 Session、缓存连接、处理并发Graph 节点通过某个 key 从 Manager 里拿连接。class McpClientManager: def __init__(self): self._sessions: dict[str, ClientSession] {} async def get_session(self, server_name: str) - ClientSession: if server_name not in self._sessions: await self._connect(server_name) return self._sessions[server_name] async def _connect(self, server_name: str): # 根据配置创建 stdio_client / streamablehttp_client ...这样 State 里永远只有 server_name 和请求参数序列化不会出问题。3.2 MultiServerMCPClient 的批量注册路径如果你用的是 langchain-mcp-adapters好消息是社区已经提供了 MultiServerMCPClient 来简化多 Server 接入。它的思路就是你提供一份 Server 配置字典它帮你把每个 Server 的连接和工具都初始化好最后一次性返回所有工具。from langchain_mcp_adapters.client import MultiServerMCPClient servers_config { math: { transport: stdio, command: npx, args: [-y, modelcontextprotocol/server-math], }, fs: { transport: stdio, command: npx, args: [-y, modelcontextprotocol/server-filesystem, /tmp], }, remote_api: { transport: streamable-http, url: http://localhost:8000/mcp, headers: {Authorization: Bearer xxx}, }, } async with MultiServerMCPClient(servers_config) as client: tools await client.get_tools() tool_node ToolNode(tools)这段代码跑通后你的 LangGraph 里就同时拥有 math、fs、remote_api 这三个 Server 暴露出来的工具。实现层面它会为每个 Server 单独维护 ClientSession并在 get_tools 时按 Server 名前缀做区分。这个默认的命名隔离非常关键。如果没有它多个 Server 都暴露 read_file 这种常见工具名时后注册的就会把先注册的覆盖掉到时候你说不清工具到底是谁提供的。3.3 上下文隔离鉴权命名冲突与配置外置多 Server 的上下文隔离是我认为最容易被低估的问题。隔离指的是A Server 的鉴权头、B Server 的超时配置、C Server 的 base URL不能相互污染。工程上我会把这些配置全部外置不写死在代码里。# mcp_servers.yaml math: transport: stdio command: npx args: [-y, modelcontextprotocol/server-math] fs: transport: stdio command: npx args: [-y, modelcontextprotocol/server-filesystem, /tmp] remote_api: transport: streamable-http url: http://localhost:8000/mcp headers: Authorization: Bearer ${REMOTE_API_TOKEN}通过环境变量注入 Token既避免密钥入库也让换环境时只改配置不改代码。再配合上面 MultiServerMCPClient 的批量化接入加一个新 Server 的成本就只剩下在 yaml 里加一段配置。这也让整个 Agent 平台从一人写死的脚本变成了可插拔的工具接入系统。4. 三个真实踩坑的完整排查记录4.1 坑一握手阶段就失败问题出在协议版本现象用 LangGraph 接一个 math Server日志显示 initialize 阶段超时有时候直接抛异常。我一开始以为是网络问题重试了好几次都没用。排查链路先绕开 LangGraph用官方 SDK 单独写了个脚本连接同一个 Server复现同样的问题。然后把 Server 的 stderr 打出来看发现里面明确写着Unsupported protocol version。顺着这条线索去查包版本才知道这个 npx 包用的 MCP SDK 版本比较旧服务端只认 2024-11-05而我的 Client 默认发的是 2025-03-26。握手契约谈不拢后面一切都是空谈。修复要么升级 Server 侧的包版本要么在 Client 端显式指定旧协议版本。我当时选了升级 Server 侧因为新版本修了不少 bug。验证方法就是重新跑 initialize打印出协商成功的 protocolVersion。这个坑给我们的教训是MCP 协议版本不是兼容并包的Client 和 Server 必须在一个版本上达成共识。遇到握手失败先看版本号别急着查网络。4.2 坑二stdio 子进程静默退出工具列表看着正常却一调就挂现象某个基于 stdio 的 Server 在本地手动连接时完全正常工具列表也能拉到但进了 LangGraph 之后第一次调用就报Server disconnected而且整个进程像是凭空消失了一样没有报错。排查链路我第一反应是代码问题于是把错误堆栈完整打印出来发现 Session 层已经收到了 EOF。然后我手动在 shell 里执行了那个 Server 的启动命令发现 npx 需要临时下载包但 Agent 运行环境的网络权限受限下载超时导致子进程退出。另一个变种是 PATH 问题LangGraph 服务部署成 systemd 服务时PATH 和 cron 环境不一样找不到 node 和 npx子进程根本起不来。修复预先在构建阶段就把 npx 包拉好离线缓存启动命令里改用绝对路径确保任何运行环境下都找得到解释了。同时给 stdio_client 的连接加超时超时后明确报出子进程启动失败而不是挂在 EOF 上。这条排查链路的核心方法是把 Server 单独跑起来先把 Server 本身搞定再让它进 LangGraph。我后面每次接入新 Server 都会先写一个独立脚本验证连接通过之后才往图里挂。4.3 坑三并行分支共享连接工具结果居然串台了现象Graph 里有并行分支两个分支同时调用不同 Server 上的工具。结果 A 分支拿到的是 B Server 的返回值偶尔还出现请求超时、返回乱码。这个 bug 特别难复现因为分支里加了缓存或时序抖动就消失了。排查链路先检查是不是 State 数据被共享了发现不是。然后我在 ClientSession 外层加了日志打印每个 call_tool 请求的 id 和返回的 id发现同一个 Session 在极短时间内收到了两个并发的 call_tool 请求而底层 read loop 返回响应时没有可靠地把 request id 对应回各自的调用方。中间层处理 JSON-RPC 的时候串了。LangGraph 的 ToolNode 默认用 asyncio.gather 并发执行工具调用所以这个问题被放大了——多个工具调用会同时打到同一个 MCP ClientSession。修复控制并发。最直接的做法是给每个 Server 的连接上加一个 asyncio.Semaphore限制同一时刻只有一定数量的请求在途。另一个思路是每个分支都用独立的 Session不过这会增加连接数。我最后选了信号量方案因为实现改动最小而且符合大多数 Agent 场景下的真实并发需求。import asyncio class SemaphoreWrapper: def __init__(self, session: ClientSession, limit: int 4): self._session session self._sem asyncio.Semaphore(limit) async def call_tool(self, name: str, args: dict): async with self._sem: return await self._session.call_tool(name, args)4.4 排查完之后的固定自查清单踩过这些坑之后我把排查多 Server 问题时的检查顺序固定了下来每次接入新 Server 都按这个顺序过一遍先独立脚本连接 Server确认握手、工具列表、调用都正常。打印握手阶段的 protocolVersion确认 Client 和 Server 协议一致。检查 Server 的运行环境PATH、node/npx 版本、网络权限。检查是否有同名工具确认 MultiServerMCPClient 是否正确加了前缀。检查是否有并发调用共享同一个 Session必要时加信号量。最后再挂进 LangGraph确认 ToolNode 注册成功。这套检查表已经帮我解决了绝大多数的诡异问题。反过来说大部分问题在第一步独立脚本验证时就能暴露。5. 把多 Server 方案推向生产复用、鉴权与可观测5.1 连接复用与并发控制前面说过不要每次调用都新建连接但真要复用也要把并发控制一并考虑。多 Server 场景下我通常会给每个 Server 维护一个固定连接池池内每个连接带一个 Semaphore请求进来时选一个空闲连接执行。这样既保证了连接复用又不会把单个 Session 的并发打爆。在 LangGraph 里这就是一个比较标准的实现class McpConnectionPool: def __init__(self, server_name: str, pool_size: int 2, limit: int 4): self._conns [create_session(server_name) for _ in range(pool_size)] self._locks [asyncio.Semaphore(limit) for _ in range(pool_size)] async def call_tool(self, tool_name: str, args: dict): for i in range(len(self._conns)): if self._locks[i].locked(): continue async with self._locks[i]: return await self._conns[i].call_tool(tool_name, args) # 都忙就等待第一个 async with self._locks[0]: return await self._conns[0].call_tool(tool_name, args)这样的连接池在 Agent 进程生命周期内常驻为了配合 LangGraph 的状态恢复池对象要放在外部的全局容器里而不是 State 里。5.2 鉴权与动态 Token 刷新远程 MCP Server 往往需要鉴权。如果你用 streamable-http 传输Authorization 头通常要挂在每个请求上。最简单的做法是在配置里写死 Token但生产环境 Token 会过期那就得支持动态刷新。我的处理方式是在 ClientManager 里维护一个 token provider每次建立 Session 或请求前拉取最新的有效 Token。MCP 的 streamable HTTP 会创建会话Token 过期后需要重新连接并重新握手所以我会把Token 过期导致 401这个错误映射成重建 Session的信号让上层自动重连。5.3 健康检查、指标和日志生产环境里Agent 平台要对接的 Server 越来越多健康检查就变得很重要。我的做法是维护一个定时任务定期对每个 Server 调用一次轻量方法比如 tools/list确认它是活着的。再配合每个工具的调用耗时、成功率和错误码做成简单的 Prometheus 指标。日志方面强烈建议在调试阶段把 JSON-RPC 报文打出来。你可以给 ClientSession 包一层日志中间件async def logged_call_tool(session, name, args): logger.info(call_tool start: %s %s, name, args) start time.time() try: result await session.call_tool(name, args) logger.info(call_tool ok: %s, cost%.2fs, name, time.time() - start) return result except Exception as e: logger.error(call_tool error: %s, err%s, name, e) raise不要小看这行日志它能救你于水火。多 Server 的很多故障都是某个 Server 慢或某个调用返回了意料外的格式有日志才能直接定位。5.4 一个收尾技巧手动喂 JSON-RPC 报文调试服务器最后分享一个我平时最常用的调试技巧当你不确定某个 MCP Server 的行为时不用急着写代码直接用一个终端连到 stdio 管道上手动粘贴 JSON-RPC 报文。你先发送 initialize 请求等服务端响应后再发送 tools/list 和指定工具的 call 请求。这个过程能让你非常直观地看到握手交互的每一步也能快速复现协议版本不一致Server 直接断开这类问题。# 在 stdio server 的管道上手动交互 npx -y modelcontextprotocol/server-math /tmp/mcp_out.txt 21 # 然后向 /tmp/mcp_in.txt 写入 JSON-RPC 报文做测试这个技巧看起来原始但在排障时比直接翻源码高效得多。毕竟协议这东西亲眼看到报文往来比在抽象层里瞎猜要可靠一百倍。
