Claude Code MCP Logs: Find the First Failed Boundary

If you are looking for Claude Code MCP logs , start with the resolved server state, then capture one incident scoped debug file. Do not begin by tailing the Claude Desktop log directory: current MCP documentation labels those filesystem paths specifically for Desktop, while Claude Code documents /mcp , claude mcp list , claude debug mcp , and debug file . The useful outcome is not “find a log.” It is to identify the first failed boundary: configuration, project approval, process startup, tool discovery, tool execution, or the external result the tool was supposed to produce. A log can explain one boundary. It cannot prove all six. This guide uses the current Claude Code documentation and npm release 2.1.220 , checked on July 30, 2026. Pin your installed version in every incident because MCP behavior and diagnostics are still changing. Inspect resolved state before reading raw output Run these checks from the same working directory and user account that exhibited the problem: Inside the affected Claude Code session, run: The official configuration debugging guide says /mcp shows configured servers, connection status, and project approval. The MCP reference adds two operational details that matter: a project scoped .mcp.json server can remain pending until the workspace is trusted and the server is approved; a connected server can still expose zero tools, and /mcp reports that count. Those facts eliminate three classes of blind log search: Resolved evidence First decision Why logs are not first Server absent CONFIG MISSING There is no loaded server process to diagnose yet. Check scope and settings sources. Pending approval APPROVAL WAIT This is a legitimate authority boundary, not a crash. Review and approve it interactively. Failed to connect Capture MCP debug evidence The command, path, environment, authentication, or transport may have failed. Connected, zero tools Reconnect, then capture MCP debug evidence Startup succeeded far enough to connect, but discovery did not produce a usable registry. Connected, tools present Reproduce one bounded call Connection health says nothing about the selected tool or its external effect. Relative paths deserve special suspicion for local stdio servers. Claude Code documents that command and args paths resolve from the directory where Claude Code was launched, not from the location of .mcp.json . A server can therefore work in one repository and fail from another with identical configuration text. Capture a scoped Claude Code MCP debug file The current Claude Code CLI reference documents two relevant flags: debug enables debug mode and accepts category filters such as mcp ; debug file <path writes debug output to an explicit path and implicitly enables debug mode. Create a private incident directory, start a fresh session with only the MCP debug category, and reproduce one bounded symptom: Inside that session, inspect /mcp . If a server is connected with zero tools, use its Reconnect action once. If tools are present, invoke only the smallest read only tool that reproduces the issue. Do not retry a write capable call merely to make the log more interesting. Treat the debug file as sensitive. It may contain absolute paths, server names, environment details, request metadata, or server stderr. Record derived evidence in the incident receipt, then retain or delete the raw file according to your security policy. Do not copy access tokens, prompt bodies, tool arguments, results, or stderr text into a monitoring system just because the file contains them. A public Claude Code feature request for per MCP server log files reports that users want Desktop style persistent files for Claude Code. That issue is useful boundary evidence, not a product guarantee. The supported incident procedure should depend on the documented explicit debug file, not on an assumed default per server path. Match the evidence path to the transport The MCP debugging guide for protocol revision 2026 07 28 draws a crucial transport boundary. For a local stdio server, stdout carries protocol messages. Server diagnostics belong on stderr; writing diagnostic text to stdout can corrupt the protocol stream. Claude Code’s troubleshooting guide specifically recommends claude debug mcp when a connected server exposes zero tools because this makes server stderr available in the debug evidence. For Streamable HTTP , the client cannot capture the remote server process’s stderr. A Claude Code debug file can still show client side connection and request behavior, but the server’s internal failure needs server side logs or OpenTelemetry plus HTTP level inspection. An empty client debug segment is not proof that the remote service did nothing. This distinction prevents a common false conclusion: Record the transport in the receipt. Without it, “no stderr” is ambiguous. Build a content minimized incident receipt The raw log is evidence for investigation. The receipt is the durable health record. It can remain useful without storing content: Keep the classifier precedence explicit: I replayed that rule against eight synthetic cases. It correctly separated missing configuration, approval wait, captured startup failure, connected zero tools, tool error, successful tool response with no outcome, verified outcome, and a failed connection with insufficient debug evidence. All eight expected states passed. The last two cases are the important boundary. A JSON RPC success or non error tool result is activity evidence. If the task promised a created issue, changed record, delivered file, or updated destination, verify that destination separately. Without that receipt, the correct state is OUTCOME UNVERIFIED , not healthy. Choose the smallest safe next action Each state should lead to one bounded response: CONFIG MISSING : inspect settings scope and the exact file Claude Code loaded. Do not alter server code. APPROVAL WAIT : route the approval to the responsible human. Do not describe waiting as a crash. STARTUP FAILED : repair the first concrete startup cause in the scoped debug evidence, then reconnect once. DISCOVERY EMPTY : compare initialization and tool list evidence; test the server independently with MCP Inspector if needed. TOOL CALL FAILED : preserve the request identity, identify whether retry is safe, and avoid replaying an uncertain write. OUTCOME UNVERIFIED : query the destination by stable identifier. Do not rerun the tool until you know whether the effect already happened. UNCERTAIN : collect the missing boundary evidence or escalate. Unknown is an operational state, not an invitation to guess. HEALTHY : require both a usable MCP chain and a fresh, deterministic outcome receipt. Logs make a failure explainable. Resolved status makes it locatable. A destination receipt makes recovery verifiable. Keep those jobs separate, and a Claude Code MCP incident becomes a short evidence exercise instead of a sequence of increasingly risky retries. Sidewisp is designed around this health first distinction between connection, useful progress, tools, and outcomes. Sidewisp is currently in private preview. The production monitoring adapters and recovery executor are not generally shipped.