MCP Troubleshooter
Walk a decision tree to fix an MCP that won't connect.
- $29 Free
- 60 sec
- No signup
Describe the symptom you're seeing
Answer the follow-up questions
Apply the targeted fix it gives you
You get: The likely cause of your MCP failure plus the exact fix.
What's happening?
Pick the symptom that matches what you're seeing to get ranked diagnostic steps.
Why MCP servers fail, and how to think about it
Almost every MCP failure is one of a small number of things: the command does not run, the path is wrong, the credential is missing or under-scoped, the transport shape is mismatched, or the server crashes on its first real request. Once you know the buckets, debugging stops being guesswork. Pick the symptom above and this troubleshooter walks you through the ranked steps for that exact failure mode, ordered so the most common fix comes first.
The single most useful habit is to separate the server from Claude Code. If the server's launch command does not run cleanly in your own terminal, no amount of config fiddling will help. Prove the server works standalone, then prove Claude Code can reach it.
The universal first move: run it standalone
Copy the exact command and args from your config and paste them into your terminal. This one step resolves a large share of failures because it tells you instantly whether the problem is the server (fails on its own) or the wiring (works alone, fails in Claude Code). A server that errors standalone has a missing runtime, a bad path, or a missing dependency - none of which are Claude Code's fault.
stdio vs remote is the config trap
A stdio server uses command + args and no url. A remote server (sse or http) needs a url and a type field. The most common silent failure is declaring one as the other - the config looks fine but never connects.
Reading the signals
- 'command not found' - the runner (node, npx, uv, uvx) is not installed or not on your PATH.
- Connects but no tools - the server started but registered nothing; it usually needs a target resource configured.
- 401 / 403 / permission denied - a credential problem: missing, expired, or too narrow a scope.
- Hangs then times out - slow startup, a network dependency, or a blocking prompt the model cannot answer.
- Starts then dies - a runtime crash; the MCP logs will name the exception.
Where to find the logs
Run 'claude mcp list' to see the status of each configured server at a glance. Claude Code also surfaces MCP startup and error output, and the server's own error message is usually the fastest path to the fix - it names the missing file, the bad flag, or the failed dependency directly. Do not debug blind when the log is telling you the answer.
Credential problems, specifically
- Confirm the credential is present and non-empty in the env block (stdio) or auth header (remote).
- Prove the token works outside Claude Code with a direct API call.
- Check the scopes match the actions - a read token cannot write.
- For OAuth servers, remove and re-add to trigger a fresh authorization if the grant lapsed.
- Watch for shell quoting that truncates the secret before it reaches the server.
When to stop debugging and rebuild
If you have run the command standalone, confirmed the runtime, checked the paths and the credential, and it still will not connect, the fastest fix is often to regenerate the config from scratch rather than keep patching it - a stray character or a subtle shape error is easy to miss by eye. Use the MCP config generator on this site to produce a guaranteed-valid config for your transport, then re-add the server clean.
Frequently asked questions
My server was working yesterday and now it isn't. What changed?
Most likely a credential expired, a package updated, or a path moved. Run the command standalone first, then check the token validity - those two cover the majority of 'it broke overnight' cases.
Claude Code says the server is connected but I can't use any tools.
The connection succeeded but the server registered no tools, usually because it needs a target configured (a repo path, database URL, or scope). Ask Claude Code to list its tools, then check the server's required configuration.
How do I see the actual error message?
Run 'claude mcp list' for status, and check Claude Code's MCP logs for the server's own output. The stack trace or error line almost always names the real cause - a missing file, bad flag, or failed dependency.
Why does my remote MCP server time out?
Remote servers can hang if the endpoint is unreachable, if they wait on a login prompt, or if startup is slow. Confirm you can reach the URL directly and that no interactive prompt is blocking the launch.
The server crashes as soon as I call a tool.
That points to a runtime error triggered by the request. Read the crash output in the logs, update the server package, confirm your Node or Python version meets its minimum, and retry the tool with minimal known-good arguments.
Is any of this sent to a server?
No. This troubleshooter is a static decision tree running entirely in your browser. Nothing you select is uploaded - the copy button just puts the plan on your clipboard.
Liked this tool? The club is the next step.
Join Claude Code Club for $9/month. 650+ lessons, weekly updates, and the workflows behind every tool on this site.
- No experience needed
- Cancel anytime
- Updated weekly