把 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.ts

Server 启动后不会有任何输出。这是正常的——因为 stdio 是 MCP 的通信通道，Server 在等待 JSON-RPC 消息。

但如果你看到：

  • 终端直接输出了错误日志；
  • Server 启动后秒退；
  • 没有任何监听或等待行为；
  • 输出了 console.log 调试内容；

这些都在告诉你：Server 层还没准备好接受连接。

用 Ctrl+C 退出，修完再试。

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 -e “require(‘./dist/server.js’)”

如果能正确加载，说明路径和编译没问题。如果你改了 Server 代码后工具没有更新，也需要先确认编译。

用 MCP Inspector 做端到端测试

MCP Inspector 是一个独立的测试工具，可以在不启动 Claude Code 的情况下测试 Server 是否正常工作。

npx @modelcontextprotocol/inspector node dist/server.js

Inspector 会：

  • 连接到你的 Server；
  • 列出所有工具和资源；
  • 调用工具并显示结果；
  • 暴露通信层错误。

如果你在 Inspector 里能看到工具列表并能正常调用，那问题就不在 Server 本身，而在 Claude Code 的配置层。

Claude Code 找不到工具的常见原因

如果 Inspector 通过，但 Claude Code 仍然找不到工具，检查这几项。

第一，Claude Code 配置文件的格式是否正确。MCP Server 配置通常在项目根目录或 Claude Code 的设置目录里。格式是 JSON，command、args、cwd 字段名不能写错。

第二，配置文件更新后有没有重启 Claude Code。配置文件修改后，Claude Code 需要重新加载才会拉取最新工具列表。热重载不一定生效。

第三，Server 是否因为错误退出了。Claude Code 启动 Server 后，如果 Server 因为语法错误、端口冲突、环境变量缺失导致退出，工具列表就是空的。查看 Claude Code 的日志可以确认这一点。

协议层错误怎么看

MCP 使用 JSON-RPC 2.0 协议。如果你看到类似的报错，说明协议层不正常：

  • Parse error：stdout 被污染了，检查是否有无关输出；
  • Method not found：Server 没有正确暴露工具或资源列表；
  • Invalid params：Server 收到参数但类型或格式不对；
  • Internal error：工具执行时抛出了异常，没有用正确方式返回。

最有效的排查方式是先去掉所有自定义工具，只暴露一个最简单的只读工具。确认通信正常后，再逐步加回去。

一个标准排查流程

把排查流程固定下来，下次就不需要重复试了：

  1. 终端直接运行 Server，确认不秒退、不报错、不输出文件。
  2. 确认 stdout 没有 console.log，日志全走 stderr。
  3. 用 npx @modelcontextprotocol/inspector 测试工具列表和调用。
  4. 确认 Claude Code 配置文件格式正确，路径是绝对或可靠相对路径。
  5. 重启 Claude Code 让配置生效。
  6. 在 Claude Code 里输入“列出当前可用的 MCP 工具”，确认列表出现。
  7. 逐个测试工具，不要一次加很多个。

这个流程走完，90% 的 MCP Server 接入问题都能解决。

FAQ

MCP Server 启动没有输出是正常吗？

正常。stdout 是协议通道，启动后不应该有任何输出。如果输出了内容，反而不正常。

Inspector 能过但 Claude Code 不能用？

检查 Claude Code 配置文件的格式和路径。配置更新后需要重启 Claude Code。

改了 Server 代码后工具没更新？

确认代码已编译，路径正确，并重启了 Claude Code。

stdout 污染怎么快速发现？

在终端启动 Server 后，输入任意字符，如果 Server 返回了非 JSON 内容，就说明 stdout 有污染。