我第一次把 MCP 串进 LangGraph 的时候最直观的感受是这玩意本质上不是在“接一个工具”而是在把 AI Agent 的“手和眼睛”拆成独立服务再通过一套统一的协议把权限、数据、行为全部管起来。MCPModel Context Protocol最近在 AI 工程圈子里火得非常快GitHub 上相关仓库几乎每周都有新动作LangGraph 也在原生支持 MCP 工具接入许多团队已经从“给模型塞几个 function”转向“多个 MCP Server 按需调度”。这篇分享我从最底层的话题聊起——MCP 的协议握手是怎么完成的Server 和 Client 是怎么建立互信的然后讲清楚在 LangGraph 里做多 Server 调用时的方案选型和真实踩坑。文章不端着讲概念直接从实操出发适合对 LangGraph 有一定了解、想认真用 MCP 构建工具链的人参考。1. 先把 MCP 这件事想清楚它到底解决什么问题1.1 从“一个模型要对接一堆工具”说起如果你拆过某个 Agent 项目大概率见过这种场景代码里写了一大堆函数每个函数都要手工声明参数名、类型、描述然后想尽办法塞进 prompt让模型知道什么时候该调用哪个。这种做法在工具数量少的时候勉强能跑一旦工具超过十几个问题就出现了——Prompt 越来越长模型开始频繁选错工具参数名冲突让每次调试变成噩梦而工具本身的鉴权、超时、错误处理全都要自己重新造一遍。MCP 的思路是反过来的把每个工具能力做成一个独立 Server通过标准协议向外暴露“工具清单”和“调用入口”客户端也就是 Agent 框架在运行时去动态发现、按需调用。这样做最大的收益是解耦。业务团队可以只维护自己的 MCP Server不必关心 Agent 框架内部怎么组织 PromptAgent 侧则可以像插 USB 设备一样把各种工具服务挂进来不用为了新增一个数据源去改主代码。我见过不少团队用这个思路把内部报表、数据库查询、审批流全都封装成了 ServerAgent 端代码基本不动。1.2 MCP 设计的核心思路把工具能力做成可插拔服务MCP 的设计整体上借鉴了 LSPLanguage Server Protocol的思路很多人应该熟悉 LSP 是怎么把代码补全、跳转、诊断从编辑器里剥离出去的。MCP 做的事情类似只不过它把“语言能力”换成了“外部工具和数据操作”。理解 MCP 的关键是在脑子里建立一个分层模型最上层是 Agent 或 AI 应用中间是 MCP Client负责协议交互和生命周期管理最底下是多个 MCP Server 进程。每个 Server 独立运行可能在本机也可能在远程它们之间通过 JSON-RPC 2.0 格式的消息通信。协议本身是传输无关的你可以用 stdio 跑本地进程也可以用 HTTPSSE 走远程服务。这一点对落地非常重要因为很多场景下业务系统并不适合整进 Agent 主进程独立部署的 Server 反倒能顺便解决安全边界、并发隔离、权限控制这些问题。1.3 先分清关键角色Server、Client、Tool、Resource很多人第一次接触 MCP 会被一堆名词绕晕我的建议是先抓住四个核心概念MCP Server提供具体能力的服务进程。比如一个“查询订单”Server内部对接数据库或内部 API。MCP Client与 Server 建立会话的客户端通常是 LangGraph、LangChain 这类框架里的一部分。Client 负责发送 initialize 请求、获取工具列表、触发调用。Tool工具可以被模型调用的操作结构上是一个带名称、描述、输入 schema 的函数。Resource资源暴露给模型读取的数据片段或文件内容。Tool 偏“动作”Resource 偏“数据”两者在协议上走不同的消息原语。在后续章节里我会反复使用这几个词先有个基础认识后再往下听握手的细节会顺很多。这里也想给新手一个建议不要把 MCP 和“插件”画等号。插件通常是把代码打包进宿主程序而 MCP 是跨进程的服务化交互调试方式、部署形态、故障隔离逻辑都很不一样。2. 协议握手机制拆解从连接到就绪到底发生了什么2.1 握手的三个关键消息initialize、result、initialized我第一次手动抓 MCP 协议包的时候最大的感慨是握手的步骤比想象中简单但一旦漏了细节客户端永远等不到工具列表。MCP 协议握手不是 TLS 那种复杂的加密协商而是基于 JSON-RPC 的三步走客户端发送initialize请求带上自己支持的协议版本、客户端标识、能力声明。Server 返回initializeresult里面包含 Server 支持的协议版本、Server 信息、能力列表。客户端再发送一条notifications/initialized通知告诉 Server“我这边已经准备就绪”。这里有个容易踩的坑第三步是一条 notification 而不是 request也就是说它不需要 Server 返回结果。很多人第一次写 MCP 客户端时习惯性等一个 ack结果把流程卡死了。另外协议版本协商并不是强制的——Server 返回的版本可以在客户端声明版本之上取交集如果完全不兼容Client 应该主动挂断并提示原因。我自己在本地调试时观察到的实际交互长这样两台进程之间的 JSON-RPC 消息// 客户端发出去的第一条 {jsonrpc:2.0,id:1,method:initialize,params:{ protocolVersion:2025-06-18, capabilities:{tools:{listChanged:true}}, clientInfo:{name:langgraph-agent,version:0.1.0} }} // Server 回应 {jsonrpc:2.0,id:1,result:{ protocolVersion:2025-06-18, capabilities:{tools:{listChanged:true}}, serverInfo:{name:order-query-server,version:1.2.0} }} // 客户端最后发出去的通知不期待返回 {jsonrpc:2.0,method:notifications/initialized, params:{capabilities:{}}}这个过程跑通之后客户端才能继续调用tools/list。在实际工程里我通常会把握手封装成一个带超时的函数失败了就重启 Server 或记录错误日志避免 Agent 主流程被一个不健康的后端进程拖死。2.2 从tools/list到tools/call发现工具与调用工具握手完成后客户端会调用tools/list获取该 Server 支持的全部工具。这一步返回的内容决定了大模型能看到什么、能调用什么。返回的结构里每个工具至少包含名称、描述、输入 schema通常是 JSON Schema。这里有一个被很多人忽略的细节工具描述的质量直接决定模型选择工具的准确率。同一个功能描述写得模棱两可模型匹配错误的概率会明显上升。我一般会在内部规范里要求每个工具必须说清楚“在什么业务场景下使用、和哪个工具有区别、输入参数的单位和范围是什么”。tools/call是最终的执行入口参数结构是{name: 工具名, arguments: 具体参数对象}。Server 执行完返回的内容可以包含content数组里面每一项有类型如 text、image、resource_link和具体数据这是真正回到模型那边作为上下文的内容。这里踩过的一个教训是很多初版 Server 会把内部数据结构原样返回比如数据库查询结果里带着 Null、枚举数字之类的垃圾信息。模型拿到这种内容不仅推理会乱回答质量也会急剧下降。我在设计 Server 的输出时会先做一层“面向消费端”的整形把模型真正需要的关键信息提取成自然语言式的摘要。2.3 容易被忽略的能力协商生命周期不只是握手比“三次握手”更深一层的能力协商很多人会忽略。MCP 协议里 Server 和 Client 都会声明自己的 capabilities比如客户端声明自己是否支持采样sampling、Server 声明自己是否支持资源订阅、日志记录等。双方在握手结果里互相确认之后后续流程必须遵守这些边界。举个例子如果 Client 没有声明支持samplingServer 就不能反过来向 Client 请求模型补全。如果 Server 没有声明resources.subscribeClient 就不能订阅它的资源变化。这类“越权”操作在调试期不会立刻报错但会在一些边缘场景引发奇怪的现象——比如资源明明更新了Agent 却一直读到旧数据。我建议你在接任何一个 MCP Server 时先把协议里 capability 的字段含义查一遍确认你依赖的高级特性在双方能力列表里都存在。还有生命周期管理的问题。MCP Server 进程并不会因为你完成了 initialize 就一直稳稳运行它可能崩溃、可能响应超时、可能被资源管理器杀掉。所以工程化的 MCP 客户端一定要具备探活、重连、退避重试机制。在 LangGraph 里跑多个 Server 时我通常会为每个 Server 外包一层连接池任何一次握手失败都触发独立的重连逻辑而不是让整个 Agent 流程停下来。3. 搭建 MCP Server 的实战从零实现一个可用的工具服务3.1 选型Python SDK、TypeScript SDK还是裸写协议目前 MCP Server 的主流实现方式有三种官方 Python SDK、官方 TypeScript SDK以及完全基于 JSON-RPC 手写协议。对于大多数人我的建议是优先用 SDK理由很简单协议里包含大量细节比如消息 id 分配、批量通知、能力协商手写非常容易出错调试成本高得离谱。但如果你所在的团队要在某种特殊运行时里嵌入 MCP比如移动端或者需要极致的体积控制那手写协议也不是不可以前提是充分理解握手和消息格式。以 Python 为例官方 SDK 提供的核心抽象是FastMCP和Server两个层级。FastMCP更贴近业务开发——你只需要写普通函数套一个装饰器它就自动把函数转成符合 MCP 规范的 tool。Server层级则适合需要精细控制协议行为的场景比如自定义鉴权、自定义资源目录、多协议版本兼容。我团队的惯例是内部小工具都用 FastMCP对外暴露给 Agent 核心链路、对稳定性要求高的服务会用 Server 层手工管理能力列表。3.2 用 FastMCP 十分钟搭一个订单查询 Server假设我们要做一个“订单查询”工具服务最基本的信息包括订单号、用户标识、下单时间。用 FastMCP 写起来非常简单from fastmcp import FastMCP mcp FastMCP(order-query-server) mcp.tool() def query_order(order_id: str) - str: 查询订单基础信息适用于客服、售后等场景输入订单号返回状态、金额、时间。 注意本工具只返回最近一年的订单跨年订单请使用 query_order_archive。 # 这里只是示意实际会去调内部订单服务 order fetch_order(order_id) if not order: return f未找到订单 {order_id} return f订单 {order_id} 状态{order[status]} 金额{order[amount]} 时间{order[created_at]}需要注意的细节有几个。第一函数名直接映射为工具名所以命名要清晰、唯一。第二docstring 会被解析成工具的 description你可以看到我在描述里主动写了“跨年订单要用另一个工具”这比模型自己猜靠谱得多。第三参数类型要带完整的类型标注FastMCP 会根据类型签名生成 JSON Schema。如果你用了*args或缺失类型生成出来的 schema 会很难看模型也可能因此传错参数。在真实业务中Server 内部大概率要访问数据库或微服务 API。我的建议是不要把复杂的鉴权逻辑写进 MCP Server 里而是让 Server 只做“协议翻译”把内部服务返回的数据转换成模型友好的格式。像订单查询这种场景你真正想返回的可能是“订单 SN、状态、支付时间、物流单号”这几项而不是把整条原始记录都塞过去。3.3 本地调试技巧MCP Inspector 真的很能说明问题MCP 调试的时候最怕的就是“客户端黑盒”你根本不知道它到底发了什么请求、Server 有没有正确返回。官方提供了一款可视化调试工具叫 MCP Inspector可以直接通过 npx 启动然后连接你的本地 Server。npx modelcontextprotocol/inspectorInspector 的界面里能看到三个核心信息连接状态、可用的工具列表、以及历史消息记录。每次调用工具时左侧会展示完整的 JSON-RPC 请求右侧展示 Server 返回。我调试时最爱看的是消息记录里的合法性检查——比如某个 notification 错用了 request 格式Inspector 会直接提示协议错误省去你对着文档逐行核对的时间。除了 Inspector你也可以自己在 Server 端加一个消息日志中间件把收到的每条 JSON-RPC 消息都记录到文件。这样在生产环境出现问题时可以还原客户端到底给 Server 发了什么。一个常见的定位方法是“串行复现”把线上日志里记录的某一次tools/call请求原样发给本地 Server观察是否复现问题。如果是说明 Server 侧处理逻辑有 bug如果否那问题多半出在客户端或网络环境。3.4 Server 的部署形态stdio 与 HTTP 两种方式对比MCP Server 支持的传输方式直接决定了你如何部署。我在本地开发时几乎全用 stdio——启动一个子进程通过 stdin/stdout 通信这样不用管端口、网络安全调试最方便。放到服务器上之后我偏向用 HTTPSSE 暴露服务因为这样可以做负载均衡、权限控制、日志审计还能跨机器给多个 Agent 共享同一组 Server。对比维度stdioHTTP SSE启动方式客户端拉起子进程独立服务监听端口适用场景本地开发、单机 Agent多 Agent 共享、集中管理权限控制依赖进程权限可在网关层统一管控故障隔离子进程崩溃影响主进程服务独立隔离更好调试难度简单直接需要抓包、看网关日志把 Server 变成远程服务之后要特别注意超时设置。本地 stdio 进程之间消息几乎是瞬时到达远程服务则有可能因为网络抖动、服务负载而几秒不返回。我在 LangGraph 里通常会为tools/call设置 10 到 30 秒的硬超时具体看业务场景。数据库查询类工具适当放宽前端交互类工具设置更短避免用户体验被拖垮。4. LangGraph 里的多 Server 调用从单工具到工具编排4.1 LangGraph 如何把 MCP 工具变成可编排的节点LangGraph 的核心概念是状态图而 MCP 工具实际上被封装成了图上的节点动作由 Agent 模型决定何时触发。与直接在一个大循环里调函数不同LangGraph 强调状态流转和条件分支所以它的工具调用并不只是“让 LLM 选个函数执行”而是把一次工具调用理解成图中的一个节点状态变化。举个例子一个简单的客服 Agent 可以设计成接收用户问题 → 判断意图 → 如果涉及订单查询就走订单节点 → 如果涉及物流信息就走物流节点 → 汇总回答。每一个节点背后都可能对应一个独立的 MCP Server。LangGraph 负责状态管理和图执行顺序MCP 负责具体动作执行两者天然互补。在写代码之前我会先想清楚图的拓扑结构。不是所有工具都适合让模型自由选择有些工具应该由前置节点做好路由再强制执行。比如订单查询之后必然要查物流那么就可以把“订单查询 → 物流查询”设计成一条确定路径而不是每次让模型重新决定。这种确定性与模型自由的平衡是 LangGraph 编排多 Server 的核心艺术。4.2 多 Server 的接入方式聚合层与路由层真正在一个 LangGraph 应用里跑多个 MCP Server有几个方案可以做方案一多 Client 并列。每个 Server 对应一个独立的 MCP ClientLangGraph 通过不同的工具名前缀区分来源。这种方案最灵活每个 Server 可以有自己的连接配置、认证方式、健康检查但需要自己维护多个 Client 的生命周期。方案二单一聚合 Client。自己写一个聚合层它内部连接多个 MCP Server对外统一暴露工具列表。LangGraph 只需要面对一个 Client工具的归属由聚合层内部决定。好处是 LangGraph 侧代码简洁坏处是聚合层要处理协议差异和工具冲突。方案三工具名前缀隔离。这是最常用的做法。比如订单 Server 的工具命名为order_query、order_cancel物流 Server 的工具命名为logistics_track、logistics_route。LangGraph 的模型看到的是带前缀的工具列表天然就能区分来源服务器。我在实践中的做法通常是把方案一和方案三结合每个 Server 一个 Client同时强制工具命名带业务前缀。LangGraph 侧则维护一个“Server 注册表”包含每个 Client 的状态、工具列表、超时配置和重试策略。下面是一段示意图的伪代码展示 LangGraph 如何把多个 MCP Client 并进来from langchain_mcp_adapters.tools import load_mcp_tools from langgraph.prebuilt import ToolNode # 每个 MCP Server 对应一个 client order_client MCPClient(order-server, transportstdio, commandpython order_server.py) logistics_client MCPClient(logistics-server, transporthttp, urlhttp://localhost:8022/sse) order_tools load_mcp_tools(order_client, prefixorder_) logistics_tools load_mcp_tools(logistics_client, prefixlogistics_) # 合并后交给 LangGraph all_tools order_tools logistics_tools tool_node ToolNode(all_tools)这段伪代码里最关键的是prefix参数和ToolNode的整合。通过给不同来源的工具加上不同前缀模型在推理“该调用哪个工具”时就不会混淆。同时如果某一批工具在 Agent 会话中始终不会被用到甚至可以不预加载LangGraph 也支持按需加载工具列表这样能减少每次推理时对模型输出 token 的挤占。4.3 多 Server 调用的核心难点状态传递与上下文管理当我第一次把两个 Server 串进 LangGraph 时最大的坑不是协议也不是工具定义而是状态如何在不同节点间传递。MCP 工具返回的是字符串或结构化内容LangGraph 的上一个节点拿到这个内容后怎么把它转换成下一个节点需要的输入这个转换逻辑如果放在 Agent 的思考循环中就会造成模型需要“记住”太多中间状态既消耗 token又容易出错。我的解法是在 LangGraph 的状态对象里维护一个tool_results字段用于保存最近几轮工具调用的核心结果摘要。在每个工具节点返回之后用一个轻量级的摘要节点把冗长结果压缩成 200 字以内的结构化文本。这样模型下轮推理时只需读取摘要不需要重新解析整段原始返回。这样做还有一个好处当一个 MCP Server 调用失败时摘要节点可以把错误信息也压缩成标准格式放进状态供后续的异常处理分支读取。实际项目中另一个容易出错的地方是并发问题。LangGraph 允许多个节点并行执行但 MCP Server 往往有状态或者针对同一用户的请求需要有先后顺序。比如“取消订单”和“查询订单”同时触发就可能出现竞态条件。这种情况下我会在 LangGraph 图里显式给相关节点加边让它们串行执行或者用“互斥锁节点”控制同一业务对象的访问。4.4 多 Server 场景的工具冲突与任务路由多个 Server 并进来工具重名的概率很低但逻辑上发生冲突的概率极高。比如订单 Server 里有一个get_user_info客户 Server 里也有一个get_user_info模型很容易选错。更隐蔽的冲突是“功能职责重叠”比如“查询订单状态”既可以在订单 Server 实现也有可能在 CRM Server 里有一个类似入口。这时模型的表现会变得很不稳定有时候调这个有时候调那个返回结果可能完全不一样。应对办法是管控模型的选择空间。我在 LangGraph 里设计工具路由时会用一个“意图识别节点”先做粗粒度分类再根据分类结果把可用的工具子集传给模型。具体到图里就是给不同的工具子集挂在不同的分支节点上让模型在每个分支内只看到局部工具列表。这样做既减轻了模型的选择压力也让同一功能只在一个 Server 中暴露天然避免职责重叠。任务路由还有一种更高阶的玩法同一类工具在多个 Server 中都存在但提供的是不同区域的覆盖范围。这时需要用用户属性比如租户 ID、地域做路由决策。我在一个国际化项目中就是这样做的不同区域的订单 Server 是独立部署的工具前缀带区域代号路由节点根据用户 IP 归属把请求导向对应区域的工具节点。LangGraph 的图结构非常适合这种按照环境变量做条件路由的设计。5. 常见问题与排查技巧实录5.1 握手失败初始化始终等不到 result这类问题在把 MCP 接进 LangGraph 时出现频率最高。我整理过一个速查表基本覆盖了大多数初始化挂起的情况。现象可能原因处理方式initialize 发出后无响应Server 启动崩溃或 stdout 被业务日志污染检查 Server 启动日志确保协议消息不混入 print 输出收到 result 后 initialized 通知卡死客户端把 notification 当 request 等待结果确认发送方式是否是异步通知不需要等待 ack工具列表拉取为空Server 没有正确注册工具或注册函数参数格式不符在 Server 端直接调用工具列表函数查看是否返回连接秒断并反复重连协议版本不匹配能力协商失败检查 protocolVersion 是否在双方支持列表内这里特别提一下 stdio 模式下最典型的坑print污染。FastMCP 之类的 SDK 会把所有日志输出重定向到 stderr但如果你在业务代码里直接print调试信息这些内容就会混进 stdout导致客户端解析 JSON-RPC 消息失败。我在团队里定的规矩是MCP Server 业务代码一律用 logging、输出到 stderr 或日志文件绝对不碰 stdout。这个习惯能省掉大量排查时间。5.2 工具调用超时与返回格式不可解析工具调用超时不一定代表 Server 慢很多时候是模型端把工具参数选错了Server 拿着错误参数去查询数据库或外部 API 迟迟不返回。我的排查思路是先把“模型选择参数”和“Server 执行”两件事分开。在 LangGraph 里我会在 ToolNode 外面包一层日志装饰器记录每次tools/call实际收到的 arguments。如果 arguments 离谱比如把“order_id”传成了“user_id”那问题多半出在 schema 设计上——要么参数名不够语义化要么工具的 description 没有把约束写清楚。返回格式不可解析则大多出在 Server 端返回了非标准 JSON-RPC 结构。比如很多人会把业务错误直接写成{error: database down}但 MCP 协议要求的tools/callresult 里必须包含content数组。一旦结构不符LangChain 的适配器会直接抛异常。解决办法是在 Server 端统一做结果包装把异常的堆栈信息也转成 content 文本内容返回模型反而能理解“数据库不可用”这类状态比接收到协议解析错误更有意义。5.3 多 Server 场景下的权限与隔离问题多 Server 调用时权限控制是个容易被忽视但又非常要命的问题。如果每个 Server 都是用同一个系统账户启动那 Agent 一旦被诱导调用某个危险工具等于拿到整台机器的权限。我在真实项目中踩过这种坑测试环境的 Server 用了管理员账户跑后来发现某个工具可以读文件系统任意路径直接把整个测试库配置翻了个底朝天。现在的普遍做法是每个 Server 用最小权限账号运行Server 进程之间互相隔离。如果走 HTTP 传输还要在网关层做 API Key 校验和来源 IP 白名单。从 LangGraph 侧来看还有一个细节是“工具白名单”而不是“全部暴露”。接进来的 MCP Server 往往自带十几个工具但当前 Agent 可能只需要其中三个。我会在聚合层写一个 filter只把需要的工具暴露给模型避免模型去做超范围的调用。5.4 排查工具箱日志、断点、串行复现三板斧最后分享一个我用了很久的排查套路。遇到 MCP 相关疑难杂症按以下顺序走大多数问题能在半小时内定位。第一把日志级别调到 DEBUG。MCP SDK 几乎都支持详细协议日志输出。LangGraph 侧可以看到每次工具调用的输入输出摘要MCP SDK 侧可以看到原始 JSON-RPC 消息。两端日志对不上的时候问题一定出在中间层网络或进程管道。第二在 Server 侧打断点或加临时日志。特别当你在用 FastMCP很多内部逻辑被封装掉了出问题时无法从外部判断是参数校验失败还是业务逻辑抛错。在关键函数入口打日志记录入参和返回能快速缩小范围。第三串行复现。从日志里把一次失败请求摘出来通过 MCP Inspector 或直接写一个最小客户端只发那一条请求给 Server观察是否复现。这一步能强制区分“协议问题”和“业务问题”。如果最小客户端能复现那 Server 端逻辑有毛病如果不能多半是 LangGraph 那边的参数变换、环境变量或并发状态污染了请求。6. 关于 LangGraph 多 Server 编排我还想补充的三个经验6.1 不要急于把所有工具都接进来MCP 让接工具变得太简单了反而容易让你失去克制。我见过一个团队第一次接入 MCP 时一口气挂上了十几个 Server工具列表上百个。结果模型每次推理时光扫描工具描述就需要消耗大量 token而且选择准确率明显下降。工具不是越多越好每个 Agent 应该只面对与当前任务最相关的一组工具。LangGraph 的优势在于可以用条件分支把工具列表“按需点亮”而不是让它们全局可见。6.2 每个 Server 都应该有独立的故障处理策略多个 Server 意味着多个故障点。任何一次外部服务抖动都可能导致节点挂起或数据不对。我在 LangGraph 的图里给每个工具节点都加了错误分支捕获到异常后进入“降级回答”节点用预设文案告知用户当前服务不可用同时把具体技术原因记录到可观测系统。有些任务允许失败重试有些任务需要告警人工介入——这些策略要按 Server 的重要性逐个定而不是全部塞给模型自主判断。6.3 测试环境与生产环境的 Server 参数一定分开最后这个经验来自一次惨痛的线上事故。测试环境的 MCP Server 用的协议版本和生产环境的不一致而代码里协议版本是硬编码的。联调时一切正常一上生产握手直接失败。从那以后我要求项目里所有 MCP Server 的协议版本、超时时间、连接地址全部由环境变量注入测试环境与生产环境参数独立配置。MCP 本身是个协议层标准但工程化落地依赖的全是这类细致的环境管理这部分没有捷径可走。在 LangGraph 这类框架里做多 Server 调用最有意思的地方在于你同时要操心底层协议细节和上层任务编排逻辑。协议没握手成功一切上层编排都是空中楼阁工具编排不清晰协议再稳也发挥不出价值。希望这篇分享能帮你把这两层都踩踏实。