★ FEATURED ARTICLE 1. 为什么值得花时间搞懂 MCP 的握手过程第一次接触 MCP 是在一个需要把本地工具链接入大模型工作流的场景里。当时的需求很朴素让模型能调用我本地写好的几个脚本一个负责查数据库、一个负责读文件、一个负责调内部接口。最开始想的是直接写函数调用硬编码进去就完事了。但真动手才发现工具一多、模型一换、调用链一长整个系统就变成了一团乱麻——每个模型有自己的一套函数描述格式每接一个新工具就要改一遍胶水代码调试的时候根本不知道是哪一层出了问题。MCP 就是在这个背景下进入视野的。它的全称是 Model Context Protocol翻译过来叫模型上下文协议。你可以把它理解成一套专门给大模型和外部工具之间设计的通用插座标准。以前每个工具都要为每个模型单独做一个转接头现在大家都按 MCP 这个标准来插上就能用。这个类比可能不够精确但方向是对的MCP 解决的是标准化对接的问题而不是某个具体功能的问题。这篇文章要聊的不是MCP 是什么这种科普层面的东西网上已经有很多了。我想聊的是更实操的两块内容一是协议握手阶段到底发生了什么这部分是很多人调不通 MCP 的根源二是怎么用 LangGraph 同时挂载多个 MCP Server这是从单工具 Demo 走向真实工作流必须跨过的一道坎。如果你已经跑通过一个最简单的 MCP 示例但一到多 Server 场景就各种报错、超时、工具名冲突那这篇内容应该能帮到你。需要提前说明的是MCP 生态还在快速演进不同语言 SDK 的实现细节有差异。我下面讲的内容基于 Python 生态的实践其他语言的同学可以对照着理解原理具体 API 名称以你用的 SDK 文档为准。2. 协议握手一次连接背后到底交换了什么2.1 握手不是打个招呼而是能力协商很多人以为 MCP 的握手就是客户端连上服务端说一句我来了服务端回一句欢迎然后就完事了。实际远比这个复杂。MCP 的握手本质上是一次双向能力声明双方要在这几轮消息里把我支持什么我需要什么我的版本是多少全部对齐。我用一个生活化的场景来解释。你去一家餐厅吃饭进门的时候服务员不会直接给你上菜而是先确认几件事你有没有预约、你几个人、有没有忌口、今天厨房有什么食材。MCP 握手就是这个过程。客户端大模型这一侧要告诉服务端我支持哪些传输方式、我能处理哪些类型的返回内容、我的协议版本号是多少。服务端则要回应我提供哪些工具、每个工具的输入参数长什么样、我支持的协议版本是多少。这里有个关键点协议版本必须匹配。如果客户端说自己是 2024-11-05 版本服务端只支持 2024-10-07 版本握手就会失败。这个失败往往不会给你很明确的提示可能就是一个连接超时或者一个模糊的 JSON 解析错误。我踩过这个坑排查了大半天才发现是版本号对不上。2.2 初始化请求的字段拆解握手的第一步是客户端发送initialize请求。这个请求里通常包含这么几个核心字段protocolVersion客户端使用的协议版本字符串格式通常是日期形式capabilities客户端支持的能力集合比如是否支持 roots、是否支持 samplingclientInfo客户端的名称和版本用于服务端做兼容性判断服务端收到之后会返回一个initialize响应里面包含protocolVersion服务端实际使用的协议版本如果和客户端不一致客户端要决定是否继续capabilities服务端支持的能力比如 tools、resources、prompts 各自是否可用serverInfo服务端的名称和版本我建议你在调试阶段把这两个消息完整打印出来。很多工具调不通的问题根源就在这一步——服务端根本没声明 tools 能力或者客户端没声明它需要 tools结果后面调用工具的时候自然就找不到。2.3 初始化完成后的通知消息握手还有第三步容易被忽略客户端在收到initialize响应后要发送一个notifications/initialized通知。注意这是通知不是请求服务端不需要回复。它的作用是告诉服务端我准备好了你可以开始正常工作了。为什么这一步重要因为有些服务端实现会在收到这个通知之前拒绝处理任何工具调用请求。如果你跳过这一步直接调工具就会收到server not initialized之类的错误。这个错误信息在不同 SDK 里措辞不一样但本质都是握手没走完。下面是一个握手流程的字段对照表方便你排查问题时逐项核对阶段消息类型关键字段常见问题第一步initialize 请求protocolVersion, capabilities, clientInfo版本号写错、capabilities 缺 tools第二步initialize 响应protocolVersion, capabilities, serverInfo服务端未声明 tools 能力第三步initialized 通知无漏发导致后续调用被拒2.4 传输层stdio 和 SSE 的取舍握手消息要通过某种传输方式送出去MCP 目前主流支持两种stdio 和 SSE。stdio 就是标准输入输出。客户端启动服务端进程通过 stdin 发消息、通过 stdout 收消息。这种方式的好处是简单、无需网络配置、进程生命周期好管理。缺点是服务端必须和客户端在同一台机器上而且服务端往 stdout 打印任何非协议内容都会污染消息流。我见过有人在自己写的 MCP Server 里加了一句print(server started)结果整个握手直接崩掉因为客户端把这句话当成了协议消息去解析。SSE 是基于 HTTP 的服务端推送。客户端通过 HTTP 连接到服务端服务端用 SSE 通道往回推消息。这种方式适合服务端部署在远端、多个客户端共享的场景。缺点是网络问题会直接影响握手成功率而且需要处理重连逻辑。我的经验是本地工具用 stdio远端共享服务用 SSE。不要为了看起来高级而强行上 SSEstdio 的稳定性在本地场景下明显更好。另外如果你用 stdio务必确保服务端的所有日志都走 stderrstdout 只留给协议消息。3. 单 Server 跑通之后多 Server 才是真正的考验3.1 为什么单 Server 顺利不代表多 Server 顺利单 Server 场景下你只需要关心一个连接、一套工具列表、一个命名空间。跑通之后很容易产生我已经掌握 MCP 了的错觉。但一旦挂上第二个 Server问题就集中爆发了。最典型的是工具名冲突。假设 Server A 提供一个叫search的工具Server B 也提供一个叫search的工具。在单 Server 场景下这完全没问题但多 Server 场景下模型发出search调用时系统根本不知道该路由到哪个 Server。这不是 MCP 协议的缺陷而是命名空间管理的问题需要客户端侧来解决。第二个问题是生命周期管理。每个 Server 可能是一个独立的子进程stdio 模式你需要确保它们都正确启动、正确关闭、异常时能重启。如果某个 Server 启动失败整个工作流是直接报错还是降级跳过这个策略要提前想清楚。第三个问题是调用超时。不同 Server 的响应速度差异可能很大一个查本地文件的 Server 可能 50 毫秒就返回一个调远端接口的 Server 可能要 5 秒。如果统一用一个超时值要么误杀快 Server要么拖死慢 Server。3.2 LangGraph 里多 Server 的挂载方式LangGraph 本身是一个编排框架它不直接管 MCP 连接而是通过工具节点来调用。常见的做法是先用 MCP 客户端把多个 Server 的工具都拉取下来转换成一个统一的工具列表再交给 LangGraph 的 agent 使用。这里有个设计选择是每个 Server 一个客户端实例还是一个客户端管多个 Server。我推荐前者也就是每个 Server 独立一个客户端连接。原因是隔离性好一个 Server 挂了不影响其他 Server而且每个连接可以有自己的超时配置和重试策略。拉取工具列表的时候要注意把工具名做前缀处理。比如 Server A 的工具统一加a_前缀Server B 的加b_前缀。这样既避免了冲突又让模型在调用时能通过前缀知道该找哪个 Server。代价是工具名变长了但对模型来说这点长度不算什么。3.3 工具描述的质量直接决定调用准确率多 Server 场景下模型面对的工具数量可能是十几个甚至几十个。这时候工具描述的质量就变得极其关键。我见过太多 MCP Server 的工具描述写得含糊其辞比如查询数据这种模型根本不知道什么时候该用它。好的工具描述应该包含三部分这个工具做什么、什么情况下用、输入参数的具体含义。举个例子不要写搜索文件而要写在指定目录下按文件名模式搜索文件支持通配符返回匹配文件的完整路径列表。后者虽然长但模型能准确判断调用时机。在多 Server 场景下我还会在工具描述里加上来源标识比如来自文件服务。这样模型在多个相似工具之间做选择时能多一个判断维度。4. 多 Server 调用的路由与容错设计4.1 工具路由的三种策略当模型发出一个工具调用请求时系统需要决定把它路由到哪个 Server。我实践下来有三种策略各有适用场景。第一种是前缀路由。工具名带前缀直接根据前缀找 Server。这是最简单也最可靠的方案我大部分场景都用这个。缺点是要求所有工具名都规范加前缀需要在一开始就定好规则。第二种是注册表路由。维护一个工具名到 Server 的映射表调用时查表。这种方式灵活工具名可以不加前缀但需要额外维护映射关系而且映射表本身可能成为单点。第三种是广播路由。把调用请求发给所有 Server谁有这个工具谁响应。这种方式最灵活但效率最低而且如果多个 Server 都有同名工具会产生歧义。我只在工具数量很少、且确定不会冲突的场景下用过。实际项目中我通常是前缀路由为主注册表路由作为补充。比如核心工具用前缀一些动态注册的工具用注册表。4.2 超时与重试的差异化配置前面提到不同 Server 响应速度差异大所以超时配置必须差异化。我的做法是给每个 Server 配一个超时值这个值根据该 Server 的历史响应时间动态调整。具体来说初始给一个保守值比如本地文件类 Server 给 2 秒远端接口类 Server 给 10 秒。运行一段时间后统计每个 Server 的 P95 响应时间把超时值设为 P95 的 1.5 倍左右。这样既能容忍正常波动又不会让慢请求拖太久。重试策略也要差异化。对于幂等的查询类工具可以重试 2 到 3 次。对于有副作用的操作类工具比如写文件、发请求重试要极其谨慎最好不自动重试而是把失败信息返回给模型让它决定。我踩过一次坑一个写操作因为超时被自动重试结果写了两遍数据重复了。从那以后所有有副作用的工具我都关掉了自动重试。4.3 单个 Server 挂掉时的降级处理多 Server 场景下某个 Server 挂掉是常态而不是异常。关键是要有降级策略不能让一个 Server 的问题拖垮整个工作流。我的做法是在启动阶段做一次健康检查把不可用的 Server 标记出来它们的工具不注册到工具列表里。运行阶段如果某个 Server 调用失败先重试重试还失败就临时把它标记为不可用并通知模型该工具暂时不可用。模型收到这个信息后可以选择用其他工具替代或者告诉用户当前无法完成。这里有个细节不要把不可用的工具直接从列表里删掉。因为模型可能已经基于之前的对话历史形成了对这个工具的认知突然消失会让它困惑。更好的做法是保留工具但标注当前不可用让模型自己判断。5. 实测中那些文档不会告诉你的坑5.1 stdio 模式下 stdout 被污染这个坑我在前面提过但值得单独展开讲因为它太常见了。stdio 模式下服务端的 stdout 是协议消息通道任何额外的输出都会破坏协议。但很多库、很多框架会默认往 stdout 打印日志比如某些 HTTP 客户端库的调试输出、某些 ORM 的 SQL 日志。我的解决方案是在服务端启动的最开始就把 stdout 重定向到一个缓冲区然后把真正的协议输出写到一个单独的通道。或者更简单粗暴在服务端代码里全局替换print函数让它走 stderr。Python 里可以用contextlib.redirect_stdout把标准输出重定向到 stderr只在需要发协议消息时才写真正的 stdout。5.2 工具返回内容过大导致截断MCP 工具返回的内容会作为上下文传给模型。如果某个工具返回了几兆的文本会直接把上下文撑爆。我遇到过一次一个查日志的工具返回了完整日志文件几万行模型直接报上下文超限。解决办法是在工具实现层面做结果截断和摘要。比如返回日志时只返回最后 N 行或者返回匹配关键字的行。如果确实需要返回大量内容就返回一个引用 ID让模型需要时再通过另一个工具去取具体内容。这个设计思路和分页是一个道理。5.3 并发调用时的连接竞争LangGraph 的 agent 可能会并发调用多个工具。如果多个调用共享同一个 MCP 客户端连接就可能出现消息交错、响应错配的问题。我遇到过一次两个工具调用几乎同时发出结果响应回来的时候对不上号A 的响应被当成了 B 的。解决方式是每个调用用独立的连接或者在客户端侧做请求 ID 匹配。MCP 协议本身有请求 ID 机制但有些简易实现没有正确处理。如果你自己写客户端务必确保每个请求有唯一 ID响应回来时按 ID 匹配。如果用现成的 SDK确认它是否支持并发不支持的话就加锁串行化。5.4 工具参数校验的缺失MCP 协议允许服务端声明工具的输入 schema但很多实现只是声明了并没有真正校验。结果就是模型传了错误的参数类型服务端直接崩溃或者返回莫名其妙的错误。我的做法是在服务端工具实现的最外层加一层参数校验用 JSON Schema 或者 Pydantic 之类的工具做严格校验。校验失败时返回明确的错误信息告诉模型哪个参数不对、期望什么类型。这样模型能自我纠正而不是反复用同样的错误参数重试。6. 从能跑到好用几个提升稳定性的实践6.1 给每个 Server 加健康探针不要等到调用失败才发现 Server 挂了。我给每个 Server 加了一个轻量的健康探针定期发一个最简单的请求比如列出工具列表看是否正常响应。探针失败达到阈值就把 Server 标记为不健康暂停路由到它的请求。探针的频率不用太高30 秒一次就够了。太频繁会增加负担太稀疏又起不到及时发现的作用。探针本身也要有超时避免探针自己卡住。6.2 记录完整的调用链路日志多 Server 场景下出问题时最痛苦的是不知道问题出在哪一层。我现在的做法是给每次工具调用生成一个 trace ID从模型发出请求、到路由决策、到 Server 处理、到返回结果每个环节都带上这个 ID 打日志。这样排查时能完整还原一次调用的全过程。日志里要包含的关键信息调用的工具名、路由到的 Server、请求参数、响应内容或摘要、耗时、是否成功。这些信息在排查超时、错配、参数错误时都用得上。6.3 工具列表的缓存与刷新每次对话都重新拉取所有 Server 的工具列表开销不小。我的做法是启动时拉一次缓存起来然后定期刷新。刷新时如果发现工具列表有变化就更新缓存并通知 agent。这里要注意缓存失效的处理。如果某个 Server 挂了刷新时拉不到它的工具不能直接把它的工具从缓存里删掉而是标记为不可用。等 Server 恢复后再重新标记为可用。6.4 用配置驱动而不是硬编码多 Server 的配置项很多每个 Server 的启动命令、传输方式、超时、重试策略、前缀。这些千万不要硬编码在代码里。我用一个 YAML 配置文件管理所有 Server 配置代码只负责读取配置并初始化。这样加一个新 Server 只需要改配置不用动代码也方便在不同环境之间切换。配置文件的格式大概是这样每个 Server 一个条目包含 name、transport、commandstdio 模式、urlSSE 模式、timeout、prefix 等字段。启动时遍历配置逐个初始化。7. 关于这套方案后续还能怎么演进多 Server 跑通之后我下一步想解决的是工具的动态发现。现在的做法是启动时确定所有 Server运行中不变化。但实际场景里有些工具是临时可用的比如某个数据处理任务启动后才有的工具。如果能支持运行时动态注册和注销 Server会更灵活。另一个方向是工具调用的成本感知路由。同一个功能可能有多个 Server 都能提供比如本地缓存 Server 和远端 Server 都有查询能力。可以根据响应速度、成本、当前负载来决定路由到哪个。这个在工具数量多、调用频繁的场景下价值很大。还有一个我觉得很有意思的点是工具组合。现在模型是一次调一个工具但很多任务需要多个工具配合。如果能定义一些组合工具内部编排多个 MCP 调用对模型来说就是一个工具会大大降低模型的编排负担。LangGraph 本身擅长做这种编排把 MCP 工具作为节点组合逻辑用图来表达这条路我觉得值得深挖。最后分享一个我在调试 MCP 时常用的小技巧先用一个最简单的 echo 工具把整条链路跑通。这个工具不查任何数据、不调任何接口就是原样返回输入。用它来验证握手、传输、路由、返回这一整条链路是否正常。链路通了之后再逐个替换成真实工具。这样能把链路问题和工具实现问题分开排查效率高很多。我见过太多人一上来就接复杂工具结果报错之后根本分不清是握手没走通还是工具本身有 bug。
阅读完成 · 觉得有帮助？
