1. 从一次多工具调用的踩坑说起去年年底我接手了一个内部工具链整合的活儿需求说起来很简单让一个对话式助手能同时调用公司内部的代码仓库查询、数据库表结构读取、以及一个自研的部署状态检查接口。三个能力三个不同的后端服务每个服务都有自己的鉴权和参数格式。我一开始的想法很朴素——写三个函数在对话流程里根据意图判断该调哪个然后手动拼参数、发请求、解析返回。结果第一版跑通花了不到两天但接下来两周我几乎都在填坑参数格式对不上、超时没有统一处理、某个服务改了字段名导致整条链路静默失败、上下文在多次调用之间丢失。后来我把这套东西推倒重来换成了基于 MCP 协议的统一接入方式再用 LangGraph 做多 Server 的编排。整个链路从“三个散装函数”变成了“一套标准协议 一张状态图”维护成本直接降了一个数量级。这篇文章就把这套方案从头到尾拆一遍——MCP 到底是什么、协议握手阶段发生了什么、怎么把多个 MCP Server 接进 LangGraph、以及我在实操中踩过的那些坑。如果你正在做 AI 应用的工具调用层或者手头有一堆零散的内部接口想要统一暴露给模型这套思路应该能帮你少走不少弯路。哪怕你之前只听说过 MCP 这个词、完全没动过手跟着下面的步骤也能跑起来。2. MCP 到底是什么把工具调用变成一门“通用语言”2.1 为什么需要 MCP 这层协议在没有 MCP 之前模型要调用外部能力通常有两种做法。第一种是把工具描述直接塞进提示词让模型输出一段结构化文本再由应用层解析执行——这就是早期的 function calling 思路。第二种是每个工具单独写适配代码模型输出意图应用层用 if-else 分发。这两种做法在小规模场景下都能用但一旦工具数量上去、或者多个应用要复用同一批工具问题就来了每个应用都要重新实现一遍工具的接入逻辑工具提供方也要为每个消费方适配不同的调用约定。MCPModel Context Protocol要解决的就是这个“N 对 N”的适配爆炸问题。它定义了一套标准的客户端-服务端交互协议工具提供方只需要实现一个 MCP Server任何支持 MCP 的客户端都能直接接入。你可以把它理解成工具调用领域的 USB-C 接口——以前每个设备一个专用口现在统一成一个标准口插上就能用。这里有个关键点容易被忽略MCP 不只是“工具调用协议”它实际上定义了三类能力——Tools可执行的操作、Resources可读取的数据、Prompts预置的提示模板。很多教程只讲 Tools但 Resources 和 Prompts 在实际项目里同样重要。比如你要让模型读取一份配置文件用 Resource 就比包装成一个 Tool 更自然因为它是只读的数据暴露不涉及副作用。2.2 MCP 的核心概念拆解要理解 MCP先得把几个角色分清楚。Host是最终面向用户的应用比如一个桌面客户端或者一个 Web 服务Client是 Host 内部负责与 Server 通信的组件通常一个 Client 对应一个 Server 连接Server则是能力提供方暴露 Tools、Resources、Prompts。这三者的关系是Host 管理多个 Client每个 Client 与一个 Server 建立连接。通信层面MCP 目前主流有两种传输方式stdio和HTTP with SSE以及较新的 Streamable HTTP。stdio 适合本地进程Server 作为子进程启动通过标准输入输出通信配置简单、延迟低适合开发调试和本地工具。HTTP 方式适合远程 Server多个客户端可以共享同一个 Server 实例适合团队内部部署。消息格式上MCP 采用JSON-RPC 2.0。这意味着每个请求和响应都是标准的 JSON-RPC 结构包含jsonrpc、id、method、params等字段。用 JSON-RPC 的好处是协议成熟、有现成的错误码规范、请求响应能通过id精确配对天然支持并发。2.3 MCP 与 LangGraph 的分工边界很多人会混淆 MCP 和 LangGraph 的职责。简单说MCP 负责“能力怎么暴露和调用”LangGraph 负责“什么时候调用、调用完怎么走下一步”。MCP 是工具层的标准LangGraph 是编排层的框架。两者是互补关系不是替代关系。举个具体例子你有三个 MCP Server分别提供数据库查询、代码搜索、部署检查。MCP 保证你调用这三个 Server 的方式是一致的——都是tools/call参数都是 JSON。但“先查数据库、根据结果决定要不要搜代码、再根据代码结果决定要不要检查部署”这个决策流程是 LangGraph 的活儿。LangGraph 用状态图的方式把这个流程显式建模出来每个节点可以是一个 MCP 调用边则定义了流转条件。这种分工的好处是工具层的变化比如某个 Server 换了实现不影响编排逻辑编排逻辑的调整也不影响工具层。两层各自独立演进维护起来清爽很多。3. 协议握手一次 MCP 连接到底发生了什么3.1 握手阶段的完整消息流MCP 连接建立不是“连上就能用”中间有一系列握手消息。以 stdio 传输为例Client 启动 Server 子进程后第一件事是发送initialize请求。这个请求里包含客户端支持的协议版本、客户端能力声明比如是否支持 roots、sampling、以及客户端信息。Server 收到后返回自己的协议版本、能力声明和 Server 信息。这里有个细节值得注意协议版本协商。Client 和 Server 各自声明自己支持的版本如果版本不兼容连接会失败。我在实操中遇到过因为客户端库版本比 Server 新一个大版本导致握手失败的情况报错信息还比较隐晦排查了半天。所以建议在项目里把 MCP 相关依赖的版本锁定避免自动升级带来的意外。握手完成后Client 通常会发送notifications/initialized通知表示初始化完成。之后就可以正常调用tools/list、tools/call、resources/list等方法了。整个握手过程如果一切顺利在本地 stdio 场景下通常几十毫秒就能完成但如果是远程 HTTP 连接网络往返会让这个过程明显变长。3.2 能力声明与动态发现握手阶段的能力声明决定了后续能调用哪些方法。比如 Server 如果没声明tools能力Client 就不应该去调tools/list。这个设计的好处是 Client 可以在握手后就知道 Server 支持什么不需要盲目试探。能力发现是动态的——tools/list返回的是当前 Server 实际暴露的工具列表包含每个工具的名称、描述、输入参数的 JSON Schema。这意味着你可以在不重启 Client 的情况下让 Server 动态增减工具只要重新拉一次列表。我在一个项目里就利用这个特性做了热插拔运维同学在 Server 端加了一个新工具Client 端定时刷新工具列表模型下一次对话就能用上新工具完全不用改客户端代码。不过这里有个坑工具描述的质量直接决定模型选得准不准。我见过很多 Server 把工具描述写得极其简略比如就一句“查询数据”模型根本不知道这个工具查的是什么数据、参数该怎么填。好的工具描述应该包含这个工具做什么、什么场景下用、每个参数的含义和格式、返回值的结构。这部分投入的回报率极高值得花时间打磨。3.3 握手失败的常见原因与排查握手失败在实际项目里并不少见我整理了几类高频原因。第一类是传输层问题stdio 场景下 Server 进程启动失败比如命令路径写错、依赖没装HTTP 场景下端口不通或证书问题。第二类是协议版本不匹配前面提过。第三类是能力声明冲突比如 Client 要求某个 Server 必须支持 Resources但 Server 没声明这个能力。排查的时候我的习惯是先看 Server 进程的 stderr 输出——stdio 场景下 Server 的日志通常打到 stderr很多启动错误会直接显示在那里。如果是 HTTP 场景先用 curl 手动发一个initialize请求确认 Server 本身是活的再排查 Client 侧的配置。这个“先隔离再定位”的思路能省很多时间。提示调试 MCP 连接时把 Client 和 Server 的日志级别都调到 debug能看到完整的 JSON-RPC 消息流。很多问题看一眼原始消息就明白了比猜快得多。4. LangGraph 多 Server 调用的架构设计4.1 为什么用状态图而不是链式调用传统的链式调用比如 LangChain 的 SequentialChain是线性的A 完了走 BB 完了走 C。但多 Server 调用的真实场景往往不是线性的——你可能需要根据第一个 Server 的返回结果决定要不要调第二个 Server或者并行调两个 Server 再汇总。这种带条件分支和并行汇聚的流程用链式表达会非常别扭而状态图天然适合。LangGraph 的核心抽象是StateGraph你定义一个状态结构通常是个字典或 TypedDict然后添加节点每个节点是一个函数接收状态、返回状态更新和边定义节点之间的流转。条件边可以根据状态内容动态决定下一个节点。这个模型和 MCP 多 Server 调用的需求高度契合——每个 MCP 调用是一个节点调用结果写入状态后续节点根据状态决定怎么走。我用下来的体会是状态图最大的价值不是“能画出来”而是把隐式的控制流显式化了。以前散落在代码各处的 if-else 判断现在都变成了图上的边和条件函数一眼就能看出整个流程长什么样。新人接手的时候看图比读代码快得多。4.2 多 Server 的连接管理策略接多个 MCP Server 时连接管理是个需要认真设计的地方。最朴素的做法是每次调用都新建连接、用完关闭但这样开销很大尤其是 stdio 场景下每次都要启动子进程。更好的做法是维护一个长连接池在应用启动时把所有 Server 连接建立好调用时从池里取。但长连接也有代价Server 进程如果崩溃了连接就断了需要有重连机制。我的做法是给每个连接加一个健康检查定期发一个轻量的ping或者tools/list发现异常就重建连接。同时给连接加超时避免某个 Server 卡死拖垮整个流程。另一个策略问题是连接是全局共享还是按会话隔离。如果 Server 是无状态的大多数工具类 Server 都是全局共享没问题还能省资源。但如果 Server 有会话状态比如维护了一个对话上下文那就得按会话隔离否则不同用户的请求会串。这个要根据具体 Server 的行为来定不能一刀切。4.3 状态结构的设计要点状态结构设计得好不好直接决定了图的可维护性。我的经验是状态里应该包含三类信息输入信息用户请求、初始参数、中间结果各个 Server 的返回、控制信息当前步骤、重试次数、错误标记。中间结果的存放有个技巧不要把所有 Server 的返回都平铺在状态顶层而是按 Server 分组比如results: { db: {...}, code: {...}, deploy: {...} }。这样状态结构清晰节点读取自己关心的部分也方便。另外MCP 的返回通常是结构化的内容块数组存进状态前最好做一层归一化把内容块转成更易处理的格式避免下游节点反复解析。控制信息里重试计数和错误标记是两个必须的字段。MCP 调用可能因为网络抖动或 Server 临时故障失败有重试计数就能实现有限次重试。错误标记则让条件边能根据“是否出错”决定走正常流程还是走降级流程。这两个字段看起来简单但少了它们图的健壮性会差很多。5. 从零搭建多 Server 调用的完整实操5.1 环境准备与依赖安装先把环境搭起来。Python 版本建议 3.10 以上因为 LangGraph 和一些 MCP 客户端库用到了较新的类型语法。核心依赖有三个langgraph编排框架、langchain-mcp-adapters把 MCP 工具转成 LangChain 工具方便在 LangGraph 里用、以及mcpMCP 的 Python SDK。pip install langgraph langchain-mcp-adapters mcp如果你要用 HTTP 传输的 Server还需要httpx。另外建议装python-dotenv管理配置把 Server 的路径、端口、鉴权信息放到.env里不要硬编码在代码里。环境变量大概长这样DB_SERVER_CMDpython DB_SERVER_ARGS-m,mcp_servers.db_server CODE_SERVER_URLhttp://localhost:8081/mcp DEPLOY_SERVER_URLhttp://localhost:8082/mcp把命令和参数分开配置是因为 stdio 场景下启动命令和参数需要分别传给客户端库合并成一个字符串反而不好处理。5.2 单个 MCP Server 的接入先接一个 Server 跑通再扩展到多个。以 stdio 传输为例用langchain-mcp-adapters的MultiServerMCPClient来管理连接from langchain_mcp_adapters.client import MultiServerMCPClient client MultiServerMCPClient({ db: { command: python, args: [-m, mcp_servers.db_server], transport: stdio, } }) tools await client.get_tools()get_tools()返回的是 LangChain 工具对象列表每个工具对应 Server 暴露的一个 Tool。这一步背后其实做了好几件事启动 Server 子进程、完成协议握手、调用tools/list、把每个工具的描述和参数 Schema 转成 LangChain 的工具格式。你拿到的tools可以直接绑定到模型上也可以在图节点里手动调用。这里有个实操细节get_tools()是异步的必须在 async 上下文里调用。如果你在同步代码里用需要用asyncio.run()包一层但要注意别在已经有事件循环的环境里再调asyncio.run()会报错。我的做法是整个应用统一用 async避免同步异步混用带来的麻烦。5.3 多 Server 并行接入与工具命名冲突处理接多个 Server 就是把配置字典扩展一下client MultiServerMCPClient({ db: { command: python, args: [-m, mcp_servers.db_server], transport: stdio, }, code: { url: http://localhost:8081/mcp, transport: streamable_http, }, deploy: { url: http://localhost:8082/mcp, transport: streamable_http, } })多 Server 场景下最容易踩的坑是工具名冲突。如果两个 Server 都暴露了一个叫query的工具get_tools()返回的列表里就会有两个同名工具模型调用时无法区分。解决办法有两个一是在 Server 端给工具名加前缀比如db_query、code_query二是在 Client 端做一层重命名。我倾向于在 Server 端加前缀因为这样工具名本身就自带了来源信息模型看到名字就知道该用哪个。另一个坑是工具数量过多导致模型选择困难。我接过一个项目三个 Server 加起来暴露了四十多个工具模型经常选错。后来做了工具分组按场景把工具分成几组每次只把相关组的工具暴露给模型准确率明显提升。这个思路在 LangGraph 里很好实现——不同的图节点绑定不同的工具子集。5.4 用 LangGraph 编排多 Server 调用流程现在进入核心部分用 LangGraph 把多个 MCP 调用串起来。先定义状态from typing import TypedDict, Annotated from langgraph.graph import StateGraph, END import operator class AgentState(TypedDict): query: str db_result: dict code_result: dict deploy_result: dict error: str retry_count: int然后定义节点。每个节点负责调用一个 MCP 工具把结果写进状态async def call_db(state: AgentState): try: result await db_tool.ainvoke({sql: state[query]}) return {db_result: result, error: } except Exception as e: return {error: str(e), retry_count: state.get(retry_count, 0) 1} async def call_code(state: AgentState): result await code_tool.ainvoke({keyword: state[db_result][table]}) return {code_result: result} async def call_deploy(state: AgentState): result await deploy_tool.ainvoke({service: state[code_result][service]}) return {deploy_result: result}接着定义条件边根据状态决定流转def after_db(state: AgentState): if state[error] and state[retry_count] 3: return retry_db if state[error]: return fallback return call_code graph StateGraph(AgentState) graph.add_node(call_db, call_db) graph.add_node(call_code, call_code) graph.add_node(call_deploy, call_deploy) graph.add_node(fallback, lambda s: {deploy_result: {status: skipped}}) graph.set_entry_point(call_db) graph.add_conditional_edges(call_db, after_db, { retry_db: call_db, call_code: call_code, fallback: fallback, }) graph.add_edge(call_code, call_deploy) graph.add_edge(call_deploy, END) graph.add_edge(fallback, END) app graph.compile()这段代码的关键在于after_db这个条件函数——它把“出错重试”“出错降级”“正常继续”三种情况显式表达出来了。以前这些逻辑散在 try-except 里现在集中在图定义里改起来一目了然。5.5 参数传递与结果归一化多 Server 调用里参数传递是个容易被低估的难点。第一个 Server 的返回往往不是第二个 Server 直接能用的格式中间需要做转换。比如数据库查询返回的是行记录列表代码搜索需要的是表名或字段名这中间就得有个提取逻辑。我的做法是在节点内部做转换而不是单独加一个转换节点。原因是转换逻辑通常和具体的 Server 对强相关放在调用节点里更内聚。但转换逻辑要写得防御性强一些——第一个 Server 的返回结构可能因为版本变化而改变转换代码要能处理字段缺失的情况不能直接result[table]这样硬取。结果归一化方面MCP 的返回是内容块数组每个块有type字段text、image、resource 等。我通常写一个辅助函数把内容块数组转成纯文本或结构化字典下游节点统一用归一化后的格式。这样即使某个 Server 返回了特殊类型的内容块也不会让下游节点崩溃。6. 常见问题与排查技巧实录6.1 连接类问题速查连接类问题占了我在 MCP 实操中遇到问题的一大半。下面这张表是我整理的速查表覆盖了最常见的几种情况现象可能原因排查方法握手超时Server 进程未启动或端口不通检查命令路径、端口占用、防火墙协议版本不匹配客户端与服务端版本差异过大锁定依赖版本查看握手日志工具列表为空Server 未声明 tools 能力检查 Server 能力声明配置连接频繁断开长连接无健康检查加 ping 机制和重连逻辑HTTP 401/403鉴权信息缺失或过期检查 token 配置和有效期排查连接问题时我有个习惯先用最简客户端手动连一次。比如用官方 SDK 写个十行的脚本只做握手和tools/list确认 Server 本身没问题。这一步能排除掉大部分“到底是 Server 问题还是 Client 问题”的纠结。6.2 调用超时与重试策略MCP 调用超时是另一个高频问题。默认超时时间往往偏短尤其是涉及数据库查询或远程服务的工具几秒钟根本不够。我的做法是给每个工具单独配置超时而不是用全局默认值。查询类工具给 30 秒写入类工具给 60 秒轻量的状态检查给 5 秒。重试策略上不是所有错误都值得重试。网络抖动、临时性服务不可用这些重试有意义参数错误、鉴权失败重试多少次都一样。所以重试逻辑里要区分错误类型只对可重试的错误做重试。LangGraph 的条件边正好能做这件事——在条件函数里判断错误类型决定是重试还是走降级。注意重试一定要有次数上限并且最好加退避比如每次重试间隔翻倍。我见过没加上限的重试逻辑Server 挂了之后客户端疯狂重试把日志刷爆还把资源耗尽了。6.3 工具选择错误的优化模型选错工具是多 Server 场景下的顽疾。除了前面说的工具分组还有几个优化手段。第一是优化工具描述把使用场景写清楚比如“当需要查询用户订单时使用此工具”比“查询订单”要好得多。第二是减少同时暴露的工具数量人面对太多选项会犹豫模型也一样。第三是在系统提示里给出选择指引比如“优先使用 db 系列工具查询数据只有在 db 工具无法满足时才用 code 工具”。我实测下来这三招组合使用工具选择准确率能从六七成提升到九成以上。其中投入产出比最高的是优化工具描述几乎不花什么成本效果立竿见影。6.4 状态污染与并发问题LangGraph 的状态是每个执行实例独立的正常情况下不会有并发问题。但如果你在节点里用了全局变量或者共享的可变对象就可能出现状态污染。我踩过一次坑在一个节点里用了一个模块级的缓存字典结果两个并发请求互相覆盖了缓存内容导致返回了错误的结果。后来改成把缓存挂在状态里或者用请求级别的上下文问题就解决了。另一个并发相关的点是 MCP 连接池。如果多个图执行实例共享同一个连接池要确保连接池本身是线程安全或协程安全的。大多数客户端库在这方面做得不错但自己实现连接池的话要特别注意。7. 几个让我少走弯路的实操心得第一个心得是先把单个 Server 跑通再扩展。我一开始贪快直接配了三个 Server 一起调结果握手阶段就出问题根本不知道是哪个 Server 的锅。后来改成先接一个、跑通、再加第二个、再跑通每步都确认无误整体调试时间反而更短。第二个心得是给每个 MCP 调用都加日志。日志里记录调用的工具名、参数、耗时、返回状态。这些日志在排查问题时是救命稻草。我现在的习惯是MCP 调用的日志单独打一个 logger和业务日志分开方便过滤。第三个心得是工具描述值得反复打磨。我有个工具的描述改了五版每版都根据模型选错的案例调整措辞最后准确率稳定在九成五以上。这个过程有点像给新人写操作手册写得越清楚对方越不容易出错。第四个心得是别把编排逻辑写得太复杂。LangGraph 能表达很复杂的流程但复杂不等于好。我见过把十几个节点串成一张大图的方案维护起来极其痛苦。我的原则是能用线性流程解决的就别加条件分支能在一个节点里做完的就别拆成三个节点。图的复杂度应该和业务复杂度匹配而不是为了用而用。最后分享一个配置管理的小技巧把每个 MCP Server 的配置写成一个独立的配置文件比如 YAML启动时统一加载。这样新增或修改 Server 不用改代码改配置就行。我在一个项目里用这个方式运维同学自己就能加 Server完全不需要开发介入省了很多沟通成本。