MCP Server 报 Connection closed:只读定位配置路径、命令与传输错误

透明说明:本文由 AI 辅助整理,命令、事实与发布内容仍需作者复核。

MCP 客户端出现 Connection closed、启动失败或超时,并不等于 Server 本身已经崩溃。本文给出的判断结果是:先确认客户端读取的配置能否解析,再定位到配置入口、传输方式、command、args、cwd、URL 或变量占位符。准备好资源和待检查的 JSON 后,第一条命令是:

node mcp-config-doctor.mjs --config ./mcp.json

该命令只读取配置,不启动其中的第三方 Server,也不访问远程地址。目标是在前三分钟得到首个可验证结果:配置文件是否存在、JSON 是否有效,以及 Server 定义是否存在明确的配置层错误。

问题现象为什么不能直接归因于 Server

Connection closed 只说明连接已经关闭,没有单独证明关闭发生在哪一层。客户端可能读错配置路径,也可能根本没有识别到 mcpServers 或 servers;stdio 配置还可能存在命令找不到、参数类型错误或工作目录不存在。远程配置则可能使用了错误协议,或者把凭据直接写进 URL。

证据包中的问题报告分别记录过 Connection closed、文档与代码中的配置路径不一致、每个 Server 的超时设置未按预期生效,以及远程连接缺少授权 URL 等情况。这些报告只能证明相关故障有人遇到,不能据此判断当前故障必然同源。因此排查顺序应从可离线确认的配置事实开始。

运行前只需要确认两件事

资源要求 Node.js 20 或更高版本,不依赖第三方包。将 --config 后面的 ./mcp.json 替换为实际配置文件的相对路径。如果不确定客户端使用哪个文件,应先从客户端设置或对应官方文档确认;资源只能分析传入的文件,不能自动判断客户端最终读取了哪一份配置。

配置文件必须是普通文件,大小不能超过 1 MiB。资源支持两种常见入口:

{
  "mcpServers": {
    "filesystem": {
      "command": "node",
      "args": ["server.mjs"]
    }
  }
}

也可以使用顶层 servers。这里的示例只说明 JSON 形态,不能证明示例中的 server.mjs 存在或能够正常提供 MCP 能力。

怎样读取第一份诊断结果

输出是结构化 JSON。先看文件级 classification,不要一开始逐项猜参数:

  • config_not_found:传入路径不存在。此时优先重新核对配置路径。
  • config_not_readable:目标不是普通文件,或者文件超过 1 MiB。
  • config_parse_error:文件未能作为 JSON 解析。
  • server_map_missing:顶层没有有效的 mcpServers 或 servers 对象。
  • configuration_error:至少一个 Server 存在错误级问题。
  • configuration_warning:没有错误,但仍有需要人工确认的警告。
  • configuration_ok:本次静态检查没有发现已定义规则覆盖的错误。

configuration_ok 只代表配置通过这组只读规则,不代表 Server 可以启动,更不代表工具调用成功。退出码也不能替代结果内容:存在错误时程序返回 1,用法错误返回 2;只有警告时 ok 仍可能为 true,因此还要查看每个 Server 的 issues。

配置包含多个 Server 时,可以缩小范围:

node mcp-config-doctor.mjs --config ./mcp.json --server filesystem

名称不匹配会得到 server_not_found。这通常意味着筛选名称写错,或者正在检查的并不是客户端实际使用的配置。

不同问题码应该怎么改

处理顺序应保持固定,避免修完参数后才发现整个配置入口都未被识别。

先解决 transport_missing 和 transport_conflict。前者表示没有可用的非空 command 或 url;后者表示同一个 Server 同时配置了两种传输入口。应依据 Server 的接入说明保留一种,不要靠反复重启客户端碰运气。

stdio 配置重点查看以下结果:

  • command_empty:把 command 改为非空字符串。
  • command_not_found:当前进程的 PATH 中找不到命令;如果填写的是带路径的命令,该文件还必须可执行。
  • args_not_array:args 必须是数组,不能写成单个字符串。
  • args_not_strings:数组中的每一项都必须是字符串。
  • env_not_object:env 必须是键值对象。
  • cwd_not_found:填写的工作目录不存在。

HTTP 或 SSE 配置出现 invalid_url 时,检查 url 是否为合法的 http 或 https 地址,并移除 URL 中内嵌的用户名或凭据。资源不会访问这个地址,所以修正格式后仍需由客户端完成真实连接验证。

unresolved_placeholder 是警告,表示定义中仍含有 ${...}。它不等于配置必然错误,因为占位符是否由客户端展开取决于对应客户端。此处应查阅客户端文档,不能直接把占位符替换成真实密钥后再公开诊断文件。

如何复现资源的离线测试

证据包中的本地验证实际运行了:

node test/run-tests.mjs

实际结果为:

mcp-config-doctor tests passed

测试会创建临时 JSON 文件,结束后删除,不执行配置中的命令,也不连接网络。它实际覆盖了有效 mcpServers 配置、找不到命令、args 不是数组、URL 内嵌凭据、未展开占位符、JSON 解析失败、文件不存在、缺少 Server 入口以及指定 Server 不存在等分支。

测试还断言输出中没有出现测试环境变量值、参数值 server.mjs 和 URL 中的凭据。这说明这些离线样例满足脱敏断言,但不能把该结果描述为生产环境验证,也不能推导出所有客户端扩展字段都受支持。

配置通过后仍然失败怎么办

如果结果是 configuration_ok,而客户端仍然出现 Connection closed 或超时,说明故障已超出这项只读检查能够确认的范围。下一步应结合对应客户端和 Server 的日志,检查进程启动后的依赖、参数语义、协议握手及远程服务状态。

资源不会验证 OAuth、TLS、HTTP 状态、授权跳转、远程可用性或实际工具调用,也不会判断客户端是否忽略某个超时字段。命令能在 PATH 中找到,也不等于其依赖完整、参数正确。不同客户端支持的扩展字段存在差异,未知字段不会被自动判错。

哪些场景适合使用

它适合在 Claude Code、Cline、VS Code 或其他 MCP 客户端没有显示 Server、连接立即关闭、启动前报错时,先保存一份不含配置值的结构化诊断结果。也适合在运行来源尚未确认的 Server 之前,低风险排除本地配置问题。

它不适合证明远程 Server 在线,也不适合评估认证流程、网络质量和业务功能。若配置已经通过,而错误发生在启动或通信阶段,应转入运行层诊断,不应继续修改已经没有静态错误的 JSON。

资源

  • 资源名称:MCP Server JSON 配置与连接前置条件只读诊断工具
  • 下载地址:https://download.csdn.net/download/zyx022/93236676
  • 说明:这是本文配套资源,包含只读诊断脚本、使用说明、许可证和离线测试;运行前请复核文件内容,并保留原始配置备份。
Logo

欢迎加入 MCP 技术社区!与志同道合者携手前行,一同解锁 MCP 技术的无限可能!

更多推荐