MCP Server 接入 Claude Code 老是失败？从 stdio、路径和 JSON-RPC 开始排查

把 MCP Server 接到 Claude Code 的过程里最容易让人困惑的不是 Server 写错了而是 Server 能跑但工具不出现、Claude Code 说找不到 Server、或者工具列表显示为空。这类问题通常不是模型或客户端的问题而是通信层、路径配置、stdout 污染或 JSON-RPC 协议没跑对。本文假设你已经写过 MCP Server 基础代码。如果你还没写过可以先看 MCP Server 开发实战。这里只讲接入时最常见的失败场景排查。先确认 Server 能不能独立跑起来很多接入失败其实在这一步就能发现。在 Claude Code 配置 MCP Server 之前先手动启动 Server 一次。如果你用 stdio 通信直接终端运行node dist/server.js或者npx tsx src/server.tsServer 启动后不会有任何输出。这是正常的——因为 stdio 是 MCP 的通信通道Server 在等待 JSON-RPC 消息。但如果你看到终端直接输出了错误日志Server 启动后秒退没有任何监听或等待行为输出了console.log调试内容这些都在告诉你Server 层还没准备好接受连接。用 CtrlC 退出修完再试。stdout 污染是最隐蔽的问题MCP 的 stdio 通信模式下stdout 是协议通道。所有普通日志都必须走 stderr。很多 Server 写成这样console.log(“Server started”); // 错误console.log(“Received request”); // 错误这些日志会污染 JSON-RPC 消息Claude Code 收到无法解析的内容就会认为 Server 不可用。正确的写法是console.error(Server started);console.error(Received request);你甚至可以把重点日志写入文件避免任何 stdout 干扰。检查路径和启动命令Claude Code 配置 MCP Server 时通常要指定命令和参数。常见的路径问题有命令使用了全局安装路径但 Claude Code 的运行环境没有找到npx或pnpm指向了错误版本工作目录cwd和 Server 的配置文件路径不一致使用了相对路径但 Claude Code 的启动目录不是项目根目录。一个稳定的配置方式是在项目根目录先确认node-erequire(./dist/server.js)如果能正确加载说明路径和编译没问题。如果你改了 Server 代码后工具没有更新也需要先确认编译。用 MCP Inspector 做端到端测试MCP Inspector 是一个独立的测试工具可以在不启动 Claude Code 的情况下测试 Server 是否正常工作。npx modelcontextprotocol/inspectornodedist/server.jsInspector 会连接到你的 Server列出所有工具和资源调用工具并显示结果暴露通信层错误。如果你在 Inspector 里能看到工具列表并能正常调用那问题就不在 Server 本身而在 Claude Code 的配置层。Claude Code 找不到工具的常见原因如果 Inspector 通过但 Claude Code 仍然找不到工具检查这几项。第一Claude Code 配置文件的格式是否正确。MCP Server 配置通常在项目根目录或 Claude Code 的设置目录里。格式是 JSONcommand、args、cwd字段名不能写错。第二配置文件更新后有没有重启 Claude Code。配置文件修改后Claude Code 需要重新加载才会拉取最新工具列表。热重载不一定生效。第三Server 是否因为错误退出了。Claude Code 启动 Server 后如果 Server 因为语法错误、端口冲突、环境变量缺失导致退出工具列表就是空的。查看 Claude Code 的日志可以确认这一点。协议层错误怎么看MCP 使用 JSON-RPC 2.0 协议。如果你看到类似的报错说明协议层不正常Parse errorstdout 被污染了检查是否有无关输出Method not foundServer 没有正确暴露工具或资源列表Invalid paramsServer 收到参数但类型或格式不对Internal error工具执行时抛出了异常没有用正确方式返回。最有效的排查方式是先去掉所有自定义工具只暴露一个最简单的只读工具。确认通信正常后再逐步加回去。一个标准排查流程把排查流程固定下来下次就不需要重复试了终端直接运行 Server确认不秒退、不报错、不输出文件。确认 stdout 没有console.log日志全走 stderr。用npx modelcontextprotocol/inspector测试工具列表和调用。确认 Claude Code 配置文件格式正确路径是绝对或可靠相对路径。重启 Claude Code 让配置生效。在 Claude Code 里输入“列出当前可用的 MCP 工具”确认列表出现。逐个测试工具不要一次加很多个。这个流程走完90% 的 MCP Server 接入问题都能解决。FAQMCP Server 启动没有输出是正常吗正常。stdout 是协议通道启动后不应该有任何输出。如果输出了内容反而不正常。Inspector 能过但 Claude Code 不能用检查 Claude Code 配置文件的格式和路径。配置更新后需要重启 Claude Code。改了 Server 代码后工具没更新确认代码已编译路径正确并重启了 Claude Code。stdout 污染怎么快速发现在终端启动 Server 后输入任意字符如果 Server 返回了非 JSON 内容就说明 stdout 有污染。