切换明暗模式
MCP 连接失败
「连接失败」可能发生在服务进程启动之前，也可能是握手、工具发现或调用时失败。先保存原始错误和发生阶段，再选检查。给启动路径错误增加网络重试，不会让不存在的文件出现。
无外部账号的最小练习
下载 本地 MCP 练习 v1.0.0，解压进入 mcp/，阅读 README，使用 Node 22+ 运行：
sh
node probe.mjs包内 server.mjs 是本方编写的 stdio 教学服务，只提供只读 greet 工具；probe.mjs 是本方协议探针。没有 npm 依赖、API Key 或外部网络服务。本站在 macOS、Node v22.23.3 实际执行，完整消息见 原始记录。
探针首先指向不存在的 missing-server.mjs。Node 退出 1 并报 MODULE_NOT_FOUND；客户端虽然已写出 initialize 请求，却没有收到响应。因此故障位于服务启动阶段，不能把它写成「握手成功后工具失效」。
随后探针只改变入口路径，使用存在的 server.mjs。服务返回初始化结果，探针发送 notifications/initialized，然后列出并调用工具：
| 阶段 | 修复后实际观察 |
|---|---|
| initialize | 返回协议 2025-11-25 与服务名称 |
| tools/list | 得到 greet 及 name 参数结构 |
| tools/call | 传入 name 为 reader，返回 Hello, reader |
脚本同时断言预期失败与成功，最后自身退出 0。成功依据是收到并核对响应，不能只凭进程存在或发出了请求。练习为每个请求设置三秒超时，以便故障时停止等待；这只是探针的界限，不是所有生产 MCP 服务应使用的统一超时值。保留最后一条成功响应比单独记录「超时」更有助于定位阶段。
沿失败阶段排查
| 最后成功的阶段 | 区分性检查 | 对应处理与复测 |
|---|---|---|
| 尚未启动 | 检查命令可解析、脚本路径存在、stderr 错误 | 修正准确路径，重新启动原命令 |
| 进程启动 | 检查 initialize 响应与协议版本 | 按客户端和服务支持范围核对握手 |
| 握手完成 | 检查 tools/list 的实际结果与过滤配置 | 核对工具声明，再刷新客户端发现结果 |
| 已列出工具 | 检查 tools/call 参数与完整错误 | 按输入结构修正，使用相同输入复测 |
后三行是诊断方向，本站没有为每种故障制造一次实测。stdio 的 stdout 必须用于协议消息，调试日志应写 stderr，避免普通打印破坏消息解析；依据见 MCP 传输规范。初始化顺序见 生命周期规范，均于 2026-10-18 复核。
接入自己的客户端之前
OpenAI MCP 文档 给出 CLI 注册方法。完成离线探针后，若你决定修改自己的 MCP 配置，可将下面路径替换为实际绝对路径：
sh
codex mcp add codexcase-lab -- node /绝对路径/server.mjs
codex mcp get codexcase-lab这一步会改客户端配置；本站探针不需要执行它。读取配置只能确认登记内容，接入后还应在实际客户端发现和调用 greet。本站没有把离线探针成功写成所有 Codex 客户端已连接。
本练习是 MCP 的最小教学子集，不覆盖 HTTP、OAuth、代理、远端权限或生产服务可靠性。先按 PATH 页 排除命令启动问题，再用 问题报告模板 记录最后成功阶段与最小消息，避免泄露完整配置。