MCP troubleshooting
Every directory lists servers. None of them help when the config breaks — which, if you've used MCP for more than a week, you know is most of the pain. These are answer-first fixes for the errors that actually happen, written from real debugging, not copy-paste filler. The rule of thumb running through all of them: don't suspect the server first — it's almost always the config, the path, or a restart.
MCP server not showing up in Claude Desktop? Here's the real fix
Don't suspect the server first. 90% of the time it's one of three things: you edited the wrong file, the JSON has a syntax error (a trailing comma kills the whole file silently), or you closed the window instead of fully quitting and reopening Claude. Fix those in order before anything else.
Read the fixMCP server not connecting? Read the logs first — here's how
A connection failure is almost never mysterious — the client log names the cause. Find the MCP log, read the last 20 lines, and you'll see one of four things: the command wasn't found, a dependency is missing, the transport is wrong (stdio vs remote), or the server crashed on startup because of a missing env var.
Read the fixMCP error -32000 'Connection closed': what it means and how to fix it
-32000 'Connection closed' means the server process started and then died before it finished the MCP handshake — so it's a crash, not a network problem. The cause is almost always a missing dependency, a bad command/path, or an env var the server needs and didn't get. The startup log line tells you which.
Read the fixCursor says 'no tools or prompts' for your MCP server — fix it
'No tools or prompts' means Cursor connected to the server but the server advertised zero tools. That's different from a connection failure. The usual reasons: the server needs an API key it didn't get, it needs a specific sub-command/flag to run in server mode, or Cursor cached an old failed state and just needs a reload (or toggle off/on).
Read the fixMCP config not working? The JSON mistakes that break it silently
MCP clients don't show JSON errors — a malformed config just silently does nothing. The four killers: a trailing comma after the last entry, smart-quotes from a doc/website, wrong nesting (servers not inside one "mcpServers" object), and unescaped backslashes in Windows paths. Validate the file and these disappear.
Read the fixMCP error -32601 'Method not found': what's actually wrong
-32601 'Method not found' is a protocol mismatch, not your config: the client asked for an MCP method the server doesn't implement. It usually means the server is built on an older (or newer) MCP SDK than the client expects. Update the server package to its latest version — that resolves the large majority of cases.
Read the fixMost config breakage is catchable before it happens. Paste your setup into the Config Doctor to spot syntax errors and tool-budget overruns, or browse servers with copy-paste configs that are correct on the first try.