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.
When a page takes five seconds to load or an API endpoint times out under load, tell Claude which route is slow and it traces the entire code path — controller, services, queries, loops — identifying N+1 queries, redundant computations, missing indexes, and cacheable operations, then fixes each bottleneck.
Flaky tests are maddening — they pass locally, fail in CI, pass again when you retry. Tell Claude to read the test, identify the source of non-determinism — timing issues, shared state, date dependencies, or order-dependent setup — and fix the root cause so the test is reliably green or reliably red.
When your app throws an error, don't just Google the message — paste the full stack trace into Claude Code. It reads the trace, opens the referenced files in your codebase, follows the call chain, and pinpoints the actual root cause instead of just explaining the symptom.