How to Debug a Failing MCP Server in Claude Code

A red failed status next to an MCP server usually means the launch command crashed, a path is wrong, or auth expired. This guide gives you a repeatable order of checks so you can find the cause quickly instead of guessing.

• An MCP server that is showing failed or disconnected
• Terminal access to the project
• The original command you used to add the server

Step 1: Read the status in the /mcp panel

Inside a session, open the /mcp panel. It shows each server with a status and, for failures, often a short error. Note whether the problem is connection or authentication, because the fix differs.

Step 2: Reproduce the launch outside Claude

The most common failure is the launch command itself. Run the exact command you gave to claude mcp add directly in your shell. If it errors there, the problem is the command or the environment, not Claude Code.

Step 3: Launch Claude with MCP debugging on

Start Claude Code with the debug flag to print the handshake and any stderr from the server. This surfaces missing modules, bad arguments, and protocol errors that the panel summarizes too briefly.

claude --mcp-debug

Step 4: Re-authenticate remote servers

If the failure is on a remote server and the message mentions auth or 401, the token expired. Open /mcp, select the server, and authenticate again. Local servers never need this; only OAuth-backed remote ones do.

Result: a clear path from a red failed badge to the actual cause, whether it is a bad launch command, a PATH gap, or an expired token, so you can fix it on the first try.