MCP 技术在圈子里热了有大半年了我从最早自己搭单机 Server 试水到最近把 LangGraph 和多个 MCP Server 串进同一个 Agent 流程里跑通中间踩了不少坑。这篇东西不是官方文档的复读是我把自己从协议握手到多 Server 调用的完整链路捋一遍顺带把过程中涉及的关键原理、选型逻辑、代码细节都记下来。适合两类人看一是刚接触 MCP 但不知道协议层到底在干什么的初学者二是已经在单 Server 上跑通、想进一步把多个工具源接入 LangGraph 做统一调度的开发者。1. 从一次“无心插柳”说起MCP 到底在解决什么问题先说清楚一个前提MCP 全称 Model Context Protocol是一个面向 AI 应用与外部工具、数据源之间通信的开放协议。它的核心思路是统一 AI 应用访问外部能力的接口形式让“模型调用工具”这件事标准化、可复用、可隔离。为什么需要它最直观的痛点在于生态割裂。过去每个 AI 应用都要自己去对接数据库、文件系统、第三方 API每家做的工具调用接口都不一样。模型服务商一套标准IDE 插件一套标准企业内部系统又一套标准集成成本非常高。MCP 的做法是定义一个通用的“工具服务器”模型AI 应用Host通过统一协议去连接各种 MCP Server每个 Server 负责暴露自己的能力Host 端只需要实现协议就能访问所有 Server 的能力。你可以把它类比成 USB-C 接口——设备工具原语千差万别但传输协议一致插上就能用。在具体应用场景里MCP 的威力体现得很直接。比如我在本地开发环境会同时挂几个 Server一个负责查询订单系统的状态一个负责操作文件还有一个是用来访问内部知识库的。LangGraph Agent 需要哪个能力就直接调用对应的 MCP 工具不需要为每个数据源单独写一套集成代码。这种“中心化接入、分布式能力”的架构正好契合 LangGraph 这种更偏图编排、多智能体协作的框架。所以你会发现MCP 和 LangGraph 天然是互补关系MCP 解决工具接入和协议统一LangGraph 解决 Agent 的编排和状态管理。我建议入门的人不要一上来就钻进代码细节里。先把 MCP 的角色模型搞清楚Host宿主机、Client客户端、Server服务端。Host 是最终用户所在的应用程序环境比如 IDE、Agent 框架、甚至是一个命令行工具Client 是 Host 内部与 Server 建立连接的协议实现Server 则提供工具、资源、提示词三类核心原语。理解了这个分层后面读握手文档和调试代码都会顺畅很多。2. 协议握手MCP 的前 5 次对话决定一切2.1 initialize 请求第一次对话如何敲定“双方身份”MCP 的通信建立在 JSON-RPC 2.0 之上。整个过程类似两个人见面握手先确认身份再交换能力清单最后才进入正式工作。最开始的请求是initialize客户端发给服务端包含三个关键字段protocolVersion、capabilities、clientInfo。protocolVersion必须明确指定版本号例如2024-11-05。服务端收到后会检查兼容性如果版本不匹配会返回支持的版本列表客户端再协商。这里有个容易忽略的点初始化阶段不要急着发业务请求必须先等服务端返回initialize响应并确认serverInfo和capabilities。我之前第一次开发时按惯性思维直接发送了tools/list结果服务端直接报错因为 MCP 客户端库内部的状态机还没完成初始化。MCP 的协议状态机严格区分“未初始化”和“已初始化”两个阶段错误处理方式完全不一样。capabilities是双方协商的关键。客户端在initialize里声明自己支持哪些特性比如roots.listChanged、sampling等服务端则在响应里声明自己支持的能力通常是tools、resources、prompts三项。现代 MCP SDK 实现里这三项基本是默认声明并自动处理的但在做跨语言对接、或手写协议实现时必须搞清楚字段含义。我自己后来在写一个边缘 case 的 Client 时就踩过如果客户端没声明sampling能力服务端就不能发起 LLM 采样请求哪怕服务端实现了这个 feature 也会被协议层拦截。这里我做一个表格把握手阶段的核心消息和职责列出来方便对照排查阶段消息方向消息类型核心职责1Client → Serverinitialize宣告协议版本、客户端能力、客户端身份2Server → Clientinitialize响应宣告服务端能力、服务端身份、协议版本3Client → Servernotifications/initialized通知服务端“初始化完成可以开始业务”4Client → Servertools/list拉取服务端可用工具清单5Client → Servertools/call按名称调用具体工具2.2 从 initialized 到 tools/list能力发现与资源预检初始化完成的消息是notifications/initialized它是通知类型不需要响应。很多初级开发者会忽略这个通知但如果漏发服务端会认为客户端还处于握手状态拒绝后续业务调用。在 LangGraph 集成场景中tools/list的响应会被转换成语义更丰富的 LangChain Tool 对象。转换过程会保留工具名称、描述、输入 Schema 和输出结构。我发现一个关键点MCP 的 Tool 描述质量直接决定了 Agent 在 LangGraph 中的“路由判断”质量。如果工具描述写得太泛比如“处理数据”Agent 就不知道什么时候该调用它容易乱选或漏选。好的描述应该具体说明输入参数含义、适用场景、返回结果格式甚至可以写明在什么情况下不要用这个工具。这也是很多教程不会强调的细节——协议本身只要求有描述字段但描述写得好不好直接关系到 Agent 后续行为。在抓包或日志观察时tools/list的交互也能让你看到 MCP 协议的 JSON-RPC 风格jsonrpc: 2.0、id用于关联请求和响应、method标明动作。我之前一直用 Charles 抓 HTTP 流量后来才发现 MCP 的 stdio 传输用的是本地进程标准输入输出HTTPSSE 传输则走普通 HTTP 流式连接。调协议时用“印日志”比“抓包”更直观尤其是 stdio 模式时。3. 快速搭建一个可复现的 MCP ServerFastMCP 实战3.1 选型思路为什么用官方 Python SDK 而不是手写要理解 MCP 的调用过程最直接的方式是自己先写一个 Server。目前生态里最省事的方案是用官方 Python SDKmcp包里的FastMCP类。它屏蔽了大量原语细节让你用装饰器就能暴露工具方法。很多人会问为什么不直接手写 JSON-RPC我的看法是手写能帮助你理解协议但作为工程实践SDK 的成熟度已经足够而且可控性更强。FastMCP 在底层维护了协议握手、状态管理等细节更重要的是它同时支持 stdio 和 HTTPSSE 两种传输模式一个对象换一个参数就能跑起来。选型时另一个重要考虑是“Server 与 Agent 进程的关系”。本地开发时用 stdio 模式最方便因为不需要维护额外端口和进程生命周期但如果 Server 要面向远程、多租户场景就必须走 HTTPSSE或最新的 streamable HTTP 传输否则无法跨机器访问。这个决定应该在写代码之前做我在项目中就是吃了“先用 stdio 全部打通、再改远程方式”的亏改起来量不大但琐碎。3.2 一个订单查询 Server 的完整实现工具本身的设计要和真实业务贴近。假设我要在 LangGraph 里做一个订单助手那么至少需要一个订单状态查询工具和一个内部备注写入工具。用 FastMCP 实现大概是这种感觉from mcp.server.fastmcp import FastMCP mcp FastMCP(order-service) mcp.tool() def get_order_status(order_id: str) - dict: 查询订单当前状态返回状态码、配送进度、预计送达时间。 order_id: 订单编号形如 20250101ABC。 # 这里对接真实的订单系统本地先用 mock 数据 return { order_id: order_id, status: shipped, progress: 已到达本地配送站, eta: 2025-02-01 18:00 } mcp.tool() def add_internal_note(order_id: str, note: str) - str: 给指定订单追加内部备注常用于客服协作。 # 写库操作 return fnote added for {order_id}在启动方式上FastMCP 支持两种入口。stdio 模式就是默认地跑一个从 stdin 读、stdout 写的进程HTTPSSE 模式则需要指定监听地址如下if __name__ __main__: # 默认 stdio 模式 mcp.run() # 远程模式则换成: # mcp.run(transportstreamable-http)从我实测来看stdio 模式在 LangGraph 本机集成时最稳定冷启动时间极短但一旦涉及容器部署或多机调度就老老实实切到 HTTP 模式因为 stdio 的进程生命周期和连接状态管理比较琐碎。新手经常问“为什么我的 Server 代码改了之后 Agent 还是旧行为”——这是缓存问题LangGraph 客户端侧如果是长连接需要重启或重新初始化客户端才能获取新的工具列表。后面我会在问题排查部分展开讲这个。3.3 工具描述与入参 Schema 的细节打磨在写 MCP Server 时有一个细节决定了 Agent 的调用精度参数 Schema 和 descriptions。如果参数是枚举值一定要写清楚合法取值如果参数之间存在依赖关系要在描述里说明。原因在于 LangGraph 里的 LLM 在做工具调用时更像是“在 Schema 驱动的 API 文档中做填空”而不是天然理解你的业务。糟糕的 Schema 会导致模型编造参数误用工具。一种有效的写法是尽量把一个工具的粒度拆细。宁可多暴露几个小工具也不要把多个能力塞进一个带mode参数的万能工具里。为什么因为 Agent 在图编排时的意图判断往往基于工具描述和参数结构小工具更易命中意图大工具容易导致“描述稀疏、调用含糊”。我实际拆过一版把原来一个process_order工具拆成query_order和modify_order后Agent 的成功率明显提升同时出错时可排查范围也变小了。4. LangGraph 与 MCP 的集成链路4.1 用 MultiServerMCPClient 同时挂载多个服务LangGraph 生态中推荐做法是使用langchain-mcp-adapters包里的MultiServerMCPClient。这个 client 专门用来管理多个 MCP Server 的连接并为每个 Server 动态加载工具。它的设计动机非常直接LangGraph Agent 需要同时访问多个外部能力源而底层连接的建立、协议握手、工具拉取应该被统一管理。下面是一个挂载两个 Server 的示例一个走 HTTPSSE 的远程服务一个走 stdio 的本地服务from langchain_mcp_adapters.client import MultiServerMCPClient from langgraph.prebuilt import create_react_agent from langchain_openai import ChatOpenAI client MultiServerMCPClient( { orders: { transport: sse, url: http://localhost:8000/mcp, }, local-utils: { command: python, args: [/path/to/local_server.py], transport: stdio, }, } ) async with client as mcp_client: tools await mcp_client.get_tools() agent create_react_agent( modelChatOpenAI(modelgpt-4o), toolstools, ) result await agent.ainvoke({messages: [{role: user, content: 订单 20250101ABC 送到哪了}]})这段代码看起来简单但背后有几个关键点需要理解透。第一transport字段决定了连接方式。sse意味着客户端会先发初始化请求然后通过 SSE 流订阅服务端事件stdio则直接 spawn 一个本地进程与它的标准输入/输出流进行通信。新版 sdk 还支持streamable-http我在新项目中更倾向用这个因为它是双向流式传输比传统 SSE 更适合长对话场景不过生态兼容性还在演进旧 Server 不一定支持。第二tools是从所有 Server 聚合后的一个扁平列表。LangGraph 的create_react_agent并不关心单个工具来自哪个 MCP Server它只关心namedescriptionargs_schema。聚合之后原来 Server 之间的边界对 Agent 来说就是透明的。这一步的抽象能力正是 MCP 的优势Agent 侧的工具管理与工具来源完全解耦。第三整个 client 是用异步上下文管理器包裹的。连接的生命周期是这个模块的关键设计——所有 Server 的初始化握手在进入上下文时完成工具拉取在内部完成退出上下文时统一释放连接。如果在外面保留长连接状态很容易导致资源泄漏。我之前在一个长期运行的 worker 里踩过这个坑后来把所有 MCP 连接统一放进应用启动时的生命周期函数里管理。4.2 Agent 拿到 tools 之后的编排策略LangGraph 的create_react_agent本质上是 ReAct 模式的预构建图模型根据用户输入决定是否调用工具、调用哪个工具、观察工具输出、继续推理。它内部的状态结构是messages列表每个工具调用产生的消息都会被追踪。这带来一个重要好处多轮工具调用之间的上下文依赖关系天然保存在图的状态里。例如用户先问“订单到哪了”模型调用get_order_status拿到eta用户又问“帮我给这个订单加条备注”模型可能需要先依赖前面的order_id才能调用add_internal_note。这种依赖不是我们手动传递的而是模型根据对话上下文自主判断的。LangGraph 的状态管理让这种多轮交互非常自然。但是这里有一个我需要提醒的点模型能自主调用多个工具不代表我们不需要控制执行顺序。ReAct 模式只是最基本的循环。如果业务逻辑有严格的前置条件应该用 LangGraph 显式构建图节点比如“先查询订单状态再根据状态决定是否调用备注工具”而不是把全部决策交给模型。MCP 工具在图中充当叶子节点的能力执行器路由和条件跳转应该靠图结构化设计。这也是我在做复杂 Agent 时更偏爱 LangGraph 而不是纯 agent loop 的原因复杂流程需要可视化、可控、可回放这恰恰是图结构的强项。4.3 流式输出MCP 工具结果如何持续性反馈在很多真实场景中工具的执行不是一个瞬时动作而是持续性的过程。比如让 Agent 调用一个文件处理工具生成大量输出内容或者调用一个长时间运行的批处理任务。这时候把工具的最终一次性结果交给模型只是最基础的做法更理想的方式是边执行边反馈。LangGraph 在异步执行时支持astream_events可以拿到每个节点的流式事件。当 MCP 工具本身支持流式事件通知时LangGraph 能把这些更新逐步累积进状态模型端可以基于部分结果继续决策。这个特性的实用价值很大但多数教程不深入讲。我的建议是如果你的 Server 端工具要返回长内容比如一组 Web 页面分析结果或大批量数据清洗结果设计成“流式事件 最终汇总”两个阶段而不是一锤子返回完整 JSON。这样 LangGraph Agent 的响应延迟更低对长时间任务的反馈更友好。在实现上langchain-mcp-adapters 的工具返回依然是完整结果流式反馈需要你在 Agent 工具调用外层包装一个事件监听。例如把 MCP 工具包进一个自定义节点节点内调用工具的同时收集 SSE 事件再通过stream_writer写到图状态。这个模式我在本地文件批处理场景中验证过效果非常稳。5. 多 Server 调用架构设计与实战排雷5.1 多 Server 的两种管理模式静态聚合与动态加载在真实项目里挂载多少个 MCP Server 不是拍脑袋决定的而是由工具域边界主导的。我常用的原则是一个 Server 只负责一个领域例如订单系统一个 Server、知识库一个 Server、文件操作一个 Server。这样每个 Server 的工具表清晰独立Agent 路由时不容易混淆。静态聚合就是上面用MultiServerMCPClient把所有 Server 一次性加载成 tools 列表。适合 Server 数量固定、能力边界稳定的项目。动态加载则适用于服务规模变化快的场景。LangGraph 的状态节点可以在运行过程中往 client 里动态注册新的 Server并重新拉取工具列表。但这带来一个并发问题如果两个节点同时修改 client 的工具列表可能会导致 Agent 的工具视图飞掉。我的做法是把 Server 注册和工具拉取放在应用的初始化阶段完成运行期只读如果确实需要在运行期动态调整直接在客户端实例外面包一层管理类加锁控制。5.2 多 Server 带来的并发与隔离问题多 Server 并发调用时最容易踩的坑是工具命名冲突。不同 Server 里可能有同名的工具比如都是search在get_tools()聚合后LangChain 会生成一个唯一名字通常是“server名 工具名”的组合但有时模型会搞混。我建议做两件事一是在定义 Server 时给每个工具起带领域前缀的名字比如order_query、kb_search避免依赖 client 层的 rename 机制二是工具描述里要写明“这个工具属于哪个领域”帮助模型选择。另一个隔离问题是错误处理。一个 MCP Server 挂掉不应该拖垮整个 Agent。在 LangGraph 回调机制里一个工具节点抛出异常时图会进入错误分支。如果这是叶子节点可以选择捕获异常并让模型基于错误信息重新决策但如果挂掉的是连接本身比如 Server 进程死了tools 列表不会自动恢复Agent 会一直使用失效的工具引用。我的解法是在 server 外层做一个健康检查节点定期拉取各 Server 的tools/list验证连通性发现异常时从工具列表里摘除对应 Server 的 tools再重建 Agent。这个逻辑听起来重但真正解决了我一次线上工具失效的问题。5.3 多 Server 配合 LangGraph 的实际案例拆解我用一个具体案例来串一下多 Server 调用的完整链路。假设 Agent 任务用户问“帮我查一下订单 20250101ABC 的物流另外把这个订单的客服备注给我看一眼”。这个任务需要调用两个 Server——订单服务查物流和客服服务查备注。如果它们在同一个 MCP Server 里Agent 只需要一次工具发现但它们属于不同领域按领域拆分会更好。LangGraph 和 MultiServerMCPClient 的组合工作流程是这样的应用启动时初始化 client注册两个 Server拉起各自连接。async with client期间完成 initialize 握手和tools/list拉取。工具聚合用户侧Agent 的模型看到order_track和cs_get_backup_note两个工具。用户提问进入 Agent 图模型决定先调用订单查询工具拿到物流状态。模型了解到订单号与备注的关联继续调用客服工具的查询。Agent 综合两个工具结果生成最终回复。从中可以看出多 Server 的“多”不是让 Agent 一次性同时调所有工具更合理的理解是Agent 在多个工具源之间自主路由。这一步的价值不在于并行而在于统一接入和统一编排。我以前手动为每个数据源写一个 LangChain Tool 包装器后来切到 MCP Server 模式后新增一个能力源只需要加一个 Server 描述和启动配置代码变更量可以忽略不计。6. 常见问题与排查技巧实录6.1 握手失败版本不匹配与初始化遗漏最频繁出现的错误是protocolVersion不兼容。MCP 协议还在快速演进老版 SDK 和新版 Server 之间经常出现版本协商失败。解决办法是升级mcpSDK 到最新版本或者显式在 Server 启动时指定支持版本。日志关键信息是Unsupported protocol version看到这个就可以确认是版本问题。另外一个隐蔽的场景如果你用自定义 Client 连接 MCP Server但没有发送notifications/initializedServer 会一直等待初始化完成的通知后续tools/call会收到错误。排查这类问题时记得在 Client 和 Server 两边同时开 debug 日志观察状态机到了哪一步。6.2 stdio 模式连接失败与进程管理坑stdio 模式下最容易犯的错误是在 Python 进程里用了print()调试。千万记住stdio 模式是通过标准输出传输协议的你的任何print都会污染协议流导致 client 解析失败。解决办法是用logging输出到 stderr或者干脆输出到文件。我之前调试的时候连续排查了半小时才意识到是自己留下的一个print(token_count)破坏了消息格式。另一个是进程生命周期问题。如果本地 Server 崩溃stdio client 不会自动重启。LangGraph 的长生命周期应用里需要监听进程退出事件并考虑用 supervisor 模式重启。用 Docker 部署时建议给 stdio 类 Server 加restart: unless-stopped策略并加健康检查。6.3 工具列表不更新与缓存问题改了一个 MCP Server 的工具定义但 Agent 的行为没变化。绝大多数时候是 client 缓存的工具列表没有刷新。MultiServerMCPClient 内部在初始化时就拉取了工具列表之后不会自动重新拉取。解决方式很简单重启进程或者在新增/删除工具时重建 client。还有一点如果你的 Server 在 HTTP 服务外层挂了缓存注意清理网络层缓存否则tools/list也会拿到旧结果。工具列表不更新的另一个表现是 LangGraph 的输出中出现了“tool not found”。比如模型打印了一个工具名但tools列表里没有。这通常是因为 Server 端工具名与聚合后工具名不一致或者 Server 端更新了工具名但 client 没有重新拉取。我解决这类问题第一步永远是打两份日志一份在 client 的get_tools()后打印工具名列表一份在 Server 的工具调用入口打印收到的 method 和参数。两边一对比问题位置立刻定位。6.4 模型乱调用工具时的调试策略模型调用工具“表现不对”不一定是你代码有 bug而是上下文和工具描述之间出现了语义鸿沟。我常用的调试手段是先把 Agent 图里的模型换成modelgpt-4o并开启verboseTrue把每一步的意图链完整打印出来。如果你发现模型在某个工具的描述里看到了含混词汇但它选择了错误的工具那多半是描述与参数 Schema 设计问题不是 LangGraph 或 MCP 的问题。踩过几次坑之后我形成了自己的规范MCP Server 的工具描述一律采用“做什么 输入是什么 什么时候用 什么时候不用”四段式写法参数一律设置精确的description和examples。这样训练出的 Agent 行为会稳定得多。这个收益在单 Server 上不明显但一旦切到多 Server 协同工具选择混乱的概率会指数下降。我个人在实际操作中最大的体会是MCP 的协议层虽然不复杂但真正决定项目成败的往往是工程层——连接生命周期、缓存刷新、错误隔离、工具语义设计。把这些细节管理好LangGraph 多 Server 调用就不再是“能跑”和“不能跑”的问题而是“稳定”和“可观测”的问题。最后再分享一个小技巧给每个 MCP Server 加一个health_check工具不参与业务只返回服务端时间与状态。这个工具既能用来验证握手也能在 Agent 流程卡住时快速定位是不是连接层出了问题。