First, Find Out Which Failure You Have
Before changing anything, check the MCP status inside Claude Code. Every server will be in one of three states, and the fix depends entirely on which one you are looking at. Guessing at this step is the single biggest time sink in MCP troubleshooting.
- Failed to start. The process never launched. This is a command, path, or config problem, and it is the easiest of the three to fix.
- Connected, then disconnected. The process launched and then died or broke the protocol. This is usually a missing credential or something the server printed to stdout.
- Connected, but no tools appear. The server is fine. Your problem is scope, permissions, or the fact that the tools are there and you are looking in the wrong place.
Cause One: The Command Is Not on the PATH Claude Code Sees
This is the most common cause by a wide margin, and it produces a failed-to-start state. Your MCP config names a command to run. Claude Code launches that command in its own environment, which is not necessarily the same environment as the terminal where you tested it.
The classic version of this is a tool installed by a version manager. Your shell profile puts it on the PATH when you open a terminal, but the desktop app was launched by the operating system and never read your shell profile. The command works when you test it and fails when Claude Code runs it, which feels like the tool is lying to you.
- Test the exact command from the config, not a shortened version of it. If the config names a runner plus a package, run that whole line.
- If it works in your terminal but fails in Claude Code, replace the command with its full absolute path in the config.
- Find the absolute path by asking your shell where the command lives, then paste that path in verbatim.
An absolute path is less elegant and dramatically more reliable. On a machine that will run this setup unattended, take the reliability.
Cause Two: A Missing Environment Variable
This produces the connected-then-disconnected state. The server starts, tries to authenticate against whatever it wraps, gets nothing, and exits. Because it technically started, the status often reads as a disconnect rather than an error, which sends people looking at the wrong file.
MCP servers do not inherit your shell environment, for the same reason the PATH problem happens. If a server needs an API key, that key has to be declared in the server's own configuration block, not exported in your shell profile.
One detail that catches people: a key that is present but expired produces exactly the same symptom as a key that is missing. If the variable is definitely set and the server still disconnects, test the credential directly against the service before you touch the config again.
Cause Three: The Config File Has a Syntax Error
A single trailing comma or an unclosed brace will stop every server in the file from loading, not just the one you were editing. The symptom is alarming and misleading: servers that worked yesterday all disappear at once after you added one new entry.
- If several servers vanish together right after an edit, assume a syntax error before you assume anything else.
- Validate the file rather than reading it. Human eyes skip over a missing brace reliably, and a parser never does.
- Add one server at a time and restart between each. Batch-adding four servers and then debugging is a false economy.
This is also the easiest failure to prevent. Keep a known-good copy of the config before you edit it, so that reverting is a file copy and not an act of memory.
Cause Four: The Server Is Scoped Somewhere Else
This one produces the most confusing symptom of all: the server works perfectly in one project and does not exist in another. Nothing is broken. The server was registered at a scope that does not cover where you are now.
MCP servers can be registered for just you across all projects, for a single project, or for a project and everyone who works on it. A server added at project scope is invisible from any other directory, which is correct behavior that looks exactly like a bug.
- If the server should be available everywhere, register it at user scope.
- If the server is specific to one codebase, project scope is right and its absence elsewhere is not a fault.
- If a teammate says a server is missing and you can see it, compare scopes before comparing configs. This is almost always the answer.
Cause Five: The Server Is Printing to Stdout
This is the failure that looks the most mysterious and has the cleanest explanation. A local MCP server talks over standard input and output. That channel carries the protocol. If the server also prints a log line, a banner, or a warning to stdout, that text lands in the middle of a protocol message and the connection breaks.
You will see this most often with a server you wrote yourself or one you modified, because a debug print statement is the most natural thing in the world to add and the least obvious thing to suspect.
- Route every log line to standard error instead of standard output. Standard error is safe and is where diagnostics belong anyway.
- Check for framework or dependency banners that print on import. You did not write them and they will still break the connection.
- If the server worked before you added logging, this is the cause. Do not look further.
The Restart Rule
Server definitions are read when Claude Code starts. An edit you make while it is running has not been loaded, no matter how correct it is. A large share of the reports that begin with I fixed it and it still does not work end right here.
Make the change, fully quit, reopen, then check status. Doing those in a different order produces results you cannot trust, and untrustworthy results are worse than no results, because you will act on them.
The Five-Minute Checklist
Run this in order. It resolves the overwhelming majority of MCP failures without you needing to know anything about the protocol itself.
- Check MCP status and write down which of the three states you are in.
- Run the config's command line by hand, exactly as written, and see if it starts.
- Replace the command with an absolute path if it worked by hand and not from Claude Code.
- Confirm every environment variable the server needs is declared in the server's own config block, and that the credential is still valid.
- Validate the config file's syntax, especially if more than one server disappeared at once.
- Confirm the scope covers the directory you are working in.
- Check that nothing is printing to stdout at startup.
- Quit fully, reopen, and check status again.
If you get to the end of that list and the server is still failing, the remaining likely cause is the server itself rather than your setup, and the fastest next step is to add a different known-good server to prove the rest of your configuration works.
Where to Go From Here
If you are still setting up your first MCP servers, our guide to the [best Claude Code MCP servers](/blog/best-claude-code-mcp-servers) covers which ones are worth the setup, and [Claude Code skills vs MCP servers](/blog/claude-code-skills-vs-mcp-servers) explains when you do not need one at all.
Inside Claude Code Club, members post their actual config and error output and get it working the same day, usually because someone else hit the identical problem last month. If you have a server that will not connect, bring the status output and the config to claudecodeclub.ai for $9 a month and we will read it with you.
Short, practical drops on skills, MCP, agents, prompts, and more. No spam, unsubscribe anytime.
Frequently asked questions
Why does my MCP server say failed to start?
The process never launched, which nearly always means the command in your config cannot be found in the environment Claude Code runs it from. Test the exact command line by hand, and if it works there but not in Claude Code, replace it with the command's full absolute path.
Why did all my MCP servers disappear at once?
A syntax error in the config file stops every server in that file from loading, not only the one you edited. If several vanished together right after a change, validate the file's syntax before investigating anything else.
Do I need to restart Claude Code after editing MCP config?
Yes. Server definitions are read at startup, so an edit made while Claude Code is running has not been loaded. Quit fully, reopen, then check status, or you will be testing the old configuration.
Why does an MCP server work in one project but not another?
It was registered at project scope, which makes it invisible outside that directory. That is correct behavior rather than a fault. Re-register it at user scope if you want it available across all your projects.
Why does my custom MCP server disconnect immediately?
Most often because it is printing to standard output. A local MCP server uses stdout for the protocol itself, so any log line, banner, or warning written there corrupts a message and drops the connection. Send all diagnostics to standard error instead.
How do I know if the problem is my config or the server?
Add a different, known-good server and see if it connects. If it does, your config file and environment are fine and the fault is in the original server. If it does not, the problem is in your setup and the checklist above applies.
Last reviewed by David Iya on August 15, 2026
