最近这半年MCP 的热度涨得比我预想快得多。最开始我只是把它当成 Claude 的一个附属协议后来发现 Cursor、Codex、Dify 甚至 IDA 和 x32dbg 都在往这边靠才意识到这套东西已经不只是“某个大厂的私有规范”而是正在变成模型和外部工具之间的通用接口层。这篇文章我想从协议握手开始讲起把我自己从写 MCP Server、再到把它接进 LangGraph 做多 Server 编排的完整过程梳理一遍重点放在那些文档不会写的细节和真正踩过的坑上。1. 为什么要关注 MCPAI 工具调用从“各写各的适配”走向“一套接口接所有”1.1 一个让我彻底放弃自研工具层的上午当时我在做一个内部运营助手需要让 Agent 同时查订单数据库、调用订单系统的 HTTP 接口、再读取本地文件做汇总。最早的方案非常直接把业务逻辑写成普通 Python 函数用 JSON Schema 声明参数然后塞给大模型做 function calling。本地跑没问题但一旦遇到下面这些场景就开始难受同一个工具脚本A 项目用 LangChainB 项目用原生 OpenAI SDKC 项目用的是公司自研的编排框架每个接入方都要重写一遍工具注册代码。某一天模型供应商调整了工具调用的消息格式function calling 的返回结构变了所有下游解析逻辑全部要跟着改。数据库、文件系统、第三方 API 这些能力散落在各个服务里没有统一入口Agent 想用的时候得靠 prompt 告诉它“该去哪找”。那天上午我在改第三套适配层的时候突然意识到问题不在某个框架而在缺少一个层——工具提供方和工具消费方之间的公共契约。MCP 恰好就是来解决这个的。它把工具、数据源、提示模板统一描述成 JSON-RPC 服务任何支持 MCP 的客户端都能通过同一套握手流程去发现和调用能力。1.2 MCP 的三原语Tool、Resource、Prompt 各自的定位MCP 规范里定义了三种核心能力刚上手的人容易混淆我拿实际例子说明Tool对应一次可执行的操作。比如“查询订单状态”“取消订单”“创建工单”它会带一个 JSON Schema 参数声明模型根据描述决定何时调用。这是整个协议里用得最重的东西。Resource对应只读的数据入口类似“通过 URI 暴露出来的一份文件或一个记录”。比如把订单详情暴露成app://orders/A001客户端可以直接读取内容而不需要执行任何函数。Prompt对应可复用的提示模板。Server 端可以定义一套带参数的模板客户端获取后填入变量生成最终 prompt。理解它们的关键在于Tool 是“会改变状态的操作”Resource 是“可以被引用的数据”Prompt 是“拼好的话术模板”。在工程上Resource 和 Prompt 的使用频率远低于 Tool但它们解决的是同一个问题的另外两面——有些能力适合交给模型主动调用有些适合预先加载到上下文里。1.3 生态在快速收敛从 IDE 到安全逆向、再到游戏引擎都在接入MCP 之所以值得花时间研究是因为接入方已经超出了大模型厂商自己的圈子。我看到的几个典型方向开发工具IDE 插件通过 MCP 把编辑器能力暴露给 Agent通义灵码这类插件也能配置 MCP 连接 Oracle 等数据源。逆向与安全分析IDA 和 x32dbg 都有 MCP 插件这意味着大模型可以直接在调试器里查函数、看反汇编、读内存这条路对安全分析工作流的影响非常直接。设计与游戏引擎Figma MCP 允许模型读取设计稿信息Unreal 5.8 方向也有人在做 MCP 适配Codex 接入蓝湖 MCP 这类需求也在出现。传统数据领域不少团队在尝试给 SQL Server、PostgreSQL 这类数据库套一层 MCP Server让 Agent 用自然语言查库。你会发现 MCP 正在变成“模型与硬件软件之间的 USB 接口”——不管背后是什么系统只要规范一致就能插上即用。这种收敛太快提前掌握协议细节的人在做 Agent 工程时会有明显优势。2. 协议握手里的那些细节从 initialize 到 tools/call 的完整一次会话2.1 传输层选择stdio 和 Streamable HTTP 各自的适用面MCP 的传输层是理解协议的第一步因为握手流程虽然相同但不同传输模式下连接管理方式完全不一样。目前主流是两种传输方式连接模式适用场景需要注意的点stdio客户端把 Server 作为子进程拉起通过 stdin/stdout 传输 JSON-RPC 消息本地工具、开发环境、私有化部署不能跨机器访问子进程崩溃即断连stdout 必须只走协议消息Streamable HTTP客户端向固定 URL 发 POST 请求服务端返回 JSON 或 SSE 流远程服务、多客户端共享、生产环境需要处理会话 ID需要鉴权注意超时与连接复用我刚开始做的时候直接用了 stdio因为本地调试最简单。等到要让团队其他服务远程调用时才改成 Streamable HTTP。这里有个容易忽略的点MCP 的 stdio 传输与 LSP 不同消息不是靠 Content-Length 头分帧的而是每条 JSON-RPC 消息单独占一行以换行符分隔。所以如果你自己写底层通信千万不要往 stdout 里打印任何日志否则客户端解析 JSON 时会直接报错。2.2 initialize 握手协议版本和能力协商MCP 会话开始前必须做一次官方意义上的“握手”流程是这样的客户端发送initialize请求带上自己支持的协议版本、客户端信息和能力声明。服务端返回它支持的协议版本、服务端信息和能力声明。客户端确认兼容后发送notifications/initialized通知。之后双方才能开始业务方法调用。一次真实的握手长这样。客户端发出{ jsonrpc: 2.0, id: 1, method: initialize, params: { protocolVersion: 2025-06-18, capabilities: { roots: { listChanged: true }, sampling: {} }, clientInfo: { name: my-agent, version: 0.1.0 } } }服务端响应{ jsonrpc: 2.0, id: 1, result: { protocolVersion: 2025-06-18, capabilities: { tools: { listChanged: true }, resources: { subscribe: true, listChanged: true } }, serverInfo: { name: order-server, version: 1.0.0 } } }协议版本是个类似2025-06-18的日期字符串。客户端声明一个较新的版本服务端如果只支持到某个旧版本会在响应里返回它自己支持的版本最终双方取一个都能接受的值继续通信。如果差距太大、客户端完全无法兼容那就只能断开连接。这个降级机制本身很简单但很容易被忽略——我自己就遇到过客户端固化了新版本协议服务端是旧版 SDK 实现握手直接失败的情况。2.3 tools/list 与 tools/call一次工具调用的真实请求链路握手完成后客户端会先调用tools/list获取工具列表。请求{ jsonrpc: 2.0, id: 2, method: tools/list, params: {} }响应里是带描述和参数 Schema 的工具数组{ jsonrpc: 2.0, id: 2, result: { tools: [ { name: query_order, description: 查询订单状态, inputSchema: { type: object, properties: { order_id: { type: string } }, required: [order_id] } } ] } }真正调用时走tools/call{ jsonrpc: 2.0, id: 3, method: tools/call, params: { name: query_order, arguments: { order_id: A001 } } }服务端拿到参数执行逻辑然后返回结构化结果。内容是数组形式常见的是text类型{ jsonrpc: 2.0, id: 3, result: { content: [ { type: text, text: {\status\:\shipped\,\eta\:\2025-01-10\} } ], isError: false } }注意isError这个字段它表示“工具本身的业务执行是否失败”比如查询不到订单可以返回isError: true这跟协议层的错误比如方法名不存在不是一回事。客户端处理时要区分HTTP 或者 JSON-RPC 层面的错误说明通信链路有问题isError: true说明业务逻辑有问题Agent 需要根据返回内容重新规划。2.4 握手失败现场版本不匹配、stdout 被污染、会话失效协议设计看着不复杂真正跑起来时踩到的坑基本都是细节。我列几个高频失败现场stdio 模式 stdout 被污染Server 代码里用了print调试直接把日志打到 stdout客户端在读取下一行协议消息时拿到{level:INFO...}这样的非 JSON 文本直接解析失败。解决办法只有一个日志一律写到 stderr。Windows 权限差异导致连接失败父进程以管理员权限启动子进程环境不一致stdio 管道连接异常甚至出现 “拒绝访问” 这类报错。处理经验是保证父子进程在同权限环境或者干脆改用 HTTP 传输。HTTP 会话 ID 失效Streamable HTTP 模式下服务端返回了Mcp-Session-Id客户端第二次请求时如果没有带上服务端会认为不是同一个会话握手状态对不上。很多对接问题最后都查到这里。token 交换失败远程 HTTP Server 如果接了 OAuth 或 API Key 鉴权token 过期后 Agent 拿旧凭证继续调用第一次握手就 401。需要在客户端实现令牌刷新而不是只做一次静态注入。这些坑的共同点是协议本身不复杂难的是把传输、鉴权、生命周期管理做完整。3. 从零写一个可 Debug 的 MCP Server选型、实现与调试3.1 框架选型FastMCP、原生 SDK 与 TypeScript SDK自己动手写 Server 时选型直接决定了前期的工作量。我试过三种路线FastMCPPython目前我最推荐的入门方式。它把 initialize、tools/list、tools/call、ping 这些协议细节全封装了你只需要注册函数装饰器一加就是一个 Server。大量社区项目都用它排错成本最低。官方 Python SDKmcp 库更贴近协议的原始结构适合需要精细控制消息流和通知机制的场景但对新人来说样板代码偏多。TypeScript SDK如果你后续要复用 npm 生态或者 Server 本身要嵌在 Node 服务里可以选这条。TypeScript SDK 的异步模型更接近前端开发习惯但多一层构建步骤。我的建议是想快速验证想法就 FastMCP要上生产再根据语言生态决定。反正核心接口都是一样的后面切换成本不高。3.2 实现一个订单查询工具集注册 Tool 与 Resource假设我们要做一个订单服务的 MCP Server暴露查询订单、取消订单、查看订单详情三个能力。用 FastMCP 实现是这样from mcp.server.fastmcp import FastMCP mcp FastMCP(order-server) mcp.tool() def query_order(order_id: str) - dict: 查询订单当前状态 # 这里实际会去调内部订单服务接口 return {order_id: order_id, status: shipped, eta: 2025-01-10} mcp.tool() def cancel_order(order_id: str, reason: str user_request) - bool: 取消指定订单 # 调用订单服务的取消接口 return True mcp.resource(app://orders/{order_id}) def order_resource(order_id: str) - str: 返回订单详情的文本化内容适合加载到上下文 return fOrder {order_id}: statusshipped, items2, total299.00 if __name__ __main__: mcp.run()mcp.tool()会从函数的类型注解和 docstring 自动生成 JSON Schema所以写工具函数时不要偷懒——参数类型要写清楚描述要说明用途和边界条件。模型能不能正确调用工具很大程度上取决于这段描述的质量。mcp.resource()则是把数据暴露成可读取的资源 URI。客户端可以直接读取这个 URI 拿内容而不需要经过工具调用。实际项目里我经常把“订单详情、数据字典、配置信息”这类数据设计成 Resource让 Agent 在需要背景信息时主动拉取而不是塞进工具参数里。3.3 本地调试三板斧Inspector、stderr 与超时验证写完之后别急着接 Agent先用官方调试工具验证。个人经验是这三步启动 MCP Inspector在 Server 目录下跑npx modelcontextprotocol/inspector然后根据提示填入启动命令。浏览器里会出现一个调试面板能看到初始化握手是否成功、工具列表长什么样、每次调用的完整请求和响应。把所有日志定向到 stderrServer 内部无论用什么日志库输出目标必须是 stderr。我在调试时甚至会在代码里临时加sys.stderr.write来打点这样既能看流程又不会污染协议流。测试慢调用如果某个工具耗时较长比如查询一个几百 GB 的数据库客户端默认超时时间可能不够。我一般会先模拟一个延迟 10 秒的工具确认客户端超时配置是否生效提前暴露问题。4. LangGraph 多 Server 调用的工程化连接管理、命名冲突与状态流转4.1 为什么选 LangGraph可编排的图执行 vs 普通函数内联当 Server 数量超过两个以后直接在脚本里手动维护 MCP 连接就变得很痛苦。我选择 LangGraph 的核心原因有两个显式的图结构Agent 的决策、工具执行、条件分支都能画成一张有向图相比“一个 ReAct 循环里堆所有工具”的方式你能清楚地控制每个节点的职责。比如数据库查询和高危删除操作拆成不同节点权限边界更清晰。状态可持久化与可恢复LangGraph 的 State 贯穿整张图支持检查点机制。Agent 跑到一半中断了可以从检查点恢复这对真实生产任务的价值非常大。如果你是第一次接触 LangGraph可以把它理解为“给 Agent 流程加了一张工程蓝图”普通函数调用是“我直接调用下一步”但图执行是“根据当前 State 判断下一步走哪条边”。这种可控性正是多 Server 编排需要的。4.2 MultiServerMCPClient 接入多个 Server 的标准姿势LangChain 生态里已经有现成的 MCP 适配层我用的是langchain-mcp-adapters里的MultiServerMCPClient。它允许一次连接多个 Server并在进入上下文时自动完成握手和工具拉取。from langchain_mcp_adapters.client import MultiServerMCPClient mcp_clients MultiServerMCPClient( { order: { command: python, args: [servers/order_server.py], transport: stdio, }, knowledge: { url: http://localhost:8100/mcp, transport: streamable_http, headers: {Authorization: Bearer YOUR_TOKEN}, }, database: { url: http://127.0.0.1:8200/mcp, transport: streamable_http, }, } ) async with mcp_clients: tools_map mcp_clients.get_tools()这里tools_map是按 Server 名分组的工具字典比如{order: [query_order, cancel_order], knowledge: [...], database: [...]}。注意async with不是可选项—— MultiServerMCPClient 在进入上下文时才会创建连接、完成 initialize 握手、拉取工具列表。如果你漏了这一步后面拿到的可能是空工具集。拿到工具之后我用 LangGraph 的create_react_agent组装 Agentfrom langchain_openai import ChatOpenAI from langgraph.prebuilt import create_react_agent all_tools [] for server_name, server_tools in tools_map.items(): for tool in server_tools: all_tools.append(tool) model ChatOpenAI(modelgpt-4o, temperature0) agent create_react_agent(model, all_tools)这样 Agent 已经具备调用所有 MCP Server 工具的能力。但真正多 Server 场景下直接把工具平铺塞进去会立刻撞见一个经典问题——命名冲突。4.3 工具名冲突、上下文路由与服务健康管理两个不同的 Server 很有可能都提供同名工具。比如订单 Server 和文档库 Server 都有一个search如果不处理LangGraph 的 ToolNode 按工具名称做索引时会混乱模型也可能调错对象。我的做法是加一层归一化all_tools [] for server_name, server_tools in tools_map.items(): for tool in server_tools: tool.name f{server_name}__{tool.name} tool.description f[{server_name}] {tool.description} all_tools.append(tool)给每个工具加上 Server 前缀同时在描述里标注来源。这样模型看到order__query_order和knowledge__search能清楚知道该找哪个能力。这个看似很傻的“字符串处理”其实是多 Server 场景最容易踩的坑很多人把工具接进来后模型乱调用最后排查半天发现是重名。服务健康管理是另一个容易被忽略的点。只要 Server 数量变多任何一个 Server 挂掉都会影响 Agent 行为。我在 LangGraph 外层维护一个 registry定期往每个 Server 发ping请求如果连续几次失败就标记为不可用并在 Agent 决策时把这些工具过滤掉。没有这条兜底机制模型会对着一个死连接反复尝试调用浪费时间和 token。4.4 工具结果在 State 中的流转与上下文瘦身LangGraph 的 State 是所有节点的共享数据流。最简单的做法是定义messages字段所有工具结果以消息形式追加进去然后 Agent 节点根据最新消息继续决策。from typing import Annotated, TypedDict from langgraph.graph.message import add_messages class AgentState(TypedDict): messages: Annotated[list, add_messages] server_health: dict但这里有个实际问题MCP Server 返回的 text 内容有时候非常大。比如database__query查出一条一万行的结果LangGraph 会把它完整放进消息历史下一轮 Agent 的上下文窗口直接告急。我常用的几种瘦身方案在 Server 侧限制返回行数查询类工具默认只返回前 50 行或聚合结果。在工具封装层加内容截断超过阈值就只保留前 N 个字符并附上截断提示。把大块数据改成 Resource 提供工具只返回资源 URI。Agent 需要细节时再主动读取。这里的核心原则是工具结果要“够用就好”上下文里只留决策所需的最小信息。很多 Agent 变慢、变贵不是因为模型不行而是什么数据都往上下文里塞。5. 我在实际项目中踩过的坑与收敛方案5.1 stdio 子进程的崩溃、重连与无感恢复stdio 模式下Server 是客户端拉起的子进程这本身就意味着它很“脆”。我遇到过的最典型场景订单 Server 在跑某个耗时任务时被系统杀掉Agent 瞬间失去所有工具能力。更麻烦的是LangGraph 的 client 会话是持有子进程句柄的进程退出后不会自动重建。我的收敛方案是在 registry 里做显式生命周期管理每次 Agent 开始执行前检查关键 Server 的存活状态失效就重新用MultiServerMCPClient建立连接并刷新工具列表。把创建连接的代码封装成工厂函数避免在多处 new 出重复连接。在 Agent 工具的调用层包一层异常捕获遇到连接错误就返回“工具暂不可用请换一种方式处理”而不是让整个图中断。一个小技巧是给关键 Server 写一个健康检查工具模型自己就能判断是否有能力可用。比如添加一个health__check工具返回当前所有 Server 的连接状态Agent 在规划阶段就会自己避开不可用的依赖。5.2 超时、并发与慢工具从同步调用到任务轮询MCP 协议本身是同步请求-响应模型但业务工具不可能都是毫秒级。数据库慢查询、第三方 API 调用、文件上传动辄几十秒。客户端默认超时时间大概率不够。我的处理思路分两层调超时参数在创建 client session 时显式设置请求超时比如 30 秒或 60 秒避免“慢工具”和“协议假死”混在一起。异步化慢工具如果一个工具注定要跑几分钟就不应该让客户端一直挂起等待。标准做法是 Server 先创建一个任务返回task_idAgent 再通过轮询工具去查结果。我在 Server 内部维护一个异步任务表submit_task返回任务 IDget_task_result查询状态。这样既不会触发超时也不会阻塞 Agent 决策。这个改动是“AI 真的下地干活”和“demo 看起来能跑”的分水岭。只处理同步短任务的 Agent一旦碰到真实业务的长耗时操作就崩做了异步化之后才能应对生产场景。5.3 安全边界高危工具隔离与人工确认节点MCP 给 Agent 带来了很强的执行能力但“能够执行”不等于“应该执行”。我在 LangGraph 里对工具做分级管理低危工具查询订单、读文档、查数据库只读视图直接交给 Agent 自由调用。高危工具删除数据、写文件、执行系统命令、生产环境变更单独收集成一个节点配置独立的执行权限并且在调用前插入人工确认。LangGraph 支持在执行某节点前挂起图流转等待用户确认。我在工具图里加了一个confirm_before_execution节点Agent 决策调用高危工具时图停下来展示给用户确认确认通过才真正进入工具调用节点。这样高危操作永远有一个人工兜底不会因为模型某次判断失误直接引发事故。多 Server 接入时尤其要注意每个 Server 的信任级别不一样。内网数据库 Server 可以相对放开但暴露到公网的 HTTP Server 一定要校验来源和鉴权别把裸工具挂出去让任何人调用。协议本身不解决鉴权问题那是应用层的事。最后分享一个我自己的体会MCP 的价值不在于省掉几百行适配代码而是把“模型能用什么工具”这件事变成一套可声明、可复用、可审计的接口协议。如果你要从零开始给 Agent 接工具我的建议是先走一遍 stdio 模式把协议流程跑通再加上 HTTP、鉴权、多 Server一步步来。等到你把 LangGraph 的图节点、工具归一化和人工确认这些环节都跑顺会发现 Agent 的稳定性和可维护性完全不是一个档次。