Claude Code MCP 日志：找到第一个失败的边界

如果您正在查找 Claude Code MCP 日志 ，请从解析的服务器状态开始，然后捕获一个事件范围的调试文件。不要从跟踪 Claude Desktop 日志目录开始：当前的 MCP 文档专门针对 Desktop 标记了这些文件系统路径，而 Claude Code 文档则为 /mcp 、 claude mcp list 、 claude --debug mcp 和 --debug-file 。 有用的结果不是“找到日志”。它是为了识别第一个失败的边界：配置、项目批准、流程启动、工具发现、工具执行或工具应该产生的外部结果。一根日志可以解释一个边界。它无法证明所有六个。 本指南使用最新的 Claude Code 文档和 npm 版本 2.1.220 ，于 2026 年 7 月 30 日检查。在每个事件中固定您安装的版本，因为 MCP 行为和诊断仍在变化。 在读取原始输出之前检查已解析状态 从出现问题的同一工作目录和用户帐户运行这些检查： 在受影响的 Claude Code 会话中，运行： 官方配置调试指南 表示 /mcp 显示已配置的服务器、连接状态和项目审批。 MCP 参考 添加了两个重要的操作细节： - 项目范围内的 .mcp.json 服务器可以保持待处理状态，直到工作区受到信任且服务器获得批准； - 连接的服务器仍然可以公开零个工具，并且 /mcp 报告该计数。 这些事实消除了三类盲目日志搜索： 已解决的证据 第一个决定 为什么日志不放在第一位 --- --- --- 服务器缺席 CONFIG MISSING 尚无加载的服务器进程可供诊断。检查范围和设置来源。 待批准 APPROVAL WAIT 这是合法的权限边界，而不是崩溃。以交互方式审核和批准它。 连接失败 捕获 MCP 调试证据 命令、路径、环境、身份验证或传输可能失败。 连接、零工具 重新连接，然后捕获 MCP 调试证据 启动成功，足以连接，但发现未生成可用的注册表。 互联互通，工具齐备 重现一次有界调用 连接运行状况没有说明所选工具或其外部效果。 对于本地 stdio 服务器，相对路径值得特别怀疑。 Claude Code 记录了 command 和 args 路径从 Claude Code 启动的目录解析，而不是从 .mcp.json 的位置解析。因此，服务器可以在一个存储库中工作，并在具有相同配置文本的另一个存储库中失败。 捕获范围内的 Claude Code MCP 调试文件 当前的 克劳德代码 CLI 参考 记录了两个相关标志： - --debug 启用调试模式并接受 mcp 等类别过滤器； - --debug-file <path 将调试输出写入显式路径并隐式启用调试模式。 创建一个私有事件目录，仅使用 MCP 调试类别启动一个新会话，并重现一个有限症状： 在该会话中，检查 /mcp 。如果服务器使用零工具连接，请使用其 重新连接 操作一次。如果存在工具，则仅调用重现问题的最小只读工具。不要仅仅为了使日志更有趣而重试可写调用。 将调试文件视为敏感文件。它可能包含绝对路径、服务器名称、环境详细信息、请求元数据或服务器 stderr。在事件收据中记录派生证据，然后根据您的安全策略保留或删除原始文件。不要仅仅因为文件包含访问令牌、提示正文、工具参数、结果或 stderr 文本而将它们复制到监视系统中。 公开的 针对每个 MCP 服务器日志文件的 Claude Code 功能请求 报告称，用户想要 Claude Code 的桌面样式持久文件。该问题是有用的边界证据，而不是产品保证。支持的事件过程应取决于记录的显式调试文件，而不是假定的默认每服务器路径。 将证据路径与传输相匹配 MCP协议修订调试指南 2026-07-28 绘制了关键的传输边界。 对于本地 stdio 服务器，stdout 携带协议消息。服务器诊断属于 stderr；将诊断文本写入标准输出可能会损坏协议流。当连接的服务器公开零工具时，Claude Code 的故障排除指南特别建议使用 claude --debug mcp ，因为这使得服务器 stderr 在调试证据中可用。 对于 Streamable HTTP ，客户端无法捕获远程服务器进程的 stderr。 Claude Code 调试文件仍然可以显示客户端连接和请求行为，但服务器内部故障需要服务器端日志或 OpenTelemetry 加上 HTTP 级别的检查。空的客户端调试段并不能证明远程服务没有执行任何操作。 这种区别可以防止一个常见的错误结论： 在收据中记录运输情况。没有它，“无 stderr”就会含糊不清。 构建内容最小化的事件收据 原始日志是调查的证据。收据是持久的健康记录。它可以在不存储内容的情况下保持有用： 保持分类器优先级明确： 我针对八个综合案例重述了这条规则。它正确区分了丢失的配置、批准等待、捕获的启动失败、零连接工具、工具错误、成功的工具响应但没有结果、已验证的结果以及调试证据不足的失败连接。所有八个预期状态都通过了。 最后两种情况是重要的边界。 JSON-RPC 成功或无错误工具结果是活动证据。如果任务承诺创建问题、更改记录、交付文件或更新目标，请单独验证该目标。如果没有该收据，正确的状态是 OUTCOME UNVERIFIED ，不健康。 选择最小的安全下一步动作 每个状态都应该导致一个有界响应： - CONFIG MISSING ：检查设置范围和加载的克劳德代码的确切文件。不要更改服务器代码。 - APPROVAL WAIT ：将批准传递给负责人。不要将等待描述为崩溃。 - STARTUP FAILED ：修复范围调试证据中的第一个具体启动原因，然后重新连接一次。 - DISCOVERY EMPTY ：比较初始化和工具列表证据；如果需要，使用 MCP Inspector 独立测试服务器。 - TOOL CALL FAILED ：保留请求身份，识别重试是否安全，避免重放不确定的写入。 - OUTCOME UNVERIFIED ：通过稳定标识符查询目的地。在您知道效果是否已经发生之前，请勿重新运行该工具。 - UNCERTAIN ：收集缺失的边界证据或升级。未知是一种运行状态，而不是邀请猜测。 - HEALTHY ：需要可用的 MCP 链和新鲜的、确定性的结果收据。 日志使失败变得可以解释。已解决的状态使其可定位。目的地收据可以验证恢复情况。将这些工作分开，克劳德代码 MCP 事件就变成了一个简短的证据练习，而不是一系列风险越来越大的重试。 Sidewisp 的设计围绕着连接、有用进展、工具和结果之间健康第一的区别。 Sidewisp 目前处于私密预览阶段。 通常不发货生产监控适配器和恢复执行器。