企业官网建设流程全解析

最近好几个技术群里都在聊 MCP，有人卡在握手阶段报错，有人问 LangGraph 里怎么同时挂多个 MCP Server，还有人已经拿 MCP 接到 UE5、数据库甚至二进制分析工具里了。但大部分讨论都停在“怎么把一个 Server 配起来”这一步，一旦涉及到协议层的细节、多 Server 的编排调度，就各种踩坑。

我前阵子刚好在做一个基于 LangGraph 的多 Agent 工程，里面同时接了三个职责完全不同的 MCP Server：一个负责查数据库，一个负责操作在线文档，还有一个负责读日志和本地文件。过程中把 MCP 从协议握手到工具调用的整个链路都摸了一遍，踩了不少文档里根本不会写的坑。这篇就把整个链路拆开讲清楚：先从协议层面分析一次完整的握手过程，再说 MCP 工具在 Agent 里是怎么被发现和调用的，最后落到 LangGraph 里的多 Server 调用方案，代码、参数、排查思路都放在里面。适合正在研究 MCP、想把多个 MCP Server 集成进自己 Agent 系统的朋友。

1. MCP 到底是什么：协议模型与应用场景

1.1 它解决的痛点：从“N 个模型 × M 个工具”到统一接口

在没有 MCP 之前，让大模型去调用一个外部工具，基本是各干各的：有的框架用 Function Calling，有的用插件机制，有的直接让模型生成一段代码再去执行。每接一个新工具，都要写一套适配代码，而且换一个 Agent 框架，这套代码大概率要重写。这就像家里买了一堆电器，但每个电器都带一个专用插座，换一个牌子的插线板就全部作废。

MCP 做的事情就是定义一个“标准插座”：工具提供方按照统一协议把能力暴露成 Server，模型应用侧按照统一协议去连接和调用。只要两边都遵守这个协议，工具和 Agent 就可以任意组合，不再关心对方内部是怎么实现的。做过几年后端的朋友应该马上能反应过来，这本质上就是“接口标准化”的思路，和 HTTP、JDBC 解决的问题一模一样，只不过这次是给大模型和外部世界之间定义的接口标准。

1.2 核心角色：Host、Client、Server 各司其职

MCP 的架构里有三个角色，很多初学的朋友容易搞混，我用一句话帮大家理清：

• Host 是“宿主程序”，也就是你正在跑的 Agent 框架、IDE 或者业务系统，它负责管理整个会话和上下文。
• Server 是“能力提供方”，比如一个数据库查询服务、一个文档处理服务，它以独立进程或远程服务的形式存在，把能力包装成标准接口暴露出来。
• Client 是“连接器”，它跑在 Host 里面，负责和 Server 建立连接、收发消息。一个 Host 可以同时持有多个 Client，每个 Client 连接一个 Server。

可以这么理解：Host 是餐厅，Server 是后厨，Client 是传菜员。你（用户）坐在餐厅里点菜，传菜员根据菜单（工具列表）去后厨把菜端过来，整个过程有一个统一的传菜标准，不会因为换了后厨就乱套。

1.3 传输方式与能力面：stdio 和 Streamable HTTP 怎么选

MCP 的通信底层有两种常用传输方式。本地场景用 stdio：Host 通过子进程启动 Server，用标准输入输出传 JSON 消息，简单高效，适合把 Python 脚本、命令行工具包装成 MCP Server。跨机器或独立部署场景用 Streamable HTTP：Server 跑成一个 HTTP 服务，Host 通过 HTTP 请求去调用，适合多客户端共享同一个 Server 的情况。

选型建议很简单：所有东西都在同一台机器上，优先用 stdio；Server 要部署到远程或要供多个客户端复用，就用 Streamable HTTP。两种方式之上跑的是同一套 MCP 协议，所以后面讲的握手、工具调用流程都是一样的。

MCP Server 能暴露的能力面有三类：Tools（工具，让模型执行动作）、Resources（资源，让模型读取数据）、Prompts（提示模板，预置一些 Prompt 片段）。这三者才是 MCP 的完整能力模型，后面我会重点展开 Tools 和 Resources。

2. 协议握手拆解：initialize 请求到底在做什么

2.1 先搞清楚通信底座：JSON-RPC 2.0

MCP 的所有通信都建立在 JSON-RPC 2.0 之上。这是一个非常轻量的远程调用协议，请求和响应都是 JSON 格式，每个请求带一个唯一 id，响应里带上同一个 id 来对应。举个例子：

// 请求 {"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {...}} // 响应 {"jsonrpc": "2.0", "id": 1, "result": {...}}

另外还有一类消息叫 notification（通知），它没有 id，也不需要响应。MCP 里的 initialized 通知就是典型代表。

我见过有的开发者想绕开官方 SDK，自己用裸 WebSocket 或 TCP 去实现 MCP 通信，结果在 JSON-RPC 的 id 对应关系和 notification 处理上吃了不少亏。建议除非有特殊需求，否则直接用官方 SDK，把精力放在业务逻辑上。

2.2 initialize 请求里到底带了什么

一次完整的 MCP 会话，Client 连上 Server 后必须先发一个 initialize 请求，这是握手的起点。这个请求的 params 里包含三个关键字段：protocolVersion、capabilities、clientInfo。

protocolVersion 是客户端声明的协议版本号，比如一段常见的版本号是“2025-06-18”，不要把它跟 SDK 的版本号搞混。capabilities 是客户端自身能力的声明，比如你支不支持读取 Resources、支不支持采样（sampling）等。clientInfo 就是客户端自己的名称和版本，相当于自我介绍。

很多人写握手代码时图省事，直接把 protocolVersion 写死成一个字符串，这是非常容易踩坑的做法。因为 Server 端有自己的版本支持范围，如果两边版本差太多，握手直接失败。正确做法是用 SDK 导出的协议版本常量，让它跟着 SDK 走，升级 SDK 时不会因为版本号对不上而出问题。

2.3 握手响应与版本协商

Server 收到 initialize 请求后，会在响应里返回自己的 protocolVersion、capabilities、serverInfo。这里最有意思的是版本协商机制：Server 会检查客户端声明的版本自己支不支持，如果不支持，它会尝试返回一个自己支持的、兼容的版本；如果两边版本差距实在太大，Server 会直接在错误信息里告诉你协议版本不兼容。

我用一段极简代码模拟一下这个过程，把一次握手看的明明白白。这里直接通过 subprocess 启动一个 MCP Server，然后手动拼一个 initialize 请求发过去：

import json import subprocess proc = subprocess.Popen( ["python", "demo_server.py"], stdin=subprocess.PIPE, stdout=subprocess.PIPE, text=True, ) req = { "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": { "protocolVersion": "2025-06-18", "capabilities": {}, "clientInfo": {"name": "handshake-demo", "version": "1.0.0"}, }, } proc.stdin.write(json.dumps(req) + "\n") proc.stdin.flush() line = proc.stdout.readline() print("握手响应:", line) proc.terminate()

正常情况下，你会看到响应里带回了 Server 选定的 protocolVersion，以及它声明的 capabilities 和 serverInfo。如果服务器发现客户端版本太老，响应里通常会有对应的错误编号和提示。通过这种方式，你可以不依赖任何 SDK 就完成一次 MCP 握手，对理解协议本身非常有帮助。

2.4 initialized 通知：比你想的重要得多

握手不是发一个 initialize 就完事了，客户端在收到 initialize 响应后，必须再发一个 notifications/initialized 通知给 Server，告诉它“初始化已完成，可以正常进行业务通信了”。

很多第一次写 MCP 代码的人会漏掉这一步，结果就表现为：明明 initialize 成功了，但紧接着发 tools/list 请求却超时或者直接被 Server 忽略。原因就是 Server 还在等那个 initialized 通知，它认为会话还没有真正建立。

我再强调一下：initialize 是 request/response，有响应；initialized 是 notification，不需要响应。一个是握手本身，一个是握手完成后的“确认信号”，两者缺一不可，顺序也不能反。

2.5 能力协商的真正影响

握手阶段声明的 capabilities 不只是礼貌性的自我介绍，它直接影响后续请求的可用性。比如说，你的客户端在 initialize 里没有声明支持 Resources 能力，那么 Server 在收到 resources/list 请求时，完全有理由返回空列表或明确报错。

这背后的设计逻辑其实很合理：Server 根据客户端的能力来裁剪自己的返回内容，避免把客户端消化不了的数据一股脑丢过去。所以在排查“某个工具/资源列表突然为空”的问题时，第一时间回看握手里客户端 capabilities 是怎么声明的，往往比查 Server 配置更有效。

3. 工具调用链路：从 tools/list 到 tools/call

3.1 工具发现：模型怎么知道有哪些工具可用

握手完成后，Client 会调用 tools/list 方法向 Server 获取可用工具列表。Server 返回的每个工具包含三个核心字段：name（工具名）、description（工具描述）、inputSchema（参数约束，用 JSON Schema 描述）。

这里有一个容易被忽略的细节：description 的质量直接影响模型调用工具的准确性。我实际测试下来，如果 description 里能写清楚参数枚举值、边界条件、返回值结构，模型传入非法参数的概率会明显下降。比如一个查询工具，如果只在 description 里写“查询订单”，模型可能不知道传什么参数；如果写成“查询订单，status 参数只接受 pending/completed/cancelled，返回最近 20 条记录”，模型几乎不会出错。

3.2 工具调用：tools/call 的完整流程

当模型决定调用某个工具时，Client 会发送一个 tools/call 请求，方法名是 tools/call，参数里带上工具名和 arguments（参数字典）。Server 执行完业务逻辑后，返回一个 callToolResult，里面主要包含 content（内容数组）和 isError（是否是业务错误）。

这里我要特别提醒一点：MCP 协议里，业务错误和数据返回在传输层可能都是 200 状态。isError 这个字段才是区分“调用成功但业务没办成”和“调用异常”的关键。我在做日志系统的时候，一开始只检查有没有异常，结果把业务失败的数据也当成正常数据处理了，最后统计数据全偏了。

在 LangChain 的 MCP 适配层里，isError=true 的返回会被包装成一个错误消息回传给模型，让模型自己决定怎么处理这个失败的调用结果，而不是直接中断整个 Agent 流程。

3.3 Resources：不只是“读文件”那么简单

热词里有人提到“mcp resource 实战”，这块确实是 MCP 里最容易忽略的能力。Resources 用 URI 寻址，比如 file:///etc/config、db://orders、notion://page/xxx，Server 通过 resources/list 暴露资源列表，通过 resources/templates/list 暴露动态资源模板。

资源模板非常有用，它定义了一类资源的 URI 模式，比如 file:///{path} 表示“任意路径下的文件”。客户端可以先通过模板了解有哪些资源可读，再按需去读具体的数据。

在 Agent 里的实际用法是：Tools 负责操作和产生副作用，Resources 负责提供上下文。比如让一个运维 Agent 排查问题，可以先通过 Resources 读取服务配置和日志索引，再通过 Tools 去执行具体的数据查询。先“读后生知”，再“动手执行”，整个链路清晰很多。下面这段代码展示了一个简单的文件读取 Server 如何暴露资源：

from mcp.server import Server from mcp.server.stdio import stdio_server import mcp.types as types app = Server("resource-demo") @app.list_resources() async def list_resources(): return [ types.Resource( uri="file:///etc/hostname", name="hostname", mimeType="text/plain", description="当前机器的主机名文件" ) ] @app.read_resource() async def read_resource(uri: str): if uri == "file:///etc/hostname": with open("/etc/hostname", "r") as f: return [types.TextContent(type="text", text=f.read())] raise ValueError(f"Unsupported resource: {uri}")

4. LangGraph 集成 MCP：多 Server 调用的工程方案

4.1 为什么偏偏选 LangGraph

市面上的 Agent 框架不少，LangGraph 的核心优势在于它是一种“图编排”模型：把 Agent 逻辑拆成节点，节点之间用边连接，支持条件分支、循环和状态持久化。对多 Server 场景来说，这个图结构特别有价值，因为你可以把“调用数据库 Server”“调用文档 Server”拆成不同的节点，让流程控制权掌握在图里，而不是全丢给模型的自由发挥。

如果只是在 Prompt 里堆一堆工具让模型自己去选，Server 少还好，Server 一多，工具之间就互相干扰：模型可能选错工具、可能在一个工具上反复重试、也可能忽略了关键路径上的某个 Server。用 LangGraph 显式地控制编排顺序，能显著提高流程的确定性。

4.2 单 Server 接入：先跑通最小闭环

在搞多 Server 之前，我强烈建议先跑通一个 Server 的最小闭环。用官方的 mcp SDK 和 langchain-mcp-adapters，接入一个 Server 的代码非常简洁：

from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client from langchain_mcp_adapters.tools import load_mcp_tools server_params = StdioServerParameters( command="python", args=["calendar_server.py"], ) async with stdio_client(server_params) as (read, write): async with ClientSession(read, write) as session: tools = await load_mcp_tools(session) # 把 tools 交给 LangGraph 或 LangChain Agent

这一小段代码完成了：启动子进程、建立 stdio 连接、MCP 握手、加载工具列表。如果你的环境在这个步骤就报错，先别急着上 LangGraph，问题几乎一定出在 MCP 连接层。

4.3 多 Server 接入：MultiServerMCPClient 的正确姿势

当你需要同时接多个 Server 时，langchain-mcp-adapters 提供了 MultiServerMCPClient，它的设计就是为多 Server 场景准备的。用法如下：

from langchain_mcp_adapters.client import MultiServerMCPClient config = { "calendar": { "transport": "stdio", "command": "python", "args": ["calendar_server.py"], }, "files": { "transport": "stdio", "command": "python", "args": ["file_server.py"], } } async with MultiServerMCPClient(config) as client: tools = client.get_tools() # tools 里已经包含了两个 Server 的工具

这里有一个非常贴心的设计：当多个 Server 的工具名出现冲突时（比如两个 Server 都有叫 search 的工具），连接器会自动给工具名前加上 Server 名前缀，比如 calendar__search 和 files__search。这样模型就不会因为工具重名而调用错 Server。

我实际测试下来，这个工具隔离方案在 LangGraph 里非常顺手。给模型看的工具描述里会明确包含“这个工具属于 xxx Server”的信息，模型在选择工具时有了更强的上下文依据。

4.4 多 Server 调用时的四个关键问题

第一个是并发初始化。MultiServerMCPClient 默认会逐个建立连接，如果 Server 多了，串行初始化耗时很长。我建议并发启动握手，用 asyncio.gather 把多个 Server 的连接和初始化分散到并发任务里，实测下来能把初始化时间压缩到原来的三分之一。

第二个是故障隔离。一个 Server 挂掉时，不能拖垮整个 Agent 执行链路。很多人在 LangGraph 节点里直接调用 tools 拿到异常就抛，引发整个图终止。合理做法是把异常捕获后转成一条“该 Server 当前不可用”的消息回传给模型，让模型决定是否用其他 Server 完成替代方案。

第三个是上下文传递。MCP Server 本身是无状态的，每次调用都必须传递完整参数，跨 Server 的数据不能指望 Server 之间互相通信。在 LangGraph 里，一切跨 Server 的数据都通过 State 来传递。比如先从数据库 Server 查出一笔订单，再调用通知 Server 去发消息，那订单数据必须先存在于 LangGraph 的 State 里，然后才能作为参数传给第二个 Server。

第四个是超时控制。MCP Client 默认的读取超时可能不太适合业务场景。曾有一个远程 Server 处理大文件时，单次工具调用跑了超过默认超时时间，Client 直接给模型返回超时错误。我的做法是给 Client 设置一个可配置的读取超时，并根据不同 Server 的响应特性区分超时档位。

4.5 安全与权限：本地和远程都不省心

本地 stdio 模式下，MCP Server 是子进程，继承当前用户的权限。我第一次在 Windows 上启动 Server 时就遇到了“拒绝访问 (os error 5)”，后来发现是工作目录和命令路径权限的问题，用管理员身份运行不是根本解，正确做法是给启动 Server 的调用方配置好目录的读写权限，并把 Server 代码放到一个独立的、权限清晰的目录里。

远程 MCP Server 如果带了 OAuth 认证，报“token exchange failed”这类错误时，我排查下来的原因基本上集中在：授权服务器的 token endpoint 地址配置错误、client_id/secret 不匹配、系统时钟偏移导致 token 被判定过期。遇到这类问题，先把授权链路的配置一项项对一遍，大概率能定位到问题源头。

5. 实操记录：从 zero 搭建一个 LangGraph + 多 MCP 的 Agent

5.1 环境准备与依赖安装

我用的版本组合是 Python 3.11 + mcp 1.x + langgraph 0.2.x，这组版本目前的兼容性验证过，比较稳。安装依赖用下面命令：

pip install "mcp[cli]" langgraph langchain-openai langchain-mcp-adapters

这里要提醒一句：mcp 包和 langchain-mcp-adapters 是独立演进的，升级 mcp 后适配层经常会报兼容性错误。我建议在项目里锁定主要版本，统一升级，不要单独升级某一个包。

5.2 准备两个实验 Server

我会准备两个最简单的 Server 来演示多 Server 调用。

第一个是日历查询 Server，用 MCP 官方 SDK 写一个最简单的 stdio Server。下面这段代码可以直接存成 calendar_server.py 运行：

from mcp.server import Server from mcp.server.stdio import stdio_server import mcp.types as types from datetime import datetime, timedelta app = Server("calendar-server") @app.list_tools() async def list_tools(): return [ types.Tool( name="get_upcoming_events", description="获取未来几天内的日程事件，days 参数表示未来第几天", inputSchema={ "type": "object", "properties": { "days": { "type": "integer", "description": "未来第几天，从0开始", } }, "required": ["days"], }, ) ] @app.call_tool() async def call_tool(name: str, arguments: dict): if name == "get_upcoming_events": days = arguments.get("days", 0) now = datetime.now() + timedelta(days=days) return [ types.TextContent( type="text", text=f"{now.strftime('%Y-%m-%d')}: 有一个产品评审会议，14:00在301会议室", ) ] raise ValueError(f"Unknown tool: {name}") async def main(): async with stdio_server() as (read_stream, write_stream): await app.run(read_stream, write_stream) if __name__ == "__main__": import asyncio asyncio.run(main())

第二个是文件查询 Server，可以做简单文件读取。这里有个实际用途：Agent 排查问题时，需要读取配置或日志文件，通过 MCP 暴露文件读取能力，比让模型直接拼接路径更安全可控。

当然，真实业务里的 Server 会比这复杂得多，但这两个已经足够验证多 Server 调用流程了。

5.3 构建 LangGraph 图：把多 Server 工具编排进去

先定义 LangGraph 的 State，也就是 Agent 的消息状态：

from typing import Annotated from typing_extensions import TypedDict from langgraph.graph import StateGraph, START, END from langgraph.graph.message import add_messages class AgentState(TypedDict): messages: Annotated[list, add_messages]

然后实现一个调用模型的节点：

from langchain_openai import ChatOpenAI from langgraph.prebuilt import ToolNode, tools_condition llm = ChatOpenAI(model="gpt-4o", temperature=0) def call_model(state: AgentState): messages = state["messages"] response = llm_with_tools.invoke(messages) return {"messages": [response]}

接下来把 MultiServerMCPClient 的工具列表注入，并用 StateGraph 组装图：

async def build_graph(): client = MultiServerMCPClient({ "calendar": { "transport": "stdio", "command": "python", "args": ["calendar_server.py"], }, "files": { "transport": "stdio", "command": "python", "args": ["file_server.py"], } }) async with client as mcp_client: tools = mcp_client.get_tools() llm_with_tools = llm.bind_tools(tools) builder = StateGraph(AgentState) builder.add_node("agent", call_model) builder.add_node("tools", ToolNode(tools)) builder.add_edge(START, "agent") builder.add_conditional_edges("agent", tools_condition, {"tools": "tools", END: END}) builder.add_edge("tools", "agent") graph = builder.compile() return graph

这段代码的精髓在于 tools_condition 和 ToolNode 的配合：模型决定要调用工具时，图自动跳转到 tools 节点执行工具；工具执行完，把结果作为消息放回 State，再回到 agent 节点继续推理，直到模型不再请求工具，图才走到 END。多 Server 的工具全部被放在同一个 ToolNode 里，但每个 Server 的名称前缀保证了互不干扰。

5.4 运行验证与流式输出

运行图时，我用流式模式来观察每一步的执行情况：

async def main(): graph = await build_graph() inputs = { "messages": [ { "role": "user", "content": "帮我看看后天有什么日程，然后把结果保存到 notes.txt", } ] } async for event in graph.astream(inputs, stream_mode="updates"): for node, value in event.items(): print(f"节点: {node}") print(f"输出: {value}")

你会看到图先进入 agent 节点，模型决定调用日历 Server 的工具，然后图跳到 tools 节点执行工具调用，再把结果传回 agent，最后模型又决定调用文件 Server 的工具去写文件。每一步的流转都清清楚楚。

流式输出在真实项目里非常重要。用户看到的不再是“模型在思考”的圈圈，而是“正在查询日历”“正在写文件”这样的实时状态。热词里有人问“使用 MCP 工具流式输出内容到文件”，这在 LangGraph 里天然支持：把流量输出到事件流里，前端按 event 展示每个节点的执行状态即可。

6. 常见问题与排查技巧实录

6.1 握手失败类问题速查

我实际遇到最头疼的还是“工具列表为空”这个问题。当时 Client 的 capabilities 配置里漏掉了对 Resources 的声明，Server 就顺理成章地隐藏了相关工具，排查了好久才在探索 Server 调试面板时发现原因。记住一条规律：MCP 的权限是双向的，Client 声明了什么，Server 才会给什么。

6.2 工具调用异常：模型参数乱传怎么办

工具调用的第一杀手是模型生成的参数不符合 JSON Schema。LangGraph 的 ToolNode 会尝试把这些非法参数传给 MCP Server，如果 Server 端校验严格，直接报错，整个 Agent 流程就被打断了。

我的处理方式是在工具适配层做一层参数清洗：把模型传进来的 kwargs 和工具的 inputSchema 做一次白名单过滤，只保留 Schema 里声明过的字段，再把参数类型按 Schema 做一次强转。比如 Schema 要求某种类型是整数，但模型传了个字符串“3”，就手动转成 3。这样做之后，因参数格式问题导致的工具调用失败率降低了很多。

6.3 LangGraph 多 Server 的上下文串扰问题

多 Server 场景里，最容易出现的问题是“上下文串扰”：模型在前一段对话里用过数据库 Server，后一段对话里遇到类似问题，直接走了数据库 Server 而不是文档 Server。这其实是工具描述不够清晰导致的。

我推荐在每个工具的 description 里显式加上所属 Server 和适用场景，比如“来自 calendar Server，用于查询日程；如果要写文件请用 files Server 的工具”。这样模型在选择路径时就有了更明确的分界。

另一个上下文问题发生在 State 里：工具返回结果如果太大，消息列表会迅速膨胀，最后超出模型上下文窗口。我的做法是在工具返回节点里加一个“摘要步骤”：把工具返回的长文本先做一个摘要再放到 State 里，只保留关键信息，既节省 token，又避免上下文被无关细节污染。

6.4 调试 MCP 的通用技巧

官方提供的 MCP Inspector 调试面板非常值得用。它可以在浏览器里可视化地打开一个 MCP Server，直接观察握手过程、工具列表、参数格式和调用响应，排查协议层问题比看代码日志快得多。

stdio 模式下要观察真实流量，我给 Server 的入口包一层打印装饰器，把收发 JSON 全部打出来，再开 MCP 的 DEBUG 日志环境变量，就能清楚看到一次握手里每个请求的走向。

最后一个建议是：把每个 MCP Server 都放到尽量隔离的环境里运行，比如用容器管理。不同 Server 的 Python 依赖、Node 版本、工作目录很容易互相影响，隔离运行能省掉很多冤枉的排查时间。

我个人实际做下来最大的体会是：多 Server 调用真正难的往往不是 MCP 协议本身，而是如何让 Agent 在不同 Server 之间有序切换。协议和框架只是给你提供了标准接口和编排能力，真正决定体验的，是你对工具命名、描述、参数约束和错误处理这些细节的把控。

最后分享一个小技巧：我会给每个 MCP Server 额外暴露一个 health 资源，Agent 在开始正式任务之前先批量“探活”一遍所有 Server，确认可用再进入业务流程。这样很多中途超时的问题，在任务启动那一刻就被拦截了，比事后排查要省心得多。