企业官网建设流程全解析

开头

最近在折腾基于 LLM 的智能体项目，发现身边不少朋友都在聊 MCP，但聊着聊着就卡在同一个地方：文档看了不少、demo 也跑通了，可一旦要把多个 MCP Server 接进 LangGraph 的编排流程里，就会遇到各种协议层面的怪问题。这篇分享就从我实际踩坑的经历出发，把 MCP 从协议握手到 LangGraph 多 Server 调用的整条链路拆开讲清楚，包括 initialize 阶段到底交换了什么、tools/list 返回的工具怎么注册成图里的节点、多个 Server 同时在线时命名空间怎么隔离，以及一堆报错背后的真实原因。适合已经跑通过基础 MCP demo、准备把工具调用落进生产级 Agent 流程的开发者参考。

1. 先搞清楚 MCP 到底解决什么问题

1.1 工具调用从“各写各的”到“统一协议”

在 MCP 出现之前，让 LLM 调用外部工具基本是各玩各的。有人给模型写 function calling 的 JSON Schema，有人自己封装 HTTP 接口再让 Agent 去请求，还有人直接把 Python 函数塞进提示词里让模型碰运气。每个项目都要重复实现一套“模型如何知道工具有什么、参数长什么样、返回结果怎么处理”的逻辑，换一个客户端或者换一个模型供应商，之前写的工具接入代码基本作废。

MCP（Model Context Protocol）就是冲着这个问题来的。它把“模型需要上下文”这件事做了标准化：工具、数据资源、提示词模板这些能力，都通过统一的协议暴露给模型客户端。你不需要为每个模型单独写工具层，也不需要为每个工具单独做接口对接，只要实现一次 MCP Server，Claude、LangChain、LangGraph 或者其他支持 MCP 的客户端都能直接复用同一套工具。

用生活里的例子类比，以前的工具调用像是每家饭店都有自己的点菜方式，有的要喊、有的要写纸条、有的要扫码，顾客换一家店就得重新学一遍；MCP 则像是统一了菜单格式和上菜流程，不管是哪家饭店，顾客都用同一种方式点菜，饭店也用同一种方式出餐。对做 Agent 的开发者来说，这套标准化省下的不是某一次对接的功夫，而是整个生态层面的复用成本。

1.2 三个角色的协作模式：host、client、server

MCP 的架构看起来简单，但三个角色的职责边界容易搞混，我刚开始就栽在这上面。简单说，host 是运行 LLM 应用的主程序，它负责提供用户交互界面和业务编排；client 是 host 内部与 server 通信的协议实现方，负责建立连接、收发消息；server 则是能力的提供方，向外暴露工具、资源和提示词。

一个容易忽略的点是：host 和 client 不一定是分开的两个进程，往往 client 就是 host 里的一个模块。LangGraph 应用跑起来时，你写的图就是 host 的一部分，每个 MCP server 对应的连接对象就是 client。Server 可以通过 stdio（标准输入输出）方式由 host 直接拉起子进程，也可以通过 HTTP 方式以流式传输暴露远程服务。这两种传输方式的适用范围差异很大，后面我会专门说什么时候该用哪种。

这个三角色模型还引出一个关键认知：MCP 的工具调用方向是“模型发起、工具执行、结果回流”，但协议层面并没有规定模型一定是调用方。反向的时候也有，比如 server 可以向 host 发起 sampling 请求，让模型生成内容后再返回给 server 使用。了解这个机制对排查问题很重要，因为很多“奇怪”的报错本质上是请求方向搞反了。

2. 协议握手拆解：从 initialize 到 tools/call

2.1 initialize 握手的报文细节

我第一次抓 MCP 握手报文时，第一个感受是：这协议比我想象的要轻。整个握手是基于 JSON-RPC 2.0 的，没有多余的包装。客户端先发一条 initialize 请求，里面带三个关键字段：protocolVersion、capabilities、clientInfo。

protocolVersion 是你支持的协议版本号，server 收到后会返回它自己支持的版本。两边版本不一致时，以 server 返回为准，这也是很多老项目连不上新 SDK 的原因——server 还停留在旧版本，但新客户端上来就发新版 initialize，老 server 不认识就直接拒绝了。

capabilities 字段在握手阶段特别容易被忽略。你在这个字段里声明自己支持哪些扩展能力，比如工具调用、资源订阅、提示词管理。注意，这个声明只是表示“我具备这个能力”，不代表当前会话里就一定要用到。server 端的 capabilities 返回同理。我在实际项目中踩过这样的坑：客户端没在 capabilities 里声明 tools，结果后续调用 tools/list 时 server 直接返回空列表，排查了半天才发现是握手阶段少声明了一个字段。

clientInfo 字段用于标识客户端身份，包含 name 和 version。别小看这个字段，很多 server 会基于它做日志记录和权限控制。调试时可以故意改一下 name，看 server 端日志里能不能正确显示你的客户端身份，这能帮你快速确认握手链路是通的。

2.2 握手之后的三个核心能力面

握手成功后，客户端会发送一次 initialized 通知，通知不期待响应。这个设计让 server 可以在收到通知后再加载资源、初始化缓存，而不用阻塞在握手阶段半途等人。做完这一步，连接才算真正进入可用状态。

接下来就是三个核心能力面：tools、resources、prompts。Tools 是函数，由模型调用来执行动作，是 Agent 场景最常用的一类；Resources 是数据，以 URI 形式暴露，供模型读取上下文；Prompts 是模板，供用户或模型选择后填充参数。

这三者的区别取决于使用场景，很多人问“我该把数据库查询做成 tool 还是 resource”，我的判断标准是看这个数据是被动读取还是主动参与决策。被动读取、直接作为上下文给模型看的，适合做成 resource；需要模型根据对话内容决定“要不要查、查什么条件”的，适合做成 tool。比如把用户订单列表做成 resource，模型直接读取就能拿到全量数据；但“按条件查询订单”就必须是 tool，因为查询条件是模型在推理过程中动态生成的。

我见过不少团队把 resource 做成 tool，结果模型每轮对话都强行调用一次工具，Token 消耗剧增，上下文还全是重复数据。这个设计决策对后续成本优化影响很大，建议在一开始就想清楚。

2.3 一次完整工具调用的链路分析

一次完整的 MCP 工具调用，表面上看起来只是模型说了一句“我要调用某某工具”，背后实际走了好几个来回。

以客户端视角，顺序是这样的：客户端通过 tools/list 拿到工具清单和 JSON Schema；模型根据对话上下文和这个 Schema 决定调用哪个工具、生成参数；客户端构造 tools/call 请求发给 server；server 执行工具逻辑，把结构化结果返回给客户端；客户端把结果回填给模型，模型基于结果继续生成内容。

听起来简单，但这里有两个隐藏环节。第一是 tools/list 不一定要在每次调用前重新请求，SDK 一般会做本地缓存，但 server 端工具列表可能动态变化（比如运行期注册了新工具），这时就需要手动刷新缓存。第二个是模型参数生成到协议层参数之间，中间有一个序列化和校验过程，如果模型返回的参数类型跟 Schema 定义不一致，工具调用会在 server 端直接失败，而这种失败往往被包装成通用错误，不深入看 server 端日志根本定位不到。

我在把 MCP 接进 LangGraph 时，最常碰到的也是这两个环节的问题。后面我会给你一份我整理的可复用检查清单，先记住一句话：凡是工具被“找到”了但“调不通”的情况，八成都出在 Schema 匹配或 server 端执行体内部。

3. 在 LangGraph 里接入 MCP Server

3.1 为什么是 LangGraph 而不是直接裸调 MCP

MCP 提供了标准协议，但协议本身不解决编排问题。真正的 Agent 应用里，模型要跟多个工具打交道，还要决定先调哪个、后调哪个、哪些结果要保留在上下文中、哪些要丢弃。这些逻辑如果全写在业务代码里，很快就会变成一团乱麻。

LangGraph 的价值在于它把 Agent 流程建模成一张图。每个节点可以做一件事：调用模型、执行工具、做条件判断、更新状态。节点之间的边表达了流转关系，条件边可以做到“当模型决定调用工具时走工具节点，否则直接返回结果”。状态对象在整张图里传递，天然适合保存工具调用历史和多轮对话上下文。

这样设计的好处是调试路径清晰。一条请求进来，你可以沿着图的节点一个一个看状态变化，知道每步发生了什么。相比之下，裸调 MCP 的代码里，请求进来就直接按业务逻辑走完，中间某个工具出错了，你只能靠打日志去猜。

我把 MCP Server 接进 LangGraph 的思路是：每个 MCP Server 当成一个工具来源，通过适配器把它的工具列表转成 LangChain 的 Tool 对象，然后把这些 Tool 注册成图里一个统一的 execute_tools 节点。模型在 decide 节点决定要调用哪些工具，execute_tools 节点负责真正执行，执行结果写回状态，再交给下一轮 decide 节点。

3.2 实操：用适配器把 MCP 工具变成 Agent 的工具

LangChain 官方有一个 mcpadapt 库，专门把 MCP Server 转成 LangChain Tool。我实际用下来，这套方式比较省心，它的核心流程分三步：创建 MCP 客户端、加载工具列表、把工具转换成 LangChain 可识别的格式。

先看一个最小可用的接入代码：

import asyncio from langchain_mcp_adapters.client import MultiServerMCPClient from langchain_openai import ChatOpenAI from langgraph.prebuilt import create_agent # 注意这里的 client 名字 mcp_weather，后面访问工具时要带前缀 mcp_client = MultiServerMCPClient( { "mcp_weather": { "transport": "stdio", "command": "python", "args": ["weather_server.py"], } } ) async def run(): async with mcp_client as client: tools = client.get_tools() model = ChatOpenAI(model="gpt-4o") agent = create_agent(model, tools) result = await agent.ainvoke({"messages": "帮我查一下北京今天的天气"}) print(result["messages"][-1].content) asyncio.run(run())

这段代码里最关键的是 mcp_weather 这个 key，它决定了工具的命名前缀。MultiServerMCPClient 会自动把 MCP server 里的工具名加上前缀，比如 server 内部有个工具叫 get_current_weather，在 LangGraph 里就会变成 mcp_weather__get_current_weather。这个前缀机制是为了避免多个 server 出现工具名冲突，但它也有副作用，后面我会详细说。

3.3 把工具节点嵌进图里：一个可复用的模板

用 create_agent 快速建 Agent 挺方便，但真正常规工作流未必走内置的 ReAct 逻辑。如果你想精确控制流程，需要手动建图。下面是我在生产项目里一直在用的一个简化模板：

from typing import TypedDict, Annotated from langgraph.graph import StateGraph, END from langgraph.graph.message import add_messages class AgentState(TypedDict): messages: Annotated[list, add_messages] def main(): graph = StateGraph(AgentState) graph.add_node("decide", decide_node) graph.add_node("execute_tools", execute_tools_node) graph.add_edge("decide", "execute_tools") graph.add_conditional_edges( "decide", lambda state: "execute_tools" if need_tools(state) else END, {"execute_tools": "execute_tools", END: END} ) graph.add_edge("execute_tools", "decide") app = graph.compile() return app

这个模板的核心是 decide 节点调模型，模型返回 tool_calls 时走 execute_tools，没有工具调用就直接结束。execute_tools 节点拿到模型请求的工具名和参数后，去对应 MCP server 执行并把结果包装成 ToolMessage 追加到状态。

这里有个容易犯的错误：直接拿 MCP 返回的原始内容当 ToolMessage 内容。我建议在 execute_tools 节点里做一个统一的结果整理，只把关键字段透出给模型，把无关的元信息过滤掉，这能显著减少模型的 Token 消耗，也能避免模型被大段原始 JSON 干扰判断。

4. 多 Server 并发调用的工程实践

4.1 多 Server 接入的前提：命名空间与工具重命名

单 Server 跑通之后，多 Server 就是水到渠成的事，但坑也在这个阶段开始密集出现。第一个绕不开的问题是命名空间。MultiServerMCPClient 支持同时连多个 Server，每个 Server 有一个 key，工具名会自动带上这个 key 作为前缀。

这个机制在规避冲突方面很有效，但也有反直觉的地方。模型在生成 tool_calls 时，看到的工具名是带前缀的完整名称。如果你某个 Server 里的工具名本来就带下划线，比如 get_current_weather，前缀拼完就变成 server_a__get_current_weather，这个双下划线容易让模型在生成参数时产生混淆，我实测中遇到过模型把前缀当成工具名一部分生成错误的情况。

如果你不想用这个约定的双下划线分隔，可以在 MultiServerMCPClient 里自定义工具的加载方式，手动把工具名映射成更容易理解的别名。不过我不建议过度改名字，因为工具名改动后，所有依赖老名字的缓存和日志都会失效，保持一致更利于排查问题。

连接多个 Server 时，另一个大坑是传输方式不能随意混用。stdio 的 Server 由客户端拉起子进程，生命周期跟父进程绑定；HTTP 的 Server 则常驻远端，连接是长连接。如果一个进程里同时有十个 stdio 子进程，每个子进程还要各拉起一份 Python 解释器，内存开销直接起飞。我建议把重的、频繁调用的工具服务化，挂成 HTTP Server；只剩那种临时性强的、不常用的工具才用 stdio 拉起。

4.2 多 Server 调用的状态管理与上下文传递

多 Server 场景下，状态管理的问题会被放大。单 Server 时，所有工具调用都发生在同一个连接里，上下文自然共享；多 Server 后，不同工具的调用可能发生在不同连接里，中间结果要不要保留、保留在哪里，就成了需要明确设计的问题。

我在 LangGraph 里的做法是把工具执行结果统一放进图的状态对象里，而不是留在各个 Server 自己的上下文中。这样做的原因很实际：LangGraph 的状态传递是显式的，一条消息经过哪个节点、产生了什么中间结果，都能在状态里看到，方便调试和审计。而如果依赖 Server 内部记忆，Server 进程一重启，状态就全丢了。

执行顺序也是个隐性坑。多 Server 工具之间的依赖关系如果处理不当，会出现“先查城市名，再查天气”这种需要两个 Server 协作的场景。我建议把有依赖关系的工具调用放在同一个节点里串行执行，把独立的工具调用放在不同节点里并行执行，这样既避免竞态，又能缩短整体耗时。

LangGraph 的节点支持异步并发，execute_tools 节点内部可以用 asyncio.gather 并行调用多个 MCP Server。但要注意，如果两个 Server 里有工具修改同一份外部资源（比如都写同一个数据库表），并发就会引发脏写。这种情况必须退回升序执行，或者引入分布式锁。

4.3 连接生命周期与资源回收

多 Server 的连接管理听起来枯燥，但踩坑率极高。最典型的问题是连接泄漏。MCP 客户端连接对象在创建后占据一个子进程或者一个网络连接，如果每次请求都新建连接又没关闭，跑一段时间后系统文件描述符会耗尽，出现各种莫名其妙的服务不可用错误。

我的做法是给每个 MCP Server 建一个独立的长连接池，复用同一个 client 对象处理多次请求，并在进程退出时统一释放。LangGraph 里推荐的做法是定义工具节点时传入一个共享的 client 容器，每个请求只是从容器里取连接，而不是重建客户端。

如果 Server 本身会动态加载工具（比如运行时扫描某个目录的插件），长连接状态下需要定期刷新工具列表。我踩过一个非常隐蔽的坑：某个 MCP Server 在启动后加载工具时失败了，但连接没有断开，客户端这边缓存了空工具列表，后续所有调用都报“工具未找到”。排查了半天，最后发现是刷新缓存的逻辑没写。所以，在做多 Server 接入时，一定要设计工具列表的定期刷新和手动刷新机制，不要默认它永远不变。

5. 高频问题排查实录

5.1 握手失败：版本、传输方式与超时

握手阶段最常见的报错是版本协商失败或连接超时。先说版本协商，客户端 initialize 请求里带 protocolVersion，如果 Server 端 SDK 版本过旧，不支持新版协议，Server 会拒绝或返回它自己支持的版本。这类错误通常不会直接提示“版本不兼容”，而是表现为连接建立后收不到任何有效响应。

排查时先看客户端 SDK 和服务端 SDK 的版本是否匹配，再看传输方式是否一致。stdio 传输出现超时，八成是启动命令写错了——比如 server 入口文件依赖没装、或者命令里写的路径不对，子进程根本没起来。HTTP 传输出现超时，先确认 server 的监听地址有没有绑定到正确网卡，再确认防火墙有没有拦截。

我在本地调试时还遇到过 stdio 传输下 stdout 被污染的情况。MCP Server 通过标准输出跟客户端通信，如果 Server 代码里有任何 print() 调试语句没清掉，输出流里混进非 JSON-RPC 内容，客户端解析就会报错。所以 MCP Server 里一切日志输出必须写到 stderr 或者日志文件，这是 stdio 模式下的硬性约束。

5.2 工具找不到 / 参数错误：注册与命名空间

工具列表为空或者调用时提示工具不存在，这类问题在多 Server 场景下特别常见。第一排查点是客户端是否在握手阶段正确声明了 tools capability，第二是 tools/list 是否触发了刷新，第三是工具名是否带了正确的前缀。

我整理了这样一张排错表，每次遇到问题直接按行查：

5.3 环境与权限：stdio 进程起不来怎么办

stdio 传输最常见的一类问题不在协议层，而在系统层：子进程启动失败或者权限不够。报错信息里经常出现类似“拒绝访问”或者“权限不允许”的字样，很多人看到后就一头扎进协议文档里找答案，其实问题很可能出在运行用户权限或者依赖环境上。

如果你用 Docker 跑 LangGraph 应用，容器里要确认已经装了 MCP Server 需要的运行时；如果你从宿主机直接拉起 stdio 子进程，要确认当前用户有执行该命令的权限，Command 路径也不能只写相对路径。我遇到过在代码里写死“python”而不是“python3”的情况，在部分 Linux 环境下直接拉起失败，改成显式指定解释器路径才解决。

另外一个环境相关的问题是多 MCP Server 之间的环境变量冲突。两个 Server 各自依赖不同的环境变量值，如果在同一个进程里加载，后加载的 Server 可能读到前一个 Server 设置的环境变量，导致行为异常。处理方式是在连接层为每个 Server 单独设置 env 参数，不要让它们共享全局环境。

5.4 排查工具与调试技巧

定位 MCP 问题，我常用的工具链其实很简单。抓协议报文看日志是第一选择，把 MCP SDK 的日志级别调到 DEBUG，就能看到完整收发内容；这是最直观的。其次是给 Server 端的工具函数入口加日志，记录入参和返回值，很多问题其实一眼就能看出来是参数没传对。

如果你在用 LangGraph，还有一个排查技巧是直接跳过模型层，手工构造一个 tool_calls 消息喂给 execute_tools 节点。这样能绕开模型变化带来的不确定性，直接验证 MCP 执行链路本身是否正常。这个思路非常有用，因为模型有时候会生成预期之外的工具参数，导致你误以为 MCP 调用挂了，其实是模型的问题。

对于 HTTP 类型的 MCP Server，我强烈建议你去通读一份服务端 access log。你在客户端看到的超时，在服务端日志里往往能看到完全不同的原因，比如请求体过大、线程池拥堵、或者对方在重试。我在一次排查中发现工具执行本身只花了 200 毫秒，但客户端等了 5 秒，原因是 HTTP 传输层的 keep-alive 超时设置太短，连接被频繁重建。这类问题看客户端日志是看不出来的。

5.5 多 Server 场景下的耗时分析与优化

多 Server 调用时，一个很现实的观察是：Agent 的整体响应时间，往往不是最慢的那个工具决定的，而是模型反复决策和工具调用轮次叠加的结果。模型可能存在“先试一个工具，失败后再换一个”的行为，这在本质上会成倍放大耗时。

我实测过一个场景：两个 MCP Server，一个提供搜索，一个提供天气，模型在回答“某城市今天适合穿什么”这个问题时，先调了搜索工具查天气，查完发现工具返回格式不理想，又调天气工具重新包装数据，整个流程多出一轮工具调用，耗时翻了一倍。

优化方法有两个层面。一是在提示词层面约束模型，明确告诉它优先使用哪个工具、什么情况才切换工具，减少无效轮次；二是在图结构层面，把能并发的工具节点设计成并行分支，而不是串行链路，把“模型先调 A 再调 B”改成“A、B 同时调，最后合并结果”。前者需要调提示词，后者需要调图结构，两者结合的优化幅度相当可观。

最后的小经验

折腾完这一整套 MCP 多 Server 接入，我最大的体会是：MCP 的协议学习曲线并不陡，真正陡的是工程化落地的细节。协议握手、工具注册、命名空间、状态管理、错误排查，每一环都有文档不会写清楚、只有实际跑过才会懂的坑。如果你也开始做类似的事情，我的建议是先把最小链路跑通，加上完整日志，再逐步扩展多 Server；调试时优先怀疑传输层和工具名，而不是怀疑协议本身。最后分享一个小习惯：凡是要接进 LangGraph 的 MCP 工具，我都先写一个独立的冒烟测试脚本，直接调用 MCP 客户端拿到工具列表并执行一次最简调用，确认没问题再放进图里，这样能把模型层的变量和协议层的故障彻底隔离，排查问题的速度能快上一倍。