How to Debug an MCP Server That Will Not Connect

You added an MCP server, but the status reads failed instead of connected and its tools never appear. The cause is almost always one of a short list: a wrong command, a missing dependency, or a credential the server cannot read. This guide walks the checklist in order.

What you need

• An MCP server already added to your client
• The exact command or URL you used to add it
• About 10 minutes

Step 1: Read the real status

List your servers to see which one failed and capture the error line. The status, not a guess, tells you where to look.

Step 2: Run the server command by hand

Copy the exact command from your config and run it directly in a terminal. If it errors here, the client was never going to start it either. This isolates the problem from the agent.

# the same command your config runs
npx -y @modelcontextprotocol/server-postgres
# a missing binary or import error shows up immediately here

Step 3: Check the credential the server reads

Many servers expect a token or connection string in an environment variable. If it is unset or named wrong, the server starts and then exits. Confirm the variable the server actually reads.

Step 4: Re-add with the fix and re-list

Remove the broken entry, add it again with the corrected command and env, then list once more to confirm it reads connected.

claude mcp remove postgres
claude mcp add postgres \
  --env DATABASE_URL=postgres://localhost:5432/app \
  -- npx -y @modelcontextprotocol/server-postgres

Result: the server reports connected and its tools show up again. The same three checks, command, dependency, credential, cover nearly every failure.