1. 为什么你的 MCP Server 一握手就失败从三个核心组件说起如果你正在自建 MCP Server或者用 Claude Desktop、Cursor、Cline 这类客户端去连自己写的服务大概率遇到过这种场景客户端日志里只有一句MCP error -32000: Connection closed或者卡在initialize阶段不动再或者工具列表死活刷不出来。你翻遍代码发现stdio也起了、JSON-RPC 也回了但就是连不上。问题往往不在“代码写错了”而在于没搞清楚 MCP 的三个核心组件到底谁负责什么以及 Server 从启动到关闭这条链路上每一步客户端在等什么、Server 该回什么。MCPModel Context Protocol本质是一套基于 JSON-RPC 2.0 的标准化协议它让 AI 应用Host通过统一的 Client 去调用外部能力Server不用为每个工具单独写一套鉴权和数据转换。而 Server 对外暴露的能力被收敛成三个组件Tools、Resources、Prompts。这三个组件的职责边界直接决定了你initialize之后要声明哪些 capability、tools/list返回什么结构、客户端在什么时机去拉资源。很多人把三者混着用结果就是能力协商异常、客户端拿不到工具、或者调用时报Method not found。这篇会按“原问题 → 前置准备 → 可复制配置 → 验证请求 → 错排查 → 接入”的顺序把 MCP Server 生命周期从初始化到关闭逐段拆开。适合正在调试客户端连接、想搞懂握手失败根因的开发者。读完你能自己写出一份能跑通的 Server 配置并且知道每一步该用什么请求去验证。先给一个整体认知MCP Server 的生命周期大致是启动 → 初始化握手initialize / initialized→ 能力协商 → 运行tools/list、tools/call、resources/read、prompts/get→ 关闭。三个核心组件在这条链路上各有各的“出场时机”Tools 偏“动作”Resources 偏“数据”Prompts 偏“模板”。下面逐段拆。2. 前置准备用 TaoToken 打通模型侧再谈 Server 连接在调 MCP Server 之前得先保证模型侧是通的。因为 MCP 的 Host 通常是一个 AI 应用它要先把用户意图交给模型模型决定调哪个工具Client 才去和 Server 通信。如果模型侧本身连不上你会在 Client 日志里看到一堆和 MCP 无关的报错排查方向直接跑偏。我一般会先把模型接入层准备好这里用的是 TaoToken 的 API 服务。它的接口兼容 OpenAI 风格Base URL 是https://taotoken.net/api模型 ID 按你实际用的填。这样做的目的是让 Host 里的模型调用先稳定再去单独验证 MCP Server 的握手两个变量分开调出问题好定位。具体操作上你可以先在 TaoToken 的控制台创建一个 API Key。入口在https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite登录后新建一个 Key复制出来备用。注意 Key 只在创建时完整显示一次丢了就重建。拿到 Key 之后先别急着配 MCP用最朴素的方式验证模型侧通不通。比如用 curl 打一次对话接口curl https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-你的Key \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: 只回复两个字通了}] }如果返回里有正常的choices[0].message.content说明模型侧没问题。这一步很关键因为后面 MCP 的 Host 会反复调用模型模型侧不稳你会误以为是 Server 握手失败。模型侧通了之后再准备 MCP Server 的运行环境。以 Node.js 为例你需要一个能跑stdio的入口文件以及一份客户端能识别的配置。MCP Server 常见的传输方式是stdio本地进程和SSEHTTP 长连接本地调试优先用stdio因为它不涉及端口和网络排障面更小。这里有个容易踩的坑很多人把 Server 写成普通 HTTP 服务然后指望客户端用stdio去连结果客户端启动子进程后收不到任何 JSON-RPC 输出直接超时。记住stdio模式下Server 必须通过标准输入读请求、标准输出写响应日志要打到标准错误stderr不能混进 stdout否则会污染 JSON-RPC 报文。准备阶段还要确认一件事你的 Server 声明的协议版本。MCP 目前常见的是2024-11-05这类日期版本客户端在initialize时会带上它支持的版本Server 要回一个自己支持的版本。版本对不上握手就会失败。所以前置准备里把协议版本、传输方式、模型侧 Key 这三样先固定下来后面调试会顺很多。3. 可复制配置Server 声明、能力协商与三组件注册片段这一节给可直接复制的配置。先看客户端侧的 MCP 配置以 Claude Desktop 的claude_desktop_config.json为例路径在 macOS 下是~/Library/Application Support/Claude/claude_desktop_config.jsonWindows 下是%APPDATA%\Claude\claude_desktop_config.json。内容长这样{ mcpServers: { my-demo-server: { command: node, args: [/absolute/path/to/mcp-server/index.js], env: { TAOTOKEN_API_KEY: sk-你的Key, TAOTOKEN_BASE_URL: https://taotoken.net/api } } } }注意command和args必须是绝对路径相对路径在客户端启动子进程时经常找不到文件报spawn ENOENT。env里把模型侧的 Key 和 Base URL 传进去Server 内部如果要调模型就能直接用。再看 Server 侧的能力声明。MCP Server 在initialize响应里要告诉客户端自己支持哪些能力。一个同时暴露 Tools、Resources、Prompts 的声明大概是这样{ jsonrpc: 2.0, id: 1, result: { protocolVersion: 2024-11-05, capabilities: { tools: { listChanged: true }, resources: { subscribe: true, listChanged: true }, prompts: { listChanged: true } }, serverInfo: { name: my-demo-server, version: 0.1.0 } } }这里的capabilities就是三个核心组件的“开关”。tools.listChanged表示工具列表会变客户端可以监听通知resources.subscribe表示支持订阅资源变更prompts.listChanged表示提示模板会更新。如果你没声明某个能力客户端就不会去调对应的list方法你也就别指望它显示工具。三个组件的注册结构分别如下。Tools 的tools/list返回{ jsonrpc: 2.0, id: 2, result: { tools: [ { name: get_weather, description: 查询指定城市的实时天气, inputSchema: { type: object, properties: { city: { type: string, description: 城市名 } }, required: [city] } } ] } }Resources 的resources/list返回{ jsonrpc: 2.0, id: 3, result: { resources: [ { uri: file:///logs/app.log, name: 应用日志, mimeType: text/plain } ] } }Prompts 的prompts/list返回{ jsonrpc: 2.0, id: 4, result: { prompts: [ { name: summarize_log, description: 总结日志中的错误, arguments: [ { name: path, description: 日志路径, required: true } ] } ] } }三者的边界可以这样记Tools 是“会改变外部状态或执行动作”的比如发请求、写文件Resources 是“只读数据”比如日志、文档、数据库查询结果Prompts 是“可复用的模板”它本身不执行动作只是给模型一段结构化输入。把这三者混用最常见的就是把“读日志”写成 Tool结果客户端在资源面板里看不到它用户以为功能没生效。如果你用的是 Cline 或 CC Switch 这类工具配置思路一致都是 Base URL Key Model ID 三件套再加上 MCP Server 的启动命令。CC Switch 里切换配置时注意别把 MCP 的command和模型配置混在同一个字段里它们是两层。4. 分阶段验证从 initialize 到 tools/call 的成功结果配置写好后别一次性全测按生命周期分阶段验证每步确认再往下走。第一阶段验证进程能起来。手动在终端跑一遍 ServerTAOTOKEN_API_KEYsk-你的Key node /absolute/path/to/mcp-server/index.js如果进程能常驻、不报错退出说明入口没问题。如果立刻退出看 stderr 里的报错常见的是模块找不到或语法错误。第二阶段验证initialize握手。你可以手写一条 JSON-RPC 请求通过管道喂给 Serverecho {jsonrpc:2.0,id:1,method:initialize,params:{protocolVersion:2024-11-05,capabilities:{},clientInfo:{name:test,version:1.0}}} | node /absolute/path/to/mcp-server/index.js正常应该返回上一节那段带capabilities和serverInfo的响应。如果没返回或者返回了但缺result说明握手逻辑有问题。这一步是排查“握手失败”的核心因为客户端日志往往只显示结果不显示原始报文。第三阶段验证initialized通知。握手成功后客户端会发一条notifications/initialized这是通知不是请求没有idServer 不需要回响应。很多 Server 实现里忘了处理这条通知导致后续请求被阻塞。你可以在 Server 里加一行日志确认收到if (msg.method notifications/initialized) { console.error([mcp] client initialized); }第四阶段验证tools/list。握手完成后发echo {jsonrpc:2.0,id:2,method:tools/list,params:{}} | node /absolute/path/to/mcp-server/index.js应该返回工具数组。如果返回空数组检查你的capabilities.tools是否声明了以及tools/list的处理分支是否真的注册了。第五阶段验证tools/call。这是真正执行动作的一步{ jsonrpc: 2.0, id: 3, method: tools/call, params: { name: get_weather, arguments: { city: 杭州 } } }成功时返回的result里通常有content数组每项是{ type: text, text: ... }。如果这里报Method not found说明工具名对不上如果报参数校验失败检查inputSchema和实际传参是否一致。Resources 和 Prompts 的验证同理分别用resources/read和prompts/get。resources/read的params里传uriprompts/get传name和arguments。分阶段验证的好处是一旦某步失败你能立刻知道是握手、能力协商还是具体调用的问题而不是对着客户端一句笼统的报错干瞪眼。5. 常见错排查401、local proxy failed、reading choices、OAuth这一节对照真实报错来。先说401 Unauthorized。这个报错如果出现在 MCP 调用链里通常不是 MCP 协议本身的问题而是 Server 内部去调模型或外部 API 时 Key 无效。检查env里的TAOTOKEN_API_KEY是否传进了子进程以及 Key 有没有多余空格。用前面那条 curl 单独验证 Key能快速排除。local proxy failed这类报错多出现在客户端尝试通过本地代理连 Server 时。如果你没配代理检查客户端配置里有没有残留的proxy字段如果有删掉。MCP 的stdio模式根本不需要代理任何代理配置都是干扰项。reading choices报错典型是模型侧返回结构不符合预期。比如你期望 OpenAI 风格的choices但实际返回了错误对象代码里直接去读choices[0]就崩了。在 Server 里调模型时先判断响应里有没有error字段再取choices。这个错和 MCP 协议无关但经常被误判成 Server 问题。OAuth相关报错出现在 Server 需要授权访问外部资源时。MCP 本身不强制 OAuth但如果你的 Server 要访问第三方服务得自己实现授权流程。常见错误是invalid_grant或token expired检查刷新逻辑和时钟偏移。如果只是本地调试可以先跳过 OAuth用静态 Token 跑通链路。还有一个高频错客户端显示工具列表为空但tools/list手动测有返回。这通常是capabilities声明和实际返回不一致或者客户端缓存了旧的initialize结果。重启客户端并确认serverInfo.name没变。如果用了 CC Switch 切换配置确认切换后客户端真的重连了 Server而不是复用旧进程。最后提醒一个协议版本坑客户端发initialize时带的protocolVersion如果和 Server 回的差太多客户端可能直接断开。统一用2024-11-05这类稳定版本别自己造版本号。6. 接入与长期使用把 MCP Server 挂到 Coding Plan 上链路调通之后接下来是长期使用。如果你只是偶尔调试手动起 Server 就够但如果你要把 MCP 用在日常编码或 Agent 工作流里建议把模型侧和 Server 侧都固定下来减少每次配置的成本。模型侧可以用 TaoToken 的 Coding Plan入口在https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite。它适合长期编码和 Agent 场景配好之后 Base URL 和 Key 基本不用动MCP Server 里直接读环境变量就行。这样你的 Server 配置里只需要关心command和args模型接入层是稳定的。如果你更想先验证模型对话效果可以用模型对话入口https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite手动发几条消息确认模型行为符合预期再去接 MCP。接入文档在https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite里面有 Base URL、鉴权方式和各语言示例配 Server 时对着抄就行。API Key 管理还是回到https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite建议给 MCP Server 单独建一个 Key方便轮换和排查。如果 Server 要调模型Key 通过env注入别硬编码在代码里。最后给一个实用技巧在 Server 里加一个--debug参数开启后把所有 JSON-RPC 收发都打到 stderr。这样客户端连不上时你直接看 stderr 日志就能知道卡在哪一步比翻客户端日志快得多。MCP 的生命周期不复杂复杂的是每一步的边界和时机把三个组件的职责分清握手失败和能力协商异常基本都能自己定位。