Debugging MCP when nothing works, the 10 checks that solve 90 percent of cases

You have an MCP server in the config. You start Claude Code. Type /mcp. It says "no servers" or the server is there but the tools are missing. Or even better: the server is listed as "connected" but on every tool call you get "tool not found". That is the hour in which most people give up or start rewriting paths at random.

I am giving you here the order that I go through myself. Ten checks, each takes one to two minutes, in the order so that on average after three steps you know what the cause is.

Step 1, read claude --debug all the way through once

Quit Claude Code, restart with claude --debug. In the console verbose logging is now running. Watch for three line types: "MCP server connecting", "tool discovery", "MCP error". The last two lines before the first error almost always tell you what is broken.

The official doc on debug logging is in the MCP Integration skill: "running claude --debug ... will reveal details about MCP server connection attempts, the process of tool discovery, authentication flows, and any errors". This is the one step you really must not skip.

Step 2, call /mcp in the chat

In the running session: type /mcp. You get a list of your servers with status. "connected" means the connection is up. "failed" means the connection never came about. "no tools" means connected but no tools discovered. Each of these three states has a different diagnosis.

Write down the status before you change anything. If you blindly rewrite the config once, you no longer know whether the previous state was "failed" or "no tools".

Step 3, the command must exist and be executable

With stdio servers (so npx, node, python) Claude Code does a spawn in the background on the command you specified in the config. If the command is not in the PATH, or the node_modules are not installed, or the script does not have execute bits, nothing comes back.

Test: copy the exact command from your mcp config into your terminal and run it manually. If the server does not start in your terminal, it does not start in Claude Code either. Check path, check permissions (chmod +x), check whether node_modules are installed.

Step 4, stdout must be clean

stdio MCP servers communicate over stdin/stdout in the JSON-RPC format. If your server writes a console.log or print('starting...') to stdout on startup, that is mixed into the JSON stream and Claude Code cannot parse anything.

Quote from the MCP integration docs on stdio troubleshooting: "ensure that your server correctly uses stdin/stdout for MCP messages and check for any unintended print or console.log statements that might interfere with the JSON-RPC stream".

Fix: redirect all logging statements in your MCP code to stderr. console.error instead of console.log in Node, sys.stderr in Python. Plus a "no banner on startup" setting in case your framework prints one.

Step 5, the path in the config is absolute

Relative paths in mcp configs are one of the most common error sources. "./meine-skripte/server.js" does not work because Claude Code starts from a different working directory than you think. Write the path out in full, /home/user/projekt/meine-skripte/server.js.

Same game with ENV variables: $HOME is not expanded in the config if you write it in as a string. Either the full path or use the env section in the config if your MCP framework supports it.

Step 6, restart after every config change

Changes to the mcp config are NOT reloaded live. From the troubleshooting docs: "If issues persist after making configuration changes, restart Claude Code to apply the updates". Quit completely, restart. A reload is not enough.

Sounds trivial. But it is the reason why people believe for an hour "the path must still be wrong" even though the path has been correct for ten minutes and they just did not notice because no new session was running.

Step 7, HTTP MCP, the port is open and auth is right

With HTTP MCP servers (remote, Cloud Run, your own endpoint) the typical failure modes are: port not reachable, wrong URL, missing auth header, expired token. curl on the health endpoint is your first test, then look at the server logs.

Important: 401 or 403 are NOT "broken". Those are auth-required endpoints, your token was wrong or missing. "connection refused" or "timeout" are the real connection problems.

Step 8, the tool name matches exactly

From the tool usage docs: "Verify that tool names match exactly, as they are case-sensitive". If your server exports nex_entity_create and you have mcp__nex__nexEntityCreate in the allow list, that does not match. Tool not available.

Checklist: upper/lowercase, underscores vs camelcase, server prefix. With plugins and bundles also the namespace prefix. If unclear: call /mcp once and copy the tool names exactly as they are listed.

Step 9, the permissions in settings.json block the tool

You might have a permissions.deny or permissions.allow list that implicitly blocks the tool. "mcp__*" as deny blocks all MCP tools. An allow list that is too narrow lets only a few through.

Test: check in .claude/settings.json (project) and ~/.claude/settings.json (global) whether there is a permissions section that excludes your tool. Plan Mode also tells you in the course "tool not allowed" if that is the case.

Step 10, the permission mode misunderstanding

If you are in Plan Mode, no tool runs, even if everything is configured correctly. You type a task, Claude answers with a plan, you see no tool call and think "the server is broken". In truth everything works, you are just in the wrong permission.

Cycle through with Shift+Tab until "default" or "acceptEdits" is shown. Then try again. Whoever spends a whole day desperately searching for an MCP bug and at the end it was Plan Mode, never forgets it again. Ask me how I know.

What is next

Once your server runs again, read the recipe phase-7-mcp-patterns/7.5-error-handling for a sensible error pattern in your MCP code. For your own servers the playbook erster-mcp-server-in-90-minuten plus mcp-server-publishen is worth it if you want to distribute. And if you often juggle between multiple servers: tool-sprawl-vermeiden helps keep the load low.

Source

• Debug logging and MCP Integration: https://code.claude.com/docs/en/mcp and https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/skills/mcp-integration/SKILL.md
• stdio troubleshooting: https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/skills/mcp-integration/references/server-types.md
• Tool usage and restart note: https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/skills/mcp-integration/references/tool-usage.md
• Plan Mode and permission modes: https://code.claude.com/docs/en/interactive-mode