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 目前处于私密预览阶段。 通常不发货生产监控适配器和恢复执行器。