Debug API and MCP Issues with --debug
When Claude Code behaves unexpectedly, the --debug flag enables verbose logging. Pass an optional category filter to cut through the noise and focus on the specific subsystem that is misbehaving.
# Debug everything
claude --debug
# Debug only API calls and MCP connections
claude --debug "api,mcp"
# Exclude noisy subsystems with the ! prefix
claude --debug "!statsig,!file"
The category filter accepts comma-separated names and supports negation. Useful categories include api (raw API requests and responses), mcp (server connections and tool calls), hooks (hook execution), and file (file read and write operations).
Without a filter, --debug outputs everything including timing data, token counts, and full tool call details. That volume can be overwhelming, which is why targeted filtering is valuable.
Common debug workflows:
--debug "mcp"to see why an MCP server is not connecting or responding--debug "api"to inspect the actual request and response when output looks wrong--debug "hooks"to trace why a hook is not firing as expected
The debug output goes to stderr, so you can capture it separately while still processing the main response:
claude --debug "api" -p "query" 2>debug.log
This makes it straightforward to share a debug log without mixing it into your output stream.
When something is wrong, --debug with a category filter is the fastest path to finding the cause.
Log in to leave a comment.
Hand Claude your heap snapshots or server code and ask it to trace memory leaks — it spots missing event listener cleanup, unbounded caches, and stream lifecycle bugs that are easy to miss in code review.
Ask Claude to audit your UI components for WCAG accessibility issues — it catches semantic problems, missing ARIA attributes, and keyboard navigation gaps that automated tools miss.
Distributed tracing turns mysterious slowdowns into pinpointed bottlenecks. Ask Claude to wire up OpenTelemetry across your application without digging through the docs.