MCP 这个圈子今年是真的热闹光是“mcp是什么”这类搜索就天天有人在问。但光知道概念没用真到自己上手把 MCP Server 接进 LangGraph 流程里你会发现坑全藏在细节里——尤其是从协议握手到多 Server 调用这一段文档写得云里雾里网上教程各说各话抄作业都抄不齐。这篇东西我憋了挺久把从零开始理解 MCP 协议握手、到在 LangGraph 里同时挂载多个 Server 的完整过程捋了一遍含代码、含配置、含报错排查。适合刚摸到 MCP 边缘的开发者也适合已经被多 Server 调用折磨到怀疑人生的同学。1. MCP 到底在解决什么问题它的设计思路是什么1.1 MCP 是什么以及它凭什么值得学MCP 的全称是 Model Context Protocol模型上下文协议。你可以把它理解成 AI 应用世界的 USB-C 接口——过去你想让大模型调用某个工具、读某个数据库、操作某个软件就得针对每个工具写一套私有集成代码换个工具就得重写一遍。MCP 想做的就是把“模型怎么跟外部工具对话”这件事标准化。它解决的核心痛点是工具接入的重复劳动。比如你今天接了一个 SQL Server 查询工具明天又要接一个 Playwright 浏览器自动化工具后天还要接 Altium Designer 的 PCB 检查接口。如果每个都单独写适配层那工作量是线性增长的而且每个适配层都要处理通信、鉴权、错误重试这些杂活。MCP 把所有这些收敛成一套协议模型侧只需要学会怎么通过 MCP 客户端跟 Server 通信工具侧只需要实现一套 MCP Server 接口。这就像家里所有电器都换成了同一个插头标准你不再需要为每个电器准备一个专属转接头。1.2 为什么 LangGraph 需要多 Server 调用LangGraph 本身是一个编排大模型应用流程的框架它擅长把复杂的任务拆成节点和边让模型在节点之间跳转。但 LangGraph 本身不产工具它需要外部能力——查询数据库、调 API、操作浏览器、读文件等等。这些能力如果全都塞进一个 MCP Server 里很快会变成一个大杂烩权限边界模糊、单个工具挂了影响全局、代码维护起来想骂人。合理的做法是按领域拆分 Server一个负责数据查询一个负责文件操作一个负责网页自动化。每个 Server 独立部署、独立升级LangGraph 作为调度中心统一调用。这就是“多 Server 调用”的真实场景。我见过不少人在这一步翻车不是因为 LangGraph 难而是因为对 MCP 的通信机制理解不透。所以后面我会先从协议握手讲起把最底层的东西搞明白再去碰 LangGraph。2. MCP 协议握手的核心机制与实操细节2.1 握手到底在握什么MCP 的通信底层用的是 JSON-RPC 2.0这是一种很轻量的远程调用协议请求和响应都是 JSON 格式带 id、method、params、result 这些字段。MCP 在此基础上定义了自己的方法集。握手的第一步是客户端给 Server 发一个initialize请求。这一步非常关键它起了三个作用确认协议版本兼容、交换双方能力信息、建立后续通信的上下文。我的经验是很多人在自测 MCP Server 时直接就用tools/list去调结果返回一堆错误原因就是跳过了initialize。Server 端在没收到合法的 initialize 之前一般不会把你当成合法客户端更不会让你列工具。握手流程拆开看是这样的客户端发送initialize带上协议版本和客户端能力描述Server 返回自己的协议版本、Server 能力描述、以及一个 session 标识客户端再发一个notifications/initialized通知告诉 Server“我已经准备好可以开始正式工作了”之后双方才能正常进行tools/list、tools/call、resources/list这些操作这里有个细节容易被忽略notifications/initialized是通知不是请求它没有响应。有些新手会在这儿傻等 Server 的回包等不到就以为连接断了。实际上这个通知发出去Server 收到就算完事。2.2 三种传输方式怎么选MCP 协议支持多种传输层实现日常接触最多的是这三种stdio、HTTPSSE、以及基于 Streamable HTTP 的现代传输。stdio是最简单的起步方式Server 作为子进程被客户端拉起双方的通信走标准输入输出。好处是零网络配置本地调试很方便坏处是没法跨机器调用。HTTPSSE是老牌方案客户端通过 POST 发请求Server 通过 SSE 单向推送事件给客户端。适合跨网络部署、需要鉴权的场景。Streamable HTTP是后面推的新方案改进了 SSE 的一些限制支持双向流式通信很多新 SDK 已经默认走这条路。选型建议很简单本地开发用 stdio部署到服务器上给远程 LangGraph 服务调用就果断用 Streamable HTTP。我踩过最大的坑就是在服务器上用了 stdio 传输结果 LangGraph 进程和 MCP Server 进程不在同一个主机上连接直接失败。切记stdio 只能在同一个进程树里用。2.3 一次完整的工具发现与调用过程握完手之后真正的工作流是工具发现和工具调用。工具发现走tools/listServer 会返回一个工具清单每个工具包括名字、描述、输入 schema。这个 schema 用的是 JSON Schema 格式描述参数的结构和校验规则。工具调用走tools/call客户端把工具名和参数传过去Server 返回执行结果。结果里有两个字段值得注意content是实际内容isError标记这次调用是否出错。我在做 LangGraph 集成的时候把工具发现做了缓存——进程启动时拉一次工具列表之后不再反复请求。原因很简单tools/list虽然不重但每次调用都走一遍 JSON-RPC 往返在高频场景下白白增加延迟。工具的增删改一般需要重启 Server 或动态刷新机制平时稳定不变。3. 多 Server 架构的设计与 LangGraph 集成方案3.1 多个 Server 的目录结构与配置管理多 Server 不是把代码堆在一起就行从一开始就要规划好工程结构。我的习惯是一个 Server 一个目录每个 Server 独立声明自己的依赖再在根目录放一个统一的配置文件记录所有 Server 的注册信息。下面是我常用的目录结构mcp-servers/ ├── sql-server/ # SQL Server 查询 Server │ ├── server.py │ └── config.json ├── playwright-server/ # 浏览器自动化 Server │ ├── server.py │ └── config.json ├── filesystem-server/ # 文件系统操作 Server │ ├── server.py │ └── config.json └── mcp-config.json # LangGraph 侧的全局配置mcp-config.json长这样{ mcpServers: { sql: { command: python, args: [sql-server/server.py], transport: stdio }, playwright: { url: http://localhost:9000/mcp, transport: streamable-http }, filesystem: { command: python, args: [filesystem-server/server.py], transport: stdio } } }这份配置是 LangGraph 侧读取的每个条目代表一个 Server。用mcpServers这个键名是行业惯例很多 MCP 客户端都认这个格式所以命名上尽量不要改。3.2 为什么按领域拆分 Server而不是按功能粒度拆分有人会问我把每个工具单独做一个 Server 行不行技术上可以但运营上是噩梦。Server 数量多了之后连接管理、鉴权配置、日志追踪全都会变成新的问题。按领域拆分的核心逻辑是一个 Server 代表一个稳定的能力边界。SQL Server 只负责数据查询你换数据库、调 SQL 优化只动这一个 ServerPlaywright 负责浏览器操作这个 Server 挂了不影响数据库查询文件系统 Server 单独控制读写权限安全审计也清晰。举个例子如果我把“读取订单表”和“读取用户表”分别做成两个 Server技术上是可行的但以后要做个统一的数据权限控制就得同时改两个 Server维护成本直接翻倍。按领域拆分控制点集中在一个 Server 内权限管理反而简单。3.3 LangGraph 中的 Client 初始化与连接管理LangGraph 本身不内置 MCP 支持需要通过langchain-mcp-adapters这个桥接库把 MCP 工具转换成 LangChain 的工具格式。这个库封装了 MCP 客户端的创建和工具转换逻辑。我当时的接入思路是这样的启动 LangGraph 应用时读全局配置文件逐个连接 MCP Server把每个 Server 的工具列表拉下来转成 LangChain 能识别的格式再统一塞给 LangGraph 的 agent 节点。核心代码逻辑如下import asyncio from langchain_mcp_adapters.client import MCPClient from langchain_mcp_adapters.tools import load_mcp_tools import json async def load_all_mcp_tools(config_path: str): with open(config_path, r, encodingutf-8) as f: config json.load(f) all_tools [] clients [] for name, server_config in config[mcpServers].items(): # 根据 transport 选择连接方式 if server_config.get(transport) stdio: client await MCPClient.create_stdio_client( commandserver_config[command], argsserver_config.get(args, []) ) else: client await MCPClient.create_http_client( urlserver_config[url] ) await client.initialize() tools await load_mcp_tools(client) # 给每个 Server 的工具名加前缀避免冲突 for tool in tools: tool.name f{name}_{tool.name} all_tools.extend(tools) clients.append(client) return all_tools, clients这里有个非常重要的操作工具名加前缀。多个 Server 很可能定义同名工具比如两个 Server 都叫query如果不做区分LangGraph 的工具映射表会直接覆盖冲突导致一个工具永远调不到。加前缀之后调用方一眼就知道是哪个 Server 的能力日志排查也方便。3.4 LangGraph 状态管理与多工具调用策略LangGraph 的状态设计直接决定多工具调用的体验。我的建议是状态里不直接存工具返回的大段文本而是存引用或摘要。原因很现实如果 SQL 查询返回了几万行结果全塞进状态里上下文长度立刻爆掉后面再跟模型交互就会变慢甚至报错。更合理的做法是状态里存查询结果的摘要比如前 N 行、存文件路径、存操作状态标志真正需要完整内容时再通过工具去取。下面是我在 LangGraph 里定义一个最小状态的示例from typing import TypedDict, Annotated import operator class AgentState(TypedDict): messages: Annotated[list, operator.add] query_result_summary: str last_operation: str active_server: str用operator.add做消息的累积归并每次节点返回的消息都会自动合并进状态。其他字段按业务需要自由定义但要克制——状态里的字段越多图的可维护性越差。调用策略上我推荐在 agent 节点里用ReAct 风格循环模型根据用户问题判断需要调哪个工具、传什么参数然后执行观察结果再决定下一步。LangGraph 的 agent 节点天然支持这种循环配合多 Server 的工具列表模型会自动选择前缀匹配的 Server 工具。关于并行调用LangGraph 支持多个节点并行执行但要注意不同 MCP Server 之间没有状态共享如果一个任务需要先查数据库再根据结果做网页操作那就必须串行。我一般只在完全独立的子任务上做并行比如同时查两个数据库、同时抓两个网页这种场景才值得开并行。4. 实操过程与关键环节逐步实现4.1 环境准备安装依赖和确认版本我踩过最坑的一件事就是依赖版本不兼容。langchain-mcp-adapters的版本跟langchain-core、mcp的版本绑定很紧版本不匹配会出现各种诡异的报错比如TypeError、Cannot instantiate client这种装的时候必须注意版本对齐。我的环境依赖清单供参考langchain0.3.x langchain-core0.3.x langchain-mcp-adapters0.1.x mcp1.9 httpx0.27建议直接用pip install langchain-mcp-adapters[cli]装全家桶它会把匹配的依赖一起拉进来避免手动装版本混乱。4.2 从零实现一个最简单的文件系统 MCP Server为了深入理解 MCP Server 端的逻辑我建议不要只当一个旁观者自己写一个最简单但完整的 Server 练手。这里我写了一个只提供两个工具的文件 Server一个读文件一个写文件。from mcp.server.fastmcp import FastMCP import os mcp FastMCP(filesystem-server) mcp.tool() def read_file(path: str) - str: 读取指定路径的文本文件内容 if not os.path.exists(path): return f错误文件 {path} 不存在 with open(path, r, encodingutf-8) as f: return f.read() mcp.tool() def write_file(path: str, content: str) - str: 将内容写入指定路径的文件 try: with open(path, w, encodingutf-8) as f: f.write(content) return f成功写入 {path} except Exception as e: return f写入失败{str(e)} if __name__ __main__: mcp.run(transportstdio)这个 Server 虽然简单但把 MCP Server 最核心的概念都覆盖了定义工具、注册进 Server、启动服务。用 FastMCP 框架mcp.tool()装饰器自动做函数到工具的映射包括参数 schema 的生成。4.3 手动跑通一次协议握手学 MCP 最快的方式是手动模拟一次握手亲眼看看 JSON-RPC 报文长什么样。我建议先把这个 Server 启起来然后用mcp官方的命令行工具连一把mcp run filesystem-server.py在另一个终端用 MCP Inspector 连接npx modelcontextprotocol/inspector filesystem-server.pyInspector 打开后你能看到完整的消息交互过程initialize请求、响应、notifications/initialized、tools/list。亲眼看过一次报文后面理解 LangGraph 里的报错就能做到心里有数。我强烈推荐大家做这一步哪怕你已经写了多年代码也值得把协议层看一遍。MCP 的很多疑难杂症比如连接成功但工具列表是空的、调用工具超时、响应格式不对本质都是对报文结构理解不到位。4.4 在 LangGraph 里把三个 Server 全部接进来下面是我实际跑通的一个 LangGraph 编排例子模型收到一个任务后可能查 SQL Server 的库存数据可能用 Playwright 去抓一个网页也可能读写本地文件。我把三个不同类型的 Server 全接进来让模型自己判断该调用哪个。import asyncio from langgraph.graph import StateGraph, END from langgraph.prebuilt import ToolNode from langchain_openai import ChatOpenAI from tools_loader import load_all_mcp_tools # 前面写的加载函数 async def build_graph(): tools, clients await load_all_mcp_tools(mcp-config.json) llm ChatOpenAI(modelgpt-4o, temperature0) llm_with_tools llm.bind_tools(tools) def agent_node(state: AgentState): response llm_with_tools.invoke(state[messages]) return {messages: [response]} def should_continue(state: AgentState): last_message state[messages][-1] if last_message.tool_calls: return tools return end tool_node ToolNode(tools) graph StateGraph(AgentState) graph.add_node(agent, agent_node) graph.add_node(tools, tool_node) graph.add_edge(agent, tools, conditionshould_continue) graph.add_edge(tools, agent) graph.add_edge(agent, end) app graph.compile() return app, clients async def main(): app, clients await build_graph() result await app.ainvoke({ messages: [{role: user, content: 查一下数据库里库存小于10的商品并输出成文件}] }) print(result[messages][-1].content) if __name__ __main__: asyncio.run(main())这段代码的思路是agent_node是决策节点模型看到用户的请求后决定用哪些工具如果模型决定用工具状态流转到tools节点ToolNode执行具体的工具调用工具完成返回结果后状态回到 agent 节点模型根据结果决定下一步或结束三个 Server 的工具统一混在一个工具列表里但因为之前做了前缀区分模型会基于工具描述选择正确的工具不会混淆。5. 常见问题与排查技巧实录5.1 高频报错与解决方案速查表我把实操里遇到的典型问题整理成了下面的速查表每个问题都是我或周围同事真实踩过的坑不是网上那种假大空的“常见问题”。报错现象根本原因解决方法Connection closed/ 握手失败Server 未正确监听或传输方式不对确认 Server 用的是 stdio 还是 HTTP客户端必须一致tools/list返回空列表Server 端工具定义有语法错误或装饰器没生效先用 MCP Inspector 单独测 Server确认能列出工具工具调用超时Server 端执行时间过长或网络延迟增加客户端超时时间大任务改为异步执行工具名冲突只调用到一个 Server 的工具多个 Server 定义了同名工具工具加载时统一加前缀JSON-RPC 响应格式错误Server 返回的不是合法 JSON检查 Server 里有没有 print 干扰标准输出stdio 模式下跨机器连接失败stdio 只在进程内通信改成 HTTP 或 SSE 传输LangGraph 节点卡死不返回结果agent 循环没停模型反复调同一个工具给工具调用加次数上限检查模型是否陷入死循环调用工具返回isError: true工具内部异常但走了错误分支检查 Server 日志把异常信息打印出来5.2 一个我排查了很久的坑stdio 模式下的 print 污染如果你做 MCP Server 时习惯性地在代码里加print()调试而且在 stdio 模式下运行那你就中招了。stdio 模式下标准输出就是 MCP 的通信通道你打一个print客户端收到的就不是合法 JSON而是“keyboard interrupt”这一类的错误排查起来让人头大。正确的调试姿势是把日志写到文件或者用 Python 的logging模块配置成输出到 stderr。import logging logging.basicConfig( levellogging.INFO, filenameserver.log, filemodea )这样既能看到日志又不会污染 stdout 的协议数据。5.3 工具调用成功但结果没用上语义匹配问题有段时间我发现模型会“选择困难”——用户问数据库问题它却去调了浏览器工具。查日志发现工具描述写得不清晰模型分辨不出工具之间的边界。解决办法是调整工具的 description 字段把它当成搜索引擎的关键词来写。比如 SQL Server 那个工具描述写成“查询 SQL Server 数据库适合处理订单、库存、用户等结构化数据问题”Playwright 的描述写成“控制浏览器打开网页、抓取页面内容、模拟点击适合处理网页上的信息”。描述写得越明确模型的工具选择准确率越高。另外可以给不同 Server 的工具加上统一的命名前缀比如sql_、web_让模型能从名字上快速区分。这也是我在多 Server 场景里强制加前缀的重要原因。5.4 流式输出的注意事项如果你需要在 LangGraph 里用 MCP 工具流式输出内容比如把一个大文件的读取结果一段段写进目标文件要注意 MCP 的tools/call响应默认是整体返回的不是流式的。想要流式效果需要在 Server 端自己做分块返回或者在客户端拿到完整结果后再分片比如每 N 行写一次文件、每攒够一定量就 flush 一次。我倾向于后者客户端分片。原因是 Server 端做流式实现复杂还要处理中断恢复对于大多数应用场景不值当。拿到完整结果后分片写入简单、可控、好排查。6. 从个人经验谈一些容易被忽视的工程化细节6.1 连接生命周期管理启动时连接退出时释放多 Server 场景下连接管理不是小事。我建议应用启动时建立所有 Server 连接并保持常驻不要在每次请求时重新握手。重新握手意味着重新拉工具列表、重新初始化耗时通常在百毫秒到秒级高频场景下完全不可接受。同时应用退出时要主动关闭连接。MCP 客户端一般有aclose()或类似的释放方法不调用的话Server 端可能会留下僵尸进程特别是在 stdio 模式下那个 python 子进程不会自己退出。6.2 配置中心化用环境变量控制环境差异开发、测试、生产环境的 Server 地址大概率不一样我强烈建议配置不要写死在代码里用环境变量动态注入。比如生产环境的 Playwright Server 地址是http://playwright-prod:9000/mcp开发环境是http://localhost:9000/mcp这时候应该用${PLAYWRIGHT_URL}这种占位符然后在启动脚本里传入环境变量。这不算什么高科技但能让你在切换环境时少改很多代码也避免了把生产地址不小心提交到代码仓库里的低级事故。6.3 安全边界只暴露最小范围的工具我之前差点把一个文件系统 Server 暴露给所有用户后来想一想真的后背发凉。MCP Server 的能力边界极其清晰如果你加了“写入文件”“执行命令”这类高风险工具一定要在 Server 端做鉴权而不是指望着模型“不会滥用”。我在 SQL Server 的 MCP Server 里就做过白名单限制只允许执行SELECT查询DROP、DELETE、UPDATE这类写操作直接返回错误。文件系统 Server 则限定在某个临时目录下路径必须经过 canonicalize 处理防止../这类路径穿越。安全这件事宁可在 Server 端多做一层校验也不能指望调用方的自觉。6.4 日志与可观测性的设计建议多 Server 调用最常见的排查难点是你根本不知道当前请求走到哪了、调了哪个 Server、花了多久。所以日志绝对不要只打一行“调用工具”要打完整的上下文。我建议最少记录这几个字段请求 ID、Server 名、工具名、入参摘要、耗时、返回状态。格式可以是[req-123][sql][query_stock] 耗时230ms 返回2行。有了这些排查问题时才不用靠猜。如果项目再大一点可以把这些日志接进链路追踪系统LangGraph 每次调用生成一个 trace ID往下传给每个 MCP 调用。这个方案初期成本稍高但一旦你开始做复杂的多工具编排这套系统能救你很多次。7. 写在最后的一些话MCP 这个协议的思路本质上是在做“接口标准化”这件事。早年我们搞微服务要定 RESTful 规范、定 OpenAPI 文档现在轮到 AI 应用对接外部世界也需要一套类似的约定MCP 就是目前最有希望成为事实标准的那个。从协议握手到 LangGraph 多 Server 调用这条路看着不长但每一步都有细节。我自己走过一遍最大的体会是不要一开始就堆框架先把协议跑通再考虑编排。先用 MCP Inspector 手动连一个 Server看看 JSON-RPC 报文长什么样再手动写一个最简单的 Server感受工具注册和调用的全流程最后才上 LangGraph让模型去做动态决策。这个顺序走得顺后面碰到再多 Server 也不会慌。如果你正在摸索 MCP 和 LangGraph 的集成希望这篇东西能帮你少踩几个坑。特别是工具名冲突、stdio 传输选型、print 污染这三个问题都是实战里很容易踩到又很难排查的提前注意能省不少时间。
MCP 这个圈子今年是真的热闹光是“mcp是什么”这类搜索就天天有人在问。但光知道概念没用真到自己上手把 MCP Server 接进 LangGraph 流程里你会发现坑全藏在细节里——尤其是从协议握手到多 Server 调用这一段文档写得云里雾里网上教程各说各话抄作业都抄不齐。这篇东西我憋了挺久把从零开始理解 MCP 协议握手、到在 LangGraph 里同时挂载多个 Server 的完整过程捋了一遍含代码、含配置、含报错排查。适合刚摸到 MCP 边缘的开发者也适合已经被多 Server 调用折磨到怀疑人生的同学。1. MCP 到底在解决什么问题它的设计思路是什么1.1 MCP 是什么以及它凭什么值得学MCP 的全称是 Model Context Protocol模型上下文协议。你可以把它理解成 AI 应用世界的 USB-C 接口——过去你想让大模型调用某个工具、读某个数据库、操作某个软件就得针对每个工具写一套私有集成代码换个工具就得重写一遍。MCP 想做的就是把“模型怎么跟外部工具对话”这件事标准化。它解决的核心痛点是工具接入的重复劳动。比如你今天接了一个 SQL Server 查询工具明天又要接一个 Playwright 浏览器自动化工具后天还要接 Altium Designer 的 PCB 检查接口。如果每个都单独写适配层那工作量是线性增长的而且每个适配层都要处理通信、鉴权、错误重试这些杂活。MCP 把所有这些收敛成一套协议模型侧只需要学会怎么通过 MCP 客户端跟 Server 通信工具侧只需要实现一套 MCP Server 接口。这就像家里所有电器都换成了同一个插头标准你不再需要为每个电器准备一个专属转接头。1.2 为什么 LangGraph 需要多 Server 调用LangGraph 本身是一个编排大模型应用流程的框架它擅长把复杂的任务拆成节点和边让模型在节点之间跳转。但 LangGraph 本身不产工具它需要外部能力——查询数据库、调 API、操作浏览器、读文件等等。这些能力如果全都塞进一个 MCP Server 里很快会变成一个大杂烩权限边界模糊、单个工具挂了影响全局、代码维护起来想骂人。合理的做法是按领域拆分 Server一个负责数据查询一个负责文件操作一个负责网页自动化。每个 Server 独立部署、独立升级LangGraph 作为调度中心统一调用。这就是“多 Server 调用”的真实场景。我见过不少人在这一步翻车不是因为 LangGraph 难而是因为对 MCP 的通信机制理解不透。所以后面我会先从协议握手讲起把最底层的东西搞明白再去碰 LangGraph。2. MCP 协议握手的核心机制与实操细节2.1 握手到底在握什么MCP 的通信底层用的是 JSON-RPC 2.0这是一种很轻量的远程调用协议请求和响应都是 JSON 格式带 id、method、params、result 这些字段。MCP 在此基础上定义了自己的方法集。握手的第一步是客户端给 Server 发一个initialize请求。这一步非常关键它起了三个作用确认协议版本兼容、交换双方能力信息、建立后续通信的上下文。我的经验是很多人在自测 MCP Server 时直接就用tools/list去调结果返回一堆错误原因就是跳过了initialize。Server 端在没收到合法的 initialize 之前一般不会把你当成合法客户端更不会让你列工具。握手流程拆开看是这样的客户端发送initialize带上协议版本和客户端能力描述Server 返回自己的协议版本、Server 能力描述、以及一个 session 标识客户端再发一个notifications/initialized通知告诉 Server“我已经准备好可以开始正式工作了”之后双方才能正常进行tools/list、tools/call、resources/list这些操作这里有个细节容易被忽略notifications/initialized是通知不是请求它没有响应。有些新手会在这儿傻等 Server 的回包等不到就以为连接断了。实际上这个通知发出去Server 收到就算完事。2.2 三种传输方式怎么选MCP 协议支持多种传输层实现日常接触最多的是这三种stdio、HTTPSSE、以及基于 Streamable HTTP 的现代传输。stdio是最简单的起步方式Server 作为子进程被客户端拉起双方的通信走标准输入输出。好处是零网络配置本地调试很方便坏处是没法跨机器调用。HTTPSSE是老牌方案客户端通过 POST 发请求Server 通过 SSE 单向推送事件给客户端。适合跨网络部署、需要鉴权的场景。Streamable HTTP是后面推的新方案改进了 SSE 的一些限制支持双向流式通信很多新 SDK 已经默认走这条路。选型建议很简单本地开发用 stdio部署到服务器上给远程 LangGraph 服务调用就果断用 Streamable HTTP。我踩过最大的坑就是在服务器上用了 stdio 传输结果 LangGraph 进程和 MCP Server 进程不在同一个主机上连接直接失败。切记stdio 只能在同一个进程树里用。2.3 一次完整的工具发现与调用过程握完手之后真正的工作流是工具发现和工具调用。工具发现走tools/listServer 会返回一个工具清单每个工具包括名字、描述、输入 schema。这个 schema 用的是 JSON Schema 格式描述参数的结构和校验规则。工具调用走tools/call客户端把工具名和参数传过去Server 返回执行结果。结果里有两个字段值得注意content是实际内容isError标记这次调用是否出错。我在做 LangGraph 集成的时候把工具发现做了缓存——进程启动时拉一次工具列表之后不再反复请求。原因很简单tools/list虽然不重但每次调用都走一遍 JSON-RPC 往返在高频场景下白白增加延迟。工具的增删改一般需要重启 Server 或动态刷新机制平时稳定不变。3. 多 Server 架构的设计与 LangGraph 集成方案3.1 多个 Server 的目录结构与配置管理多 Server 不是把代码堆在一起就行从一开始就要规划好工程结构。我的习惯是一个 Server 一个目录每个 Server 独立声明自己的依赖再在根目录放一个统一的配置文件记录所有 Server 的注册信息。下面是我常用的目录结构mcp-servers/ ├── sql-server/ # SQL Server 查询 Server │ ├── server.py │ └── config.json ├── playwright-server/ # 浏览器自动化 Server │ ├── server.py │ └── config.json ├── filesystem-server/ # 文件系统操作 Server │ ├── server.py │ └── config.json └── mcp-config.json # LangGraph 侧的全局配置mcp-config.json长这样{ mcpServers: { sql: { command: python, args: [sql-server/server.py], transport: stdio }, playwright: { url: http://localhost:9000/mcp, transport: streamable-http }, filesystem: { command: python, args: [filesystem-server/server.py], transport: stdio } } }这份配置是 LangGraph 侧读取的每个条目代表一个 Server。用mcpServers这个键名是行业惯例很多 MCP 客户端都认这个格式所以命名上尽量不要改。3.2 为什么按领域拆分 Server而不是按功能粒度拆分有人会问我把每个工具单独做一个 Server 行不行技术上可以但运营上是噩梦。Server 数量多了之后连接管理、鉴权配置、日志追踪全都会变成新的问题。按领域拆分的核心逻辑是一个 Server 代表一个稳定的能力边界。SQL Server 只负责数据查询你换数据库、调 SQL 优化只动这一个 ServerPlaywright 负责浏览器操作这个 Server 挂了不影响数据库查询文件系统 Server 单独控制读写权限安全审计也清晰。举个例子如果我把“读取订单表”和“读取用户表”分别做成两个 Server技术上是可行的但以后要做个统一的数据权限控制就得同时改两个 Server维护成本直接翻倍。按领域拆分控制点集中在一个 Server 内权限管理反而简单。3.3 LangGraph 中的 Client 初始化与连接管理LangGraph 本身不内置 MCP 支持需要通过langchain-mcp-adapters这个桥接库把 MCP 工具转换成 LangChain 的工具格式。这个库封装了 MCP 客户端的创建和工具转换逻辑。我当时的接入思路是这样的启动 LangGraph 应用时读全局配置文件逐个连接 MCP Server把每个 Server 的工具列表拉下来转成 LangChain 能识别的格式再统一塞给 LangGraph 的 agent 节点。核心代码逻辑如下import asyncio from langchain_mcp_adapters.client import MCPClient from langchain_mcp_adapters.tools import load_mcp_tools import json async def load_all_mcp_tools(config_path: str): with open(config_path, r, encodingutf-8) as f: config json.load(f) all_tools [] clients [] for name, server_config in config[mcpServers].items(): # 根据 transport 选择连接方式 if server_config.get(transport) stdio: client await MCPClient.create_stdio_client( commandserver_config[command], argsserver_config.get(args, []) ) else: client await MCPClient.create_http_client( urlserver_config[url] ) await client.initialize() tools await load_mcp_tools(client) # 给每个 Server 的工具名加前缀避免冲突 for tool in tools: tool.name f{name}_{tool.name} all_tools.extend(tools) clients.append(client) return all_tools, clients这里有个非常重要的操作工具名加前缀。多个 Server 很可能定义同名工具比如两个 Server 都叫query如果不做区分LangGraph 的工具映射表会直接覆盖冲突导致一个工具永远调不到。加前缀之后调用方一眼就知道是哪个 Server 的能力日志排查也方便。3.4 LangGraph 状态管理与多工具调用策略LangGraph 的状态设计直接决定多工具调用的体验。我的建议是状态里不直接存工具返回的大段文本而是存引用或摘要。原因很现实如果 SQL 查询返回了几万行结果全塞进状态里上下文长度立刻爆掉后面再跟模型交互就会变慢甚至报错。更合理的做法是状态里存查询结果的摘要比如前 N 行、存文件路径、存操作状态标志真正需要完整内容时再通过工具去取。下面是我在 LangGraph 里定义一个最小状态的示例from typing import TypedDict, Annotated import operator class AgentState(TypedDict): messages: Annotated[list, operator.add] query_result_summary: str last_operation: str active_server: str用operator.add做消息的累积归并每次节点返回的消息都会自动合并进状态。其他字段按业务需要自由定义但要克制——状态里的字段越多图的可维护性越差。调用策略上我推荐在 agent 节点里用ReAct 风格循环模型根据用户问题判断需要调哪个工具、传什么参数然后执行观察结果再决定下一步。LangGraph 的 agent 节点天然支持这种循环配合多 Server 的工具列表模型会自动选择前缀匹配的 Server 工具。关于并行调用LangGraph 支持多个节点并行执行但要注意不同 MCP Server 之间没有状态共享如果一个任务需要先查数据库再根据结果做网页操作那就必须串行。我一般只在完全独立的子任务上做并行比如同时查两个数据库、同时抓两个网页这种场景才值得开并行。4. 实操过程与关键环节逐步实现4.1 环境准备安装依赖和确认版本我踩过最坑的一件事就是依赖版本不兼容。langchain-mcp-adapters的版本跟langchain-core、mcp的版本绑定很紧版本不匹配会出现各种诡异的报错比如TypeError、Cannot instantiate client这种装的时候必须注意版本对齐。我的环境依赖清单供参考langchain0.3.x langchain-core0.3.x langchain-mcp-adapters0.1.x mcp1.9 httpx0.27建议直接用pip install langchain-mcp-adapters[cli]装全家桶它会把匹配的依赖一起拉进来避免手动装版本混乱。4.2 从零实现一个最简单的文件系统 MCP Server为了深入理解 MCP Server 端的逻辑我建议不要只当一个旁观者自己写一个最简单但完整的 Server 练手。这里我写了一个只提供两个工具的文件 Server一个读文件一个写文件。from mcp.server.fastmcp import FastMCP import os mcp FastMCP(filesystem-server) mcp.tool() def read_file(path: str) - str: 读取指定路径的文本文件内容 if not os.path.exists(path): return f错误文件 {path} 不存在 with open(path, r, encodingutf-8) as f: return f.read() mcp.tool() def write_file(path: str, content: str) - str: 将内容写入指定路径的文件 try: with open(path, w, encodingutf-8) as f: f.write(content) return f成功写入 {path} except Exception as e: return f写入失败{str(e)} if __name__ __main__: mcp.run(transportstdio)这个 Server 虽然简单但把 MCP Server 最核心的概念都覆盖了定义工具、注册进 Server、启动服务。用 FastMCP 框架mcp.tool()装饰器自动做函数到工具的映射包括参数 schema 的生成。4.3 手动跑通一次协议握手学 MCP 最快的方式是手动模拟一次握手亲眼看看 JSON-RPC 报文长什么样。我建议先把这个 Server 启起来然后用mcp官方的命令行工具连一把mcp run filesystem-server.py在另一个终端用 MCP Inspector 连接npx modelcontextprotocol/inspector filesystem-server.pyInspector 打开后你能看到完整的消息交互过程initialize请求、响应、notifications/initialized、tools/list。亲眼看过一次报文后面理解 LangGraph 里的报错就能做到心里有数。我强烈推荐大家做这一步哪怕你已经写了多年代码也值得把协议层看一遍。MCP 的很多疑难杂症比如连接成功但工具列表是空的、调用工具超时、响应格式不对本质都是对报文结构理解不到位。4.4 在 LangGraph 里把三个 Server 全部接进来下面是我实际跑通的一个 LangGraph 编排例子模型收到一个任务后可能查 SQL Server 的库存数据可能用 Playwright 去抓一个网页也可能读写本地文件。我把三个不同类型的 Server 全接进来让模型自己判断该调用哪个。import asyncio from langgraph.graph import StateGraph, END from langgraph.prebuilt import ToolNode from langchain_openai import ChatOpenAI from tools_loader import load_all_mcp_tools # 前面写的加载函数 async def build_graph(): tools, clients await load_all_mcp_tools(mcp-config.json) llm ChatOpenAI(modelgpt-4o, temperature0) llm_with_tools llm.bind_tools(tools) def agent_node(state: AgentState): response llm_with_tools.invoke(state[messages]) return {messages: [response]} def should_continue(state: AgentState): last_message state[messages][-1] if last_message.tool_calls: return tools return end tool_node ToolNode(tools) graph StateGraph(AgentState) graph.add_node(agent, agent_node) graph.add_node(tools, tool_node) graph.add_edge(agent, tools, conditionshould_continue) graph.add_edge(tools, agent) graph.add_edge(agent, end) app graph.compile() return app, clients async def main(): app, clients await build_graph() result await app.ainvoke({ messages: [{role: user, content: 查一下数据库里库存小于10的商品并输出成文件}] }) print(result[messages][-1].content) if __name__ __main__: asyncio.run(main())这段代码的思路是agent_node是决策节点模型看到用户的请求后决定用哪些工具如果模型决定用工具状态流转到tools节点ToolNode执行具体的工具调用工具完成返回结果后状态回到 agent 节点模型根据结果决定下一步或结束三个 Server 的工具统一混在一个工具列表里但因为之前做了前缀区分模型会基于工具描述选择正确的工具不会混淆。5. 常见问题与排查技巧实录5.1 高频报错与解决方案速查表我把实操里遇到的典型问题整理成了下面的速查表每个问题都是我或周围同事真实踩过的坑不是网上那种假大空的“常见问题”。报错现象根本原因解决方法Connection closed/ 握手失败Server 未正确监听或传输方式不对确认 Server 用的是 stdio 还是 HTTP客户端必须一致tools/list返回空列表Server 端工具定义有语法错误或装饰器没生效先用 MCP Inspector 单独测 Server确认能列出工具工具调用超时Server 端执行时间过长或网络延迟增加客户端超时时间大任务改为异步执行工具名冲突只调用到一个 Server 的工具多个 Server 定义了同名工具工具加载时统一加前缀JSON-RPC 响应格式错误Server 返回的不是合法 JSON检查 Server 里有没有 print 干扰标准输出stdio 模式下跨机器连接失败stdio 只在进程内通信改成 HTTP 或 SSE 传输LangGraph 节点卡死不返回结果agent 循环没停模型反复调同一个工具给工具调用加次数上限检查模型是否陷入死循环调用工具返回isError: true工具内部异常但走了错误分支检查 Server 日志把异常信息打印出来5.2 一个我排查了很久的坑stdio 模式下的 print 污染如果你做 MCP Server 时习惯性地在代码里加print()调试而且在 stdio 模式下运行那你就中招了。stdio 模式下标准输出就是 MCP 的通信通道你打一个print客户端收到的就不是合法 JSON而是“keyboard interrupt”这一类的错误排查起来让人头大。正确的调试姿势是把日志写到文件或者用 Python 的logging模块配置成输出到 stderr。import logging logging.basicConfig( levellogging.INFO, filenameserver.log, filemodea )这样既能看到日志又不会污染 stdout 的协议数据。5.3 工具调用成功但结果没用上语义匹配问题有段时间我发现模型会“选择困难”——用户问数据库问题它却去调了浏览器工具。查日志发现工具描述写得不清晰模型分辨不出工具之间的边界。解决办法是调整工具的 description 字段把它当成搜索引擎的关键词来写。比如 SQL Server 那个工具描述写成“查询 SQL Server 数据库适合处理订单、库存、用户等结构化数据问题”Playwright 的描述写成“控制浏览器打开网页、抓取页面内容、模拟点击适合处理网页上的信息”。描述写得越明确模型的工具选择准确率越高。另外可以给不同 Server 的工具加上统一的命名前缀比如sql_、web_让模型能从名字上快速区分。这也是我在多 Server 场景里强制加前缀的重要原因。5.4 流式输出的注意事项如果你需要在 LangGraph 里用 MCP 工具流式输出内容比如把一个大文件的读取结果一段段写进目标文件要注意 MCP 的tools/call响应默认是整体返回的不是流式的。想要流式效果需要在 Server 端自己做分块返回或者在客户端拿到完整结果后再分片比如每 N 行写一次文件、每攒够一定量就 flush 一次。我倾向于后者客户端分片。原因是 Server 端做流式实现复杂还要处理中断恢复对于大多数应用场景不值当。拿到完整结果后分片写入简单、可控、好排查。6. 从个人经验谈一些容易被忽视的工程化细节6.1 连接生命周期管理启动时连接退出时释放多 Server 场景下连接管理不是小事。我建议应用启动时建立所有 Server 连接并保持常驻不要在每次请求时重新握手。重新握手意味着重新拉工具列表、重新初始化耗时通常在百毫秒到秒级高频场景下完全不可接受。同时应用退出时要主动关闭连接。MCP 客户端一般有aclose()或类似的释放方法不调用的话Server 端可能会留下僵尸进程特别是在 stdio 模式下那个 python 子进程不会自己退出。6.2 配置中心化用环境变量控制环境差异开发、测试、生产环境的 Server 地址大概率不一样我强烈建议配置不要写死在代码里用环境变量动态注入。比如生产环境的 Playwright Server 地址是http://playwright-prod:9000/mcp开发环境是http://localhost:9000/mcp这时候应该用${PLAYWRIGHT_URL}这种占位符然后在启动脚本里传入环境变量。这不算什么高科技但能让你在切换环境时少改很多代码也避免了把生产地址不小心提交到代码仓库里的低级事故。6.3 安全边界只暴露最小范围的工具我之前差点把一个文件系统 Server 暴露给所有用户后来想一想真的后背发凉。MCP Server 的能力边界极其清晰如果你加了“写入文件”“执行命令”这类高风险工具一定要在 Server 端做鉴权而不是指望着模型“不会滥用”。我在 SQL Server 的 MCP Server 里就做过白名单限制只允许执行SELECT查询DROP、DELETE、UPDATE这类写操作直接返回错误。文件系统 Server 则限定在某个临时目录下路径必须经过 canonicalize 处理防止../这类路径穿越。安全这件事宁可在 Server 端多做一层校验也不能指望调用方的自觉。6.4 日志与可观测性的设计建议多 Server 调用最常见的排查难点是你根本不知道当前请求走到哪了、调了哪个 Server、花了多久。所以日志绝对不要只打一行“调用工具”要打完整的上下文。我建议最少记录这几个字段请求 ID、Server 名、工具名、入参摘要、耗时、返回状态。格式可以是[req-123][sql][query_stock] 耗时230ms 返回2行。有了这些排查问题时才不用靠猜。如果项目再大一点可以把这些日志接进链路追踪系统LangGraph 每次调用生成一个 trace ID往下传给每个 MCP 调用。这个方案初期成本稍高但一旦你开始做复杂的多工具编排这套系统能救你很多次。7. 写在最后的一些话MCP 这个协议的思路本质上是在做“接口标准化”这件事。早年我们搞微服务要定 RESTful 规范、定 OpenAPI 文档现在轮到 AI 应用对接外部世界也需要一套类似的约定MCP 就是目前最有希望成为事实标准的那个。从协议握手到 LangGraph 多 Server 调用这条路看着不长但每一步都有细节。我自己走过一遍最大的体会是不要一开始就堆框架先把协议跑通再考虑编排。先用 MCP Inspector 手动连一个 Server看看 JSON-RPC 报文长什么样再手动写一个最简单的 Server感受工具注册和调用的全流程最后才上 LangGraph让模型去做动态决策。这个顺序走得顺后面碰到再多 Server 也不会慌。如果你正在摸索 MCP 和 LangGraph 的集成希望这篇东西能帮你少踩几个坑。特别是工具名冲突、stdio 传输选型、print 污染这三个问题都是实战里很容易踩到又很难排查的提前注意能省不少时间。
