做 Agent 类项目做到第二个版本我基本都会撞到同一个墙工具太多每个工具一套 SDK。最开始图省事直接给每个数据源写一个函数包装器塞进工具列表结果代码量失控不说模型经常因为描述不准确把参数传错排错更是噩梦。后来我把接入层整体换成了 MCPModel Context Protocol编排层换成 LangGraph从单 Server 到多 Server 一路趟过来才敢说摸清了这条链路。这篇文章就把我从协议握手到 LangGraph 多 Server 调用的完整过程拆一遍适合正在做 Agent 集成、或者已经被各种私有 SDK 折磨过的开发者参考。1. 先说为什么卡在“接入”这一层还有多少人在手写工具包装器1.1 集成工具的三代演进很多人还停在第一代如果你做过稍微复杂一点的 AI 应用大概率经历过这个阶段给模型配工具本质上是“每个服务写一个 adapter”。数据库查个用户信息要封装一个get_user_info调个天气接口再封装一个get_weather接内部搜索又写一个search_docs。每个函数的参数校验、超时处理、错误码解析全都不一样写出来的代码重复度高、难维护而且每接一个新数据源就得重新走一遍“看文档、写适配、联调”的流程。再往后有人把工具统一成 OpenAPI 格式或者函数调用规范但那也只是统一了“描述形式”底层链接还是各连各的。真正的问题在于工具的“提供方”和“消费方”之间没有标准协议。MCP 想解决的就是这一层——让工具服务像 USB 设备一样即插即用客户端只需要知道协议不需要知道服务端内部怎么实现。用大白话说以前是你给每个设备配一根专属充电线现在统一成一个口子。1.2 MCP 的职责边界它只解决“连接”不解决“编排”很多人第一次接触 MCP 会有一个误区以为用了 MCP 就有 Agent 了。不是的。MCP 的定位是“模型上下文协议”它管的是客户端和服务端之间怎么发现工具、怎么传参数、怎么返回结果。它不负责模型应该先调哪个工具、调错了怎么办、多步推理怎么走。LangGraph 管的是另一件事状态流转、节点编排、条件分支、循环控制。它决定了 Agent 的“大脑回路”长什么样。所以一个比较干净的架构是MCP Server 负责把外部能力变成标准化的工具LangGraph 负责把这些工具编排进一个有状态、可暂停、可恢复的 Agent 工作流里。两者是互补关系不是替代关系。1.3 我这边的落地场景和整体架构我实际在做的项目类似一个内部效率工具需要同时访问内部文档库、外部搜索、代码仓库索引和几个第三方数据服务。第一版用的是直接包装 SDK 的方案工具数量一多模型的选择准确率明显下降因为很多工具描述里根本说不清边界。改造后我把所有后端能力封装成独立的 MCP Server每个 Server 只暴露真正需要的工具然后由一个统一的网关层注册到 LangGraph 的 Agent 里。整体结构大致是MCP Server多个独立进程→ MCP Client 会话管理网关→ LangGraph Agent 工具列表 → 模型编排调用。后面的章节我会按这个链路逐步拆细节其中协议握手部分是最容易被忽略、但又最容易出问题的地方。2. 握手不是一锤子买卖initialize、能力协商与生命周期管理2.1 传输层选型stdio 和 streamable HTTP 怎么选MCP 目前常见的传输方式有两种stdio 和 streamable HTTP。stdio 适合本地子进程客户端负责拉起一个进程消息通过标准输入输出传递天然适合开发调试和本机工具。streamable HTTP 则适合远程服务客户端通过一个 HTTP endpoint 收发 JSON-RPC 消息服务端可以跑在别的主机上适合多团队部署或者跨网络访问。我的经验是本地优先用 stdio因为省去了网络鉴权和端口管理远程、需要隔离环境的服务用 streamable HTTP。迁移成本倒不大因为协议层是同一套 JSON-RPC换传输方式不会影响工具逻辑只要改连接配置即可。纠结传输方式时别被各种权衡绑架先看你的 Server 部署在哪里就选哪种。2.2 一次完整握手的逐字段拆解MCP 的握手基于 JSON-RPC 2.0。客户端先发一个initialize请求这个请求里带三个关键信息protocolVersion、capabilities和clientInfo。下面是我抓的典型请求报文{jsonrpc:2.0,id:1,method:initialize,params:{ protocolVersion:2025-06-18, capabilities:{roots:{listChanged:false},sampling:{}}, clientInfo:{name:agent-gateway,version:0.1.0} }}服务端收到后会返回自己的能力和版本信息比如{jsonrpc:2.0,id:1,result:{ protocolVersion:2025-06-18, capabilities:{tools:{listChanged:true}}, serverInfo:{name:docs-mcp,version:1.2.0} }}这两条消息做完连接还没完全进入可用状态。客户端还必须再发一条notifications/initialized通知告诉服务端“我已经确认你的能力了咱们进入正常运行阶段”。很多自研客户端的坑就出在这发了initialize就急着调tools/list部分服务端不严格照样能返回但严格实现的服务端会直接挂起或报错表现就是“偶尔能用、偶尔一直等待”。protocolVersion的协商也值得提一句客户端发的是自己支持的版本服务端返回的是双方都能接受的版本。两边版本不一致时以服务端返回的为准所以客户端逻辑里不要假设自己发出去的版本就是最终版本。我在实践中遇到过 Server 只支持旧版本、Client 默认发新版本的情况如果不做版本回退后续消息结构就可能对不上。2.3 生命周期与连接状态管理MCP 连接的生命周期可以简单分成三态连接建立前未握手、运行中握手完成、关闭。运行中客户端可以发tools/list、tools/call、resources/list、prompts/list等请求也可以接收服务端的通知比如工具列表变化通知notifications/tools/list_changed。我建议网关层把每个 Server 的连接状态显式建模不要只在变量里存一个 session 对象。因为实际运行中会发生服务端进程崩了、网络断了、服务端主动关了连接。状态建模到位客户端才知道该重连还是该标记不可用。我在网关里维护的是一个简单的状态字段INITIALIZING、RUNNING、DEGRADED、CLOSED状态迁移都放在一个管理类里统一处理后续加多 Server 时你会感谢这个设计。3. 真正干活的是 tools/list 和 tools/call消息格式与调用链路3.1 工具发现阶段Schema 如何被 Agent 消费握手完成后的第一件事通常是tools/list服务端返回该 Server 暴露的全部工具。每个工具包含name、description和inputSchema其中inputSchema是 JSON Schema 格式用来描述参数结构。{jsonrpc:2.0,id:2,method:tools/list}返回结构大致是{jsonrpc:2.0,id:2,result:{tools:[ {name:search_docs,description:Search internal docs by keywords,inputSchema:{ type:object,properties:{query:{type:string},limit:{type:integer}}, required:[query] }} ]}}这里有一个非常关键的实践认知模型选择工具的依据主要就是name和description。你写得越清楚模型选对的概率越高。很多工具作者把description写成“A tool for searching”基本等于没写。我现在的写法是强制包含“这个工具干什么”“什么时候用”“典型参数示例”“不要用于什么场景”四个要素实测模型误调用率能降不少。3.2 调用与返回content 结构、错误语义、还有 isError调用工具走tools/call参数里带工具名和参数字典{jsonrpc:2.0,id:3,method:tools/call,params:{ name:search_docs,arguments:{query:MCP handshake,limit:5} }}返回结果里的核心是content数组常见类型有text、image、resource。文本型最常见我一般把多个 content item 的 text 拼接后作为工具结果喂回模型。还有两个字段特别容易忽略structuredContent和isError。isError是服务端认为“这次调用本身执行了但业务上失败了”的标记。比如查不到数据、权限不足HTTP 层面成功返回但业务失败。这个语义和抛异常完全不同异常是链路问题isError是业务结果。Agent 编排时要区分处理异常应该重试或降级业务失败则直接把错误信息给模型让它自己决定是换参数还是换工具。3.3 一个调用请求从模型到 Server 的完整时序我画不出来图但可以讲讲我理解中的时序。模型基于当前上下文决定要调用某个工具LangGraph 把模型输出里的 tool_calls 解析出来交到工具执行节点工具执行节点调用我们封装好的适配函数适配函数定位到对应的 MCP Server 会话拼接tools/call请求通过传输层发给服务端服务端执行后返回结果适配函数把content解析成字符串再作为工具结果消息写回状态。模型继续下一轮推理。这个链路里最容易出性能问题的是“每轮都现连”。如果每个工具调用都重新拉起一个 Server 进程、重新握手延迟会非常难看。正确做法是连接复用进程启动时把所有 MCP Server 都连好LangGraph 运行期间直接复用会话。这要求网关层的连接数和运行期生命周期管理要稳后面第 4 节我会给具体实现思路。4. LangGraph 侧改造把多个 MCP Server 适配成统一的工具层4.1 适配层核心代码从 MCP Tool 到 LangChain ToolLangGraph 的工具执行机制依赖 LangChain 的工具抽象。要让 MCP Server 里的工具能被 LangGraph 直接用核心工作就是写一个适配器把 MCP 的 tool 描述 调用函数包装成一个符合 LangChain 规范的 StructuredTool。我这里用DynamicStructuredTool来接 JSON Schema因为它能直接吃 dict 形式的 schema省去手写 pydantic 模型的麻烦。from mcp import ClientSession, StdioServerParameters, stdio_client from langchain_core.tools import DynamicStructuredTool def wrap_mcp_tool(server_name: str, session: ClientSession, mcp_tool): async def _execute(**kwargs) - str: result await session.call_tool(mcp_tool.name, kwargs) parts [] for item in result.content: if getattr(item, type, None) text: parts.append(item.text) if result.isError: return f[{server_name}::{mcp_tool.name}] execution error: (; .join(parts) or unknown error) return \n.join(parts) return DynamicStructuredTool( namef{server_name}__{mcp_tool.name}, descriptionmcp_tool.description, args_schemamcp_tool.inputSchema, coroutine_execute, )这里我给工具名加了server_name__前缀是为了解决多 Server 场景下的工具重名问题第 5 节会展开讲。如果你的 LangChain 版本里DynamicStructuredTool对 dict schema 支持不好就退回用create_model根据inputSchema动态构建 pydantic 模型原理一样只是多一层转换代码。4.2 会话与生命周期多 Server 的网关管理类多 Server 场景下我不建议每个工具各自维护连接应该有一个网关类统一管理。基本思路是每个 Server 一个句柄句柄里持有传输上下文和 ClientSession启动时逐个握手需要工具列表时遍历所有句柄调用时按工具名路由到指定句柄。class McpGateway: def __init__(self, server_configs: list[dict]): self.handles [] for cfg in server_configs: self.handles.append(McpServerHandle(cfg[name], cfg[command], cfg[args])) async def start_all(self): for h in self.handles: await h.start() # 内部包括拉起进程 initialize initialized notification async def list_all_tools(self): all_tools [] for h in self.handles: tools await h.session.list_tools() for t in tools.tools: all_tools.append(wrap_mcp_tool(h.name, h.session, t)) return all_tools async def close_all(self): for h in self.handles: await h.close()这个网关类建议在 LangGraph 图执行前初始化一次Agent 跑完不要立刻销毁连接因为同一个进程里可能连续跑多个任务连接复用能省掉大量握手开销。我踩过的一个坑是想当然地在每次任务开始都调用start_all结果一个长任务里反复重启 Server 进程不仅慢还会把文件句柄占满。4.3 接入 LangGraph 的两种方式第一种最简单用create_react_agent把网关返回的全部工具列表直接塞进去。from langgraph.prebuilt import create_react_agent tools await gateway.list_all_tools() agent create_react_agent(modelmy_model, toolstools) result await agent.ainvoke({messages: [{role: user, content: 查一下最新的项目文档并总结}]})这种方式的优点是省事适合工具总量不大、模型上下文装得下的场景。缺点也明显所有工具都堆在同一个命名空间里Server 多的时候模型选择压力大而且这个 Agent 是“单智能体”结构编排能力有限。第二种是自定义 StateGraph。把工具执行做成一个独立节点模型节点负责决策工具节点负责执行中间用条件边判断“还有没有 tool_calls”。这样你可以在工具执行节点里加拦截、限流、日志、审计等逻辑也可以把不同 Server 的工具分组给不同的子 Agent。对于工具数量超过 15 个、或者有多条业务路径的项目我会更推荐第二种虽然初期代码多一点但后续扩展空间大得多。5. 多 Server 架构里绕不开的三件事命名、路由和故障隔离5.1 工具命名空间重名不是小事是事故源头多个 Server 都叫search的情况非常常见文档搜索是search代码搜索也是search商品搜索还是search。如果直接把工具列表合并模型看到的是一堆同名工具它根本不知道调哪个。我的方案是给每个工具加 Server 前缀同时在前缀命名上做统一规范短、无歧义、一眼能看出归属。比如docs__search、code__search、goods__search。前缀带来的另一个问题是工具名变长占用模型上下文。所以 Server 起名要短我一般用 3-6 个字母的缩写。还有一种替代思路是不改工具名只看 description 里的服务归属但实践中不可靠同名工具的误导性太强别在这个点上省事。5.2 路由与并发同一个网关怎么处理多路请求路由逻辑要建立在“展示名”和“实际调用目标”的映射上。展示给模型的是带前缀的名字网关层负责把展示名拆成 Server 标识和原始工具名再定向到正确的会话执行。映射表在适配器生成时就固定下来不要每次调用都现解析字符串那样容易出错。并发方面LangGraph 一次模型输出可能包含多个 tool_calls。如果这些调用落在不同的 Server 上理论上可以并行我的做法是在工具执行节点里用asyncio.gather并行跑多个工具的协程明显能缩短整个 Agent 的响应时间。同一 Server 内的多个调用就要谨慎了MCP 的请求-响应是有序关联的同一个 session 并发发太多请求部分实现会乱序。我实际的做法是同一 Server 的调用在网关里做简单串行化跨 Server 的调用并行。为了直观对比我把开发和部署时的关键参数整理成了一个表维度单 Server 本地多 Server 本地多 Server 跨主机传输方式stdiostdiostreamable HTTP连接策略单例复用网关统一管理网关统一管理 重连并发策略顺序执行跨 Server 并行、同 Server 串行跨 Server 并行 限流故障影响挂掉即全挂单 Server 降级其他不受影响同上额外考虑网络重试5.3 故障隔离与降级别让一个 Server 拖垮整个 Agent多 Server 最大的优势是隔离但前提是你真的隔离了。如果某个 Server 进程崩了我不希望整个 Agent 直接报错退出而是把涉及它的工具标记为不可用让模型走备选路径。实现上就是在工具执行函数里包一层 try/except捕获异常后返回“工具不可用xxx”这样的文本而不是把异常传出去。同时要给每个工具调用加上超时控制。MCP 调用本身没有内置超时语义我习惯用asyncio.wait_for包一层比如给本地工具设 15 秒、远程工具设 30 秒。超时后把结果标记为失败。模型看到失败结果后要么重试要么换工具这正是 Agent 自愈能力的体现。如果你不做这层控制一个挂死的工具调用会让整个图执行卡住用户看到的现象就是“AI 半天不回话”。6. 我实测中反复踩的坑和一份可抄的避坑清单6.1 握手超时和慢启动初始化时间和进程启动时间不是一回事第一个坑是握手超时设置得太激进。本地 stdio 方式启动一个 Python 写的 MCP Server如果它要 import 大模型库、加载索引文件启动可能要好几秒。我第一次设了 3 秒超时结果 Server 还没起来就超时报错信息又含糊查了半天才反应过来。后来我把initialize的超时设为 20-30 秒进程拉起后单独留出启动窗口这个坑就消失了。同样如果 Server 启动失败要从子进程的 stderr 里捞日志不要只盯着 JSON-RPC 的报错。6.2 initialized notification 和旧版本协商自研客户端最容易翻车的地方第二个坑就是前面提到的漏发notifications/initialized。如果你用的是官方 SDK一般不用操心SDK 会处理好但如果你为了轻量自己实现客户端或者从别的语言移植务必确认这条通知真的发了。另一个翻车点是协议版本协商有些 Server 对新版本协议的支持只是“声明支持”实际实现还是旧语义遇到可疑行为时把双方版本打印出来对比是最快的定位方式。我还遇到过一个动静很诡异的问题同一个 Server命令行下直接通信一切正常放到 LangGraph 里就偶尔卡住。后来发现是网关里用了两个不同的 session 实例一个被工具调用、另一个在等待通知消息根本没走到正确连接上。排查到最后其实就是连接复用时没有校验 session 的归属。这个问题花了我半天时间代码上就是一句话的事所有工具调用的 session 必须来自同一份启动时建立的句柄。6.3 Schema 兼容性和描述质量模型选错工具的隐形推手第三个坑发生在 JSON Schema 转换到 LangChain 工具的过程中。MCP 的inputSchema支持 JSON Schema 的不少特性但 LangChain 侧动态生成 pydantic 模型时对anyOf、oneOf、$ref这类复杂结构的支持并不完善转换失败时整个工具会加载失败。我的建议是Server 侧定义参数时尽量用基础类型和显式required少用嵌套引用。此外参数描述也要写到属性级别模型才知道每个字段应该传什么否则参数传错是家常便饭。6.4 子进程生命周期与安全边界多 Server 时代的运维功课stdio 传输的 Server 本质是子进程进程被 kill、机器重启、端口冲突都可能让连接失效。网关要有关键检查机制我用的方法是定期发ping请求做健康检查发现异常就重启 Server 句柄。同时因为 MCP Server 拥有执行本地代码的权限安全边界必须做只加载可信 Server工具列表按需过滤不需要的工具不要暴露给模型。我在网关上加了工具白名单机制list_tools返回后再按规则过滤一遍避免 Server 里某些高权限工具被模型误调。最后给一张排查速查表遇到问题直接对照现象最可能原因建议处理initialize 超时Server 进程慢启动调大握手超时检查子进程日志工具列表加载时卡住缺少 initialized notification确认通知已发送或降级 SDK 版本同名工具调用结果错乱缺少命名空间全局唯一工具名加 Server 前缀LangGraph 整图卡死单个工具调用无超时用asyncio.wait_for包裹调用Server 崩溃后恢复困难缺少健康检查与重启逻辑定时 ping异常时重建会话模型反复选错工具描述和 schema 质量差重写 description简化 inputSchema这条链路走通之后我最大的感受是MCP 的协议本身不难真正难的是把“多 Server 的进程管理、连接状态、命名空间、超时和故障恢复”这些工程细节都兜住。如果你也在接 MCP 和 LangGraph建议别一上来就追求花哨的多 Agent 编排先用两个本地 Server 跑通握手、工具调用、错误隔离这条主线再往上叠加并发和远程服务。把地基夯实了后面加再多的 Server 都不会手忙脚乱。