这两年“MCP”这个词在AI工程圈子里快被聊烂了但它到底是什么、为什么能解决工具调用乱象、以及如何把它真正塞进Agent工作流里很多人仍然是一知半解。我自己从早期给Claude写自定义工具适配器到后来把项目全面切到Model Context Protocol再到用LangGraph把多个MCP Server串成一条完整链路中间踩了不少坑。这篇分享就围绕“从协议握手到LangGraph多Server调用”这条主线把MCP的通信机制、传输层选型、多Server接入实践经验一次性讲透适合正在做AI Agent落地、想摆脱重复工具适配的开发者参考。所谓的“MCP”简单说就是给AI模型和外挂工具之间做了一套标准接口。以前每接一个数据源或工具都要写一套私有协议AI应用和工具之间全是密密麻麻的胶水代码。而MCP定义了client和server之间的JSON-RPC通信规范让“AI应用”和“工具”解耦这相当于给AI工具生态定了一个USB-C标准接一次线到处能用。这篇文章的核心就是想让你在读完以后能自己搭建一个MCP Server并且理解如何在LangGraph里同时调度多个Server而不至于被各种隐性问题卡住。1. MCP 协议基础与握手流程拆解1.1 为什么需要MCP模型工具调用的“USB-C时刻”我们先回想一下没有MCP的日子。你要做一个能查数据库的Agent就得写一个Python函数内部建立数据库连接再手动把查询结果拼成prompt返回给模型。你要再接一个GitHub工具又得写一套OAuth流程和API调用。这样的集成方式不仅重复而且每个工具的接口风格都不一样有的返回JSON有的返回XML有的还需要分页处理。时间久了光维护这些“胶水代码”就让人头大。MCP把问题拆成了三层Host宿主应用比如Claude Desktop、LangGraph App、Client协议客户端负责和Server建立会话、Server暴露工具和数据源的服务进程。所有能力都通过统一的三种原语暴露Tools可执行的函数调用、Resources可读取的数据资源、Prompts可复用的提示模板。你只需让Client和Server完成一次标准握手之后所有工具调用都走同一套JSON-RPC报文。这种设计最大的好处是“连接一次处处可用”换哪个AI应用都行换哪个LLM也能用。我在实际工程里感受很深以前接一个工具要画两三天现在只要别人给我一个MCP Server的地址或者命令我把它写进配置十分钟内就能在Agent里调用。这种标准化带来的成本削减才是MCP真正让人兴奋的地方。1.2 一次完整握手的报文级拆解MCP的握手不是简单的TCP三次握手它是在传输层之上做一次“能力协商”。整个过程基于JSON-RPC 2.0请求、响应、通知三种消息类型都有严格的格式约束。我贴一段最核心的握手报文你们感受一下。Client发送initialize请求{ jsonrpc: 2.0, id: 1, method: initialize, params: { protocolVersion: 2024-11-05, capabilities: { roots: { listChanged: true }, sampling: {} }, clientInfo: { name: my-agent, version: 1.0.0 } } }Server返回响应{ jsonrpc: 2.0, id: 1, result: { protocolVersion: 2024-11-05, capabilities: { tools: { listChanged: true }, resources: { subscribe: true, listChanged: true } }, serverInfo: { name: my-mcp-server, version: 0.2.0 } } }之后Client会再发一条notifications/initialized通知到这里才算是正式进入可通信状态。很多人容易忽略一个细节初始化参数里有个protocolVersion双方会协商一个共同支持的协议版本。比如Client声明支持2024-11-05Server端实际支持的是更早的版本那Server会在响应里回一个自己最高支持的版本后续请求都按这个版本解析。如果两边的版本完全不交叉官方建议Server返回一个兼容旧版的版本号但对于某些严格校验的SDK来说协议版本不匹配会直接导致连接失败这点在排查问题时尤其重要。1.3 能力协商与初始化超时握手的关键产出不是“连接建立”而是“能力清单”。MCP的capabilities字段明确告诉对方“我能做什么”。在Client侧可以声明roots允许访问的目录根、sampling模型采样在Server侧更常见的是tools、resources、prompts和logging。我最初踩过一个坑写了个自定义Server明明定义了工具却忘了在capabilities里声明tools结果客户端怎么都拉不到工具列表。后来养成习惯每次写Server首先检查capabilities是否完整。初始化超时也是高频问题。MCP的SDK里一般都有默认超时配置比如Python SDK的initialize默认超时是10秒。如果Server启动很慢比如要加载模型、初始化数据库连接Client可能就因为超时直接断开。我建议在Server的main函数里把耗时初始化操作放到异步任务中保证握手响应能秒回再在后台慢慢准备具体依赖。还有一点是关于生命周期MCP会话不是无限期的Client可以随时发送shutdown请求Server回复后两边再彻底关闭。一些长任务则依赖后续的流式消息继续传输会话状态在服务端会保留。理解这个生命周期模型对定位“调用到一半连接断了”之类的问题很有帮助。2. 传输层与 Server 配置实操2.1 stdio、SSE、Streamable HTTP 三选一MCP的传输方式不是唯一的目前主流有三种stdio、SSE、Streamable HTTP。我直接给一张对比表方便你按场景快速做决策。传输方式通信方向适用场景优点缺点stdio双向通过标准输入输出本地子进程单机工具零网络依赖权限隔离好无法远程调用进程生命周期难管理SSE服务端向客户端单向推送事件远程服务老式浏览器实现简单兼容性好客户端请求受限流式交互较弱Streamable HTTP双向支持流式响应生产级远程服务长时间任务支持POST/GET双向可流式返回需要处理鉴权部署配置复杂我的选择习惯是本地调试、开发环境用stdio把MCP Server作为子进程启动简单直接还能看到忠实日志。等到上线尤其是要跨机器调用时果断换成Streamable HTTP。现在官方SDK已经把它定为推荐传输方案老旧的SSE模式能不用就不用。2.2 最小可运行的 MCP Server 配置我们不讲空理论直接写一个能跑的MCP Server。以Python官方SDK为例实现一个“读取指定文件内容”的工具。先装SDK然后创建server.py。import asyncio from mcp.server.models import InitializationOptions import mcp.server.stdio from mcp.server import NotificationOptions, Server from mcp.types import Tool, TextContent server Server(file-reader) server.list_tools() async def list_tools() - list[Tool]: return [ Tool( nameread_file, description读取指定路径的文件内容, inputSchema{ type: object, properties: { path: {type: string} }, required: [path] } ) ] server.call_tool() async def call_tool(name: str, arguments: dict) - list[TextContent]: if name read_file: path arguments.get(path, ) try: with open(path, r, encodingutf-8) as f: content f.read() return [TextContent(typetext, textcontent)] except Exception as e: return [TextContent(typetext, textferror: {str(e)})] raise ValueError(f未知工具: {name}) async def main(): async with mcp.server.stdio.stdio_server() as (read_stream, write_stream): await server.run( read_stream, write_stream, InitializationOptions( server_namefile-reader, server_version0.1.0, capabilitiesserver.get_capabilities( notification_optionsNotificationOptions(), experimental_capabilities{}, ), ), ) if __name__ __main__: asyncio.run(main())如果你用的是Claude Desktop可以直接在配置文件里加一个mcpServers条目把启动命令填进去。在LangGraph里接入时则通过MultiServerMCPClient来加载这个我们在后面细讲。2.3 多Server的命名空间与工具冲突当你有多个Server时最头大的问题不是启动多个进程而是工具名冲突。比如GitHub MCP里有个工具叫list_issues你自己的工单系统MCP也有一个同名工具。如果一股脑把所有工具直接注册到Agent模型可能就稀里糊涂调错了。解决这类冲突的标准做法是给每个Server加命名空间前缀。很多MCP Client的封装都支持这个能力比如MultiServerMCPClient可以给每个server指定transport参数并把返回工具按server名/工具名的方式重命名。你看下面这个加载代码from langchain_mcp_adapters.client import MultiServerMCPClient client MultiServerMCPClient( { github: { command: npx, args: [-y, modelcontextprotocol/server-github], transport: stdio, }, filesystem: { command: npx, args: [-y, modelcontextprotocol/server-filesystem, /tmp], transport: stdio, } } ) tools await client.get_tools()在这个封装里工具名会变成github.list_issues和filesystem.read_file这样LangGraph里的ToolNode就不会因为同名工具而混淆。如果你用的是自己的SDK一定要在通信层加一层工具名映射不要心存侥幸。3. LangGraph 接入多 Server 的完整实践3.1 LangGraph 在 MCP 场景中的定位LangGraph是LangChain生态里的图编排框架它的核心思路是让你用“节点 边”的方式定义Agent的执行流程。那为什么多Server场景适合用LangGraph因为MCP只解决了“工具协议”问题但它没有解决“工具调度”问题。如果只是把几十个MCP工具一股脑塞给模型模型往往会陷入选择困难或者按错误顺序调用工具。用LangGraph你可以显式规定先调用哪个Server的工具拿到结果后再进哪个节点甚至可以根据条件动态选择分支。我在项目里就是把MCP Server当成“技能包”LangGraph当成“大脑调度器”。大脑决定什么时候用哪个技能包技能包本身则是一堆MCP工具。这样既保留了MCP的即插即用优势又保证了流程的可控性和可观测性。3.2 把 MCP Server 接入 LangGraph 流程LangGraph本身并没有“MCP原生支持”但LangChain官方提供了一个适配器包langchain-mcp-adapters它能把MCP工具转换成LangChain的StructuredTool然后塞进LangGraph的ToolNode。下面是一个完整的示例from langchain_mcp_adapters.client import MultiServerMCPClient from langchain_openai import ChatOpenAI from langgraph.prebuilt import create_react_agent from langgraph.checkpoint.memory import MemorySaver client MultiServerMCPClient( { github: { command: npx, args: [-y, modelcontextprotocol/server-github], transport: stdio, }, db: { url: https://your-server.com/mcp/db, transport: streamable_http, headers: {Authorization: Bearer xxx}, } } ) tools await client.get_tools() model ChatOpenAI(modelgpt-4o, temperature0) graph create_react_agent(model, tools, checkpointerMemorySaver())一个典型的ReAct Agent就搭好了。这里的create_react_agent内部会自动生成ToolNode节点模型会根据任务调用带前缀的工具名。如果你需要手动控制流程可以自己定义节点来调用某个具体工具。3.3 多 Server 调用的架构设计多Server接入不仅是个技术操作更是个架构决策。我概括为两种模式第一种是“合并模式”把不同Server的工具全部丢进同一个ToolNode。适合工具数量少、工具间无明显依赖关系的场景比如查天气MCP加一个做数学计算的MCP。优点是实现快、模型自由度高缺点是一旦Server多工具列表就非常长影响模型决策速度。第二种是“分治模式”每个Server对应一个独立的ToolNode甚至每个节点只允许调用某一类工具。比如GitHub相关操作单独一个节点数据库操作单独一个节点中间由路由节点控制跳转。适合工具数量大、业务流程固定的场景比如企业内部工单处理系统。我实际做一个Repo分析Agent的时候就用了分治模式。三个Server分别是GitHub MCP拉取仓库信息、本地文件系统MCP读取项目文件、SQL MCP查询历史数据。LangGraph的流程是先用GitHub工具列出Issue再根据Issue中的路径用文件系统工具读取代码最后把结果写入SQL。这种模式下模型不需要在几十个工具里挑来挑去每个节点只看到相关的几个工具准确率高了很多。3.4 流式输出与状态管理多Server调用往往意味着长时间的多步骤任务流式输出和状态管理就非常重要了。LangGraph提供了astream_events方法可以实时推送每个节点的事件包括工具开始调用、工具返回结果、模型生成Token等。我在写交互式Agent时就用它把工具调用的中间结果流式转发给前端。async for event in graph.astream_events( {messages: [(user, 分析这个仓库的Issue并生成报告)]}, config{recursion_limit: 20} ): if event[event] on_tool_start: print(调用工具:, event[name], event[data].get(input)) elif event[event] on_tool_end: print(工具输出:, str(event[data].get(output))[:300])状态管理方面LangGraph每个节点都会收到一个共享的State对象。多Server调用的输出要作为下一步输入时你可以在State里用字段名作为标识。比如让SQL查询工具把结果写到query_result字段后续生成报告的节点从这个字段读取。千万注意工具返回的内容要转成字符串否则有些模型的Context Window会直接爆掉。4. 常见问题与排查技巧实录4.1 握手失败“拒绝访问 (os error 5)”如果你在Windows上用stdio启动MCP Server很可能看到类似error: 拒绝访问。 (os error 5) to work without the background server, rerun的报错。这个os error 5在Windows里就是权限不足的意思。排查步骤很简单第一确认你给Server的可执行文件设置了正确的执行权限尤其当Server是可执行脚本如.exe或.cmd时Windows默认可能会拦截。第二确认路径中没有特殊字符最好用绝对路径。第三检查工作目录是否正确有些Server启动时依赖相对路径的文件工作目录不对就会直接报权限错误。如果是远程HTTP方式那还要检查鉴权头是否带上以及服务端是否把/mcp路径暴露在了代理之后。4.2 工具列表为空或调用不到这类问题八成出在capabilities声明上。有些Server虽然实现了list_tools回调但忘了在初始化响应里声明toolscapability客户端就会认为该Server不支持工具。调试时可以直接用mcp.__main__里的调试命令行来查看server的完整初始化响应。还有一种情况是Server进程没有正常启动但客户端没感知到。你会发现握手好像成功了但拉工具列表时返回空。这种多半是Server端在启动过程中崩了或者还有依赖没有加载。建议先把Server进程单独跑一遍用curl或官方调试工具验证再接入LangGraph。4.3 流式输出中断与超时长时间跑LangGraph任务时Streamable HTTP很容易出现流式输出中断尤其在请求超过路由器默认超时时。这时的表现是前面几步有正常返回到了某个工具调用后整个图卡住不动。我的做法是把所有MCP工具的timeout参数调大同时在LangGraph的配置里增加recursion_limit避免因为递归次数过多而报错。如果是自己实现MCP Server记得给长任务工具增加进度通知机制而不是让客户端一直干等。协议里虽然没有强制要求但一个负责任的生产级Server应该主动上报进度。4.4 MCP 调试三板斧日志、抓包、最小复现最后分享一套我一直在用的调试方法论。第一斧是开日志Python SDK支持--log-level DEBUG把握手报文和工具调用报文都打出来。第二斧是抓包看报文对于HTTP传输的方式直接抓HTTP流量查看JSON-RPC消息是否符合规范。第三斧是最小复现出了问题时不要直接拿整个LangGraph图来调而是先写一个10行代码的Client单独连目标MCP Server看能不能握手、能不能调用工具。这三个层层递进能帮你快速定位问题在哪个Layer。我把常见问题整理成了速查表方便你直接对照。症状可能原因解决办法初始化超时Server启动慢异步初始化提高SDK超时工具拉取不到capabilities未声明tools检查Server初始化响应os error 5Windows权限不足检查执行权限和路径工具名冲突多个Server同名工具启用命名空间前缀流式输出中断网络代理超时调大timeout使用Streamable HTTP调用结果为空工具返回类型不规范检查工具返回值是否序列化正确从我自己的实际体验来说把MCP和LangGraph组合起来之后最大的改变不是写代码量变少了而是整个Agent系统的“接插”成本被压到了极低。以前每加一个工具就要重新梳理一遍调用链和参数映射现在只需要配一个MCP Server地址再在LangGraph里决定把它挂到哪个节点就完事了。如果你还在纠结项目里工具调用越来越乱不妨先梳理出“哪些能力可以拆成独立Server”再按这个思路走一遍跑通后你会回来感谢当初动手的自己。 
长河君 · 2026/10/8 21:02:01 · 阅读 1.2k MCP协议与LangGraph实践：从握手到多Server调用的完整指南
这两年“MCP”这个词在AI工程圈子里快被聊烂了但它到底是什么、为什么能解决工具调用乱象、以及如何把它真正塞进Agent工作流里很多人仍然是一知半解。我自己从早期给Claude写自定义工具适配器到后来把项目全面切到Model Context Protocol再到用LangGraph把多个MCP Server串成一条完整链路中间踩了不少坑。这篇分享就围绕“从协议握手到LangGraph多Server调用”这条主线把MCP的通信机制、传输层选型、多Server接入实践经验一次性讲透适合正在做AI Agent落地、想摆脱重复工具适配的开发者参考。所谓的“MCP”简单说就是给AI模型和外挂工具之间做了一套标准接口。以前每接一个数据源或工具都要写一套私有协议AI应用和工具之间全是密密麻麻的胶水代码。而MCP定义了client和server之间的JSON-RPC通信规范让“AI应用”和“工具”解耦这相当于给AI工具生态定了一个USB-C标准接一次线到处能用。这篇文章的核心就是想让你在读完以后能自己搭建一个MCP Server并且理解如何在LangGraph里同时调度多个Server而不至于被各种隐性问题卡住。1. MCP 协议基础与握手流程拆解1.1 为什么需要MCP模型工具调用的“USB-C时刻”我们先回想一下没有MCP的日子。你要做一个能查数据库的Agent就得写一个Python函数内部建立数据库连接再手动把查询结果拼成prompt返回给模型。你要再接一个GitHub工具又得写一套OAuth流程和API调用。这样的集成方式不仅重复而且每个工具的接口风格都不一样有的返回JSON有的返回XML有的还需要分页处理。时间久了光维护这些“胶水代码”就让人头大。MCP把问题拆成了三层Host宿主应用比如Claude Desktop、LangGraph App、Client协议客户端负责和Server建立会话、Server暴露工具和数据源的服务进程。所有能力都通过统一的三种原语暴露Tools可执行的函数调用、Resources可读取的数据资源、Prompts可复用的提示模板。你只需让Client和Server完成一次标准握手之后所有工具调用都走同一套JSON-RPC报文。这种设计最大的好处是“连接一次处处可用”换哪个AI应用都行换哪个LLM也能用。我在实际工程里感受很深以前接一个工具要画两三天现在只要别人给我一个MCP Server的地址或者命令我把它写进配置十分钟内就能在Agent里调用。这种标准化带来的成本削减才是MCP真正让人兴奋的地方。1.2 一次完整握手的报文级拆解MCP的握手不是简单的TCP三次握手它是在传输层之上做一次“能力协商”。整个过程基于JSON-RPC 2.0请求、响应、通知三种消息类型都有严格的格式约束。我贴一段最核心的握手报文你们感受一下。Client发送initialize请求{ jsonrpc: 2.0, id: 1, method: initialize, params: { protocolVersion: 2024-11-05, capabilities: { roots: { listChanged: true }, sampling: {} }, clientInfo: { name: my-agent, version: 1.0.0 } } }Server返回响应{ jsonrpc: 2.0, id: 1, result: { protocolVersion: 2024-11-05, capabilities: { tools: { listChanged: true }, resources: { subscribe: true, listChanged: true } }, serverInfo: { name: my-mcp-server, version: 0.2.0 } } }之后Client会再发一条notifications/initialized通知到这里才算是正式进入可通信状态。很多人容易忽略一个细节初始化参数里有个protocolVersion双方会协商一个共同支持的协议版本。比如Client声明支持2024-11-05Server端实际支持的是更早的版本那Server会在响应里回一个自己最高支持的版本后续请求都按这个版本解析。如果两边的版本完全不交叉官方建议Server返回一个兼容旧版的版本号但对于某些严格校验的SDK来说协议版本不匹配会直接导致连接失败这点在排查问题时尤其重要。1.3 能力协商与初始化超时握手的关键产出不是“连接建立”而是“能力清单”。MCP的capabilities字段明确告诉对方“我能做什么”。在Client侧可以声明roots允许访问的目录根、sampling模型采样在Server侧更常见的是tools、resources、prompts和logging。我最初踩过一个坑写了个自定义Server明明定义了工具却忘了在capabilities里声明tools结果客户端怎么都拉不到工具列表。后来养成习惯每次写Server首先检查capabilities是否完整。初始化超时也是高频问题。MCP的SDK里一般都有默认超时配置比如Python SDK的initialize默认超时是10秒。如果Server启动很慢比如要加载模型、初始化数据库连接Client可能就因为超时直接断开。我建议在Server的main函数里把耗时初始化操作放到异步任务中保证握手响应能秒回再在后台慢慢准备具体依赖。还有一点是关于生命周期MCP会话不是无限期的Client可以随时发送shutdown请求Server回复后两边再彻底关闭。一些长任务则依赖后续的流式消息继续传输会话状态在服务端会保留。理解这个生命周期模型对定位“调用到一半连接断了”之类的问题很有帮助。2. 传输层与 Server 配置实操2.1 stdio、SSE、Streamable HTTP 三选一MCP的传输方式不是唯一的目前主流有三种stdio、SSE、Streamable HTTP。我直接给一张对比表方便你按场景快速做决策。传输方式通信方向适用场景优点缺点stdio双向通过标准输入输出本地子进程单机工具零网络依赖权限隔离好无法远程调用进程生命周期难管理SSE服务端向客户端单向推送事件远程服务老式浏览器实现简单兼容性好客户端请求受限流式交互较弱Streamable HTTP双向支持流式响应生产级远程服务长时间任务支持POST/GET双向可流式返回需要处理鉴权部署配置复杂我的选择习惯是本地调试、开发环境用stdio把MCP Server作为子进程启动简单直接还能看到忠实日志。等到上线尤其是要跨机器调用时果断换成Streamable HTTP。现在官方SDK已经把它定为推荐传输方案老旧的SSE模式能不用就不用。2.2 最小可运行的 MCP Server 配置我们不讲空理论直接写一个能跑的MCP Server。以Python官方SDK为例实现一个“读取指定文件内容”的工具。先装SDK然后创建server.py。import asyncio from mcp.server.models import InitializationOptions import mcp.server.stdio from mcp.server import NotificationOptions, Server from mcp.types import Tool, TextContent server Server(file-reader) server.list_tools() async def list_tools() - list[Tool]: return [ Tool( nameread_file, description读取指定路径的文件内容, inputSchema{ type: object, properties: { path: {type: string} }, required: [path] } ) ] server.call_tool() async def call_tool(name: str, arguments: dict) - list[TextContent]: if name read_file: path arguments.get(path, ) try: with open(path, r, encodingutf-8) as f: content f.read() return [TextContent(typetext, textcontent)] except Exception as e: return [TextContent(typetext, textferror: {str(e)})] raise ValueError(f未知工具: {name}) async def main(): async with mcp.server.stdio.stdio_server() as (read_stream, write_stream): await server.run( read_stream, write_stream, InitializationOptions( server_namefile-reader, server_version0.1.0, capabilitiesserver.get_capabilities( notification_optionsNotificationOptions(), experimental_capabilities{}, ), ), ) if __name__ __main__: asyncio.run(main())如果你用的是Claude Desktop可以直接在配置文件里加一个mcpServers条目把启动命令填进去。在LangGraph里接入时则通过MultiServerMCPClient来加载这个我们在后面细讲。2.3 多Server的命名空间与工具冲突当你有多个Server时最头大的问题不是启动多个进程而是工具名冲突。比如GitHub MCP里有个工具叫list_issues你自己的工单系统MCP也有一个同名工具。如果一股脑把所有工具直接注册到Agent模型可能就稀里糊涂调错了。解决这类冲突的标准做法是给每个Server加命名空间前缀。很多MCP Client的封装都支持这个能力比如MultiServerMCPClient可以给每个server指定transport参数并把返回工具按server名/工具名的方式重命名。你看下面这个加载代码from langchain_mcp_adapters.client import MultiServerMCPClient client MultiServerMCPClient( { github: { command: npx, args: [-y, modelcontextprotocol/server-github], transport: stdio, }, filesystem: { command: npx, args: [-y, modelcontextprotocol/server-filesystem, /tmp], transport: stdio, } } ) tools await client.get_tools()在这个封装里工具名会变成github.list_issues和filesystem.read_file这样LangGraph里的ToolNode就不会因为同名工具而混淆。如果你用的是自己的SDK一定要在通信层加一层工具名映射不要心存侥幸。3. LangGraph 接入多 Server 的完整实践3.1 LangGraph 在 MCP 场景中的定位LangGraph是LangChain生态里的图编排框架它的核心思路是让你用“节点 边”的方式定义Agent的执行流程。那为什么多Server场景适合用LangGraph因为MCP只解决了“工具协议”问题但它没有解决“工具调度”问题。如果只是把几十个MCP工具一股脑塞给模型模型往往会陷入选择困难或者按错误顺序调用工具。用LangGraph你可以显式规定先调用哪个Server的工具拿到结果后再进哪个节点甚至可以根据条件动态选择分支。我在项目里就是把MCP Server当成“技能包”LangGraph当成“大脑调度器”。大脑决定什么时候用哪个技能包技能包本身则是一堆MCP工具。这样既保留了MCP的即插即用优势又保证了流程的可控性和可观测性。3.2 把 MCP Server 接入 LangGraph 流程LangGraph本身并没有“MCP原生支持”但LangChain官方提供了一个适配器包langchain-mcp-adapters它能把MCP工具转换成LangChain的StructuredTool然后塞进LangGraph的ToolNode。下面是一个完整的示例from langchain_mcp_adapters.client import MultiServerMCPClient from langchain_openai import ChatOpenAI from langgraph.prebuilt import create_react_agent from langgraph.checkpoint.memory import MemorySaver client MultiServerMCPClient( { github: { command: npx, args: [-y, modelcontextprotocol/server-github], transport: stdio, }, db: { url: https://your-server.com/mcp/db, transport: streamable_http, headers: {Authorization: Bearer xxx}, } } ) tools await client.get_tools() model ChatOpenAI(modelgpt-4o, temperature0) graph create_react_agent(model, tools, checkpointerMemorySaver())一个典型的ReAct Agent就搭好了。这里的create_react_agent内部会自动生成ToolNode节点模型会根据任务调用带前缀的工具名。如果你需要手动控制流程可以自己定义节点来调用某个具体工具。3.3 多 Server 调用的架构设计多Server接入不仅是个技术操作更是个架构决策。我概括为两种模式第一种是“合并模式”把不同Server的工具全部丢进同一个ToolNode。适合工具数量少、工具间无明显依赖关系的场景比如查天气MCP加一个做数学计算的MCP。优点是实现快、模型自由度高缺点是一旦Server多工具列表就非常长影响模型决策速度。第二种是“分治模式”每个Server对应一个独立的ToolNode甚至每个节点只允许调用某一类工具。比如GitHub相关操作单独一个节点数据库操作单独一个节点中间由路由节点控制跳转。适合工具数量大、业务流程固定的场景比如企业内部工单处理系统。我实际做一个Repo分析Agent的时候就用了分治模式。三个Server分别是GitHub MCP拉取仓库信息、本地文件系统MCP读取项目文件、SQL MCP查询历史数据。LangGraph的流程是先用GitHub工具列出Issue再根据Issue中的路径用文件系统工具读取代码最后把结果写入SQL。这种模式下模型不需要在几十个工具里挑来挑去每个节点只看到相关的几个工具准确率高了很多。3.4 流式输出与状态管理多Server调用往往意味着长时间的多步骤任务流式输出和状态管理就非常重要了。LangGraph提供了astream_events方法可以实时推送每个节点的事件包括工具开始调用、工具返回结果、模型生成Token等。我在写交互式Agent时就用它把工具调用的中间结果流式转发给前端。async for event in graph.astream_events( {messages: [(user, 分析这个仓库的Issue并生成报告)]}, config{recursion_limit: 20} ): if event[event] on_tool_start: print(调用工具:, event[name], event[data].get(input)) elif event[event] on_tool_end: print(工具输出:, str(event[data].get(output))[:300])状态管理方面LangGraph每个节点都会收到一个共享的State对象。多Server调用的输出要作为下一步输入时你可以在State里用字段名作为标识。比如让SQL查询工具把结果写到query_result字段后续生成报告的节点从这个字段读取。千万注意工具返回的内容要转成字符串否则有些模型的Context Window会直接爆掉。4. 常见问题与排查技巧实录4.1 握手失败“拒绝访问 (os error 5)”如果你在Windows上用stdio启动MCP Server很可能看到类似error: 拒绝访问。 (os error 5) to work without the background server, rerun的报错。这个os error 5在Windows里就是权限不足的意思。排查步骤很简单第一确认你给Server的可执行文件设置了正确的执行权限尤其当Server是可执行脚本如.exe或.cmd时Windows默认可能会拦截。第二确认路径中没有特殊字符最好用绝对路径。第三检查工作目录是否正确有些Server启动时依赖相对路径的文件工作目录不对就会直接报权限错误。如果是远程HTTP方式那还要检查鉴权头是否带上以及服务端是否把/mcp路径暴露在了代理之后。4.2 工具列表为空或调用不到这类问题八成出在capabilities声明上。有些Server虽然实现了list_tools回调但忘了在初始化响应里声明toolscapability客户端就会认为该Server不支持工具。调试时可以直接用mcp.__main__里的调试命令行来查看server的完整初始化响应。还有一种情况是Server进程没有正常启动但客户端没感知到。你会发现握手好像成功了但拉工具列表时返回空。这种多半是Server端在启动过程中崩了或者还有依赖没有加载。建议先把Server进程单独跑一遍用curl或官方调试工具验证再接入LangGraph。4.3 流式输出中断与超时长时间跑LangGraph任务时Streamable HTTP很容易出现流式输出中断尤其在请求超过路由器默认超时时。这时的表现是前面几步有正常返回到了某个工具调用后整个图卡住不动。我的做法是把所有MCP工具的timeout参数调大同时在LangGraph的配置里增加recursion_limit避免因为递归次数过多而报错。如果是自己实现MCP Server记得给长任务工具增加进度通知机制而不是让客户端一直干等。协议里虽然没有强制要求但一个负责任的生产级Server应该主动上报进度。4.4 MCP 调试三板斧日志、抓包、最小复现最后分享一套我一直在用的调试方法论。第一斧是开日志Python SDK支持--log-level DEBUG把握手报文和工具调用报文都打出来。第二斧是抓包看报文对于HTTP传输的方式直接抓HTTP流量查看JSON-RPC消息是否符合规范。第三斧是最小复现出了问题时不要直接拿整个LangGraph图来调而是先写一个10行代码的Client单独连目标MCP Server看能不能握手、能不能调用工具。这三个层层递进能帮你快速定位问题在哪个Layer。我把常见问题整理成了速查表方便你直接对照。症状可能原因解决办法初始化超时Server启动慢异步初始化提高SDK超时工具拉取不到capabilities未声明tools检查Server初始化响应os error 5Windows权限不足检查执行权限和路径工具名冲突多个Server同名工具启用命名空间前缀流式输出中断网络代理超时调大timeout使用Streamable HTTP调用结果为空工具返回类型不规范检查工具返回值是否序列化正确从我自己的实际体验来说把MCP和LangGraph组合起来之后最大的改变不是写代码量变少了而是整个Agent系统的“接插”成本被压到了极低。以前每加一个工具就要重新梳理一遍调用链和参数映射现在只需要配一个MCP Server地址再在LangGraph里决定把它挂到哪个节点就完事了。如果你还在纠结项目里工具调用越来越乱不妨先梳理出“哪些能力可以拆成独立Server”再按这个思路走一遍跑通后你会回来感谢当初动手的自己。