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 fixProtocol and runtime error guides
Diagnose the exact JSON-RPC, process, transport, and certificate failures that generic connection advice cannot resolve.
MCP Error -32603: How to Find the Real Internal Error
Error -32603 is a wrapper, not a diagnosis; the useful evidence is in the server stderr, transport response, or exception that the client hid.
Diagnose this errorMCP Error -32602: Fix Invalid Params Without Guessing
Error -32602 means a known method rejected the request shape; inspect the exact schema and error data instead of randomly renaming fields.
Diagnose this errorMCP Error -32001: Fix Request Timed Out at the Right Layer
A request timeout says the client stopped waiting; prove whether the server was slow, silent, blocked, or already dead before extending the deadline.
Diagnose this errorMCP spawn npx ENOENT: Fix PATH on macOS, Windows, and Linux
spawn npx ENOENT means the MCP client cannot locate the executable it was told to launch; the server package has not started yet.
Diagnose this errorMCP initialize EOF: Find Why the Server Exits Before Handshake
initialize EOF means the client reached the server process or stream, but it closed before returning a valid initialize response.
Diagnose this errorMCP Unsupported Protocol Version: Align Client and Server Safely
An unsupported protocol version means the client and server do not share—or did not correctly negotiate—the revision carried in the request.
Diagnose this errorMCP No Server Info Found: Fix the Initialize Response in Cursor
No server info found means the client never retained a valid initialize result containing server identity and capabilities, even if the process appears to run.
Diagnose this errorUnknown MCP Tool: Refresh Discovery Before You Change Code
Unknown MCP tool means tools/call reached a server that does not currently advertise the exact requested tool name.
Diagnose this errorMCP Inspector Self-Signed Certificate Error: Trust the CA, Not the Risk
A self-signed certificate error means the Node process behind MCP Inspector cannot build a trusted TLS chain for the server certificate.
Diagnose this errorMCP Error POSTing to Endpoint: Diagnose 401, 404, 400, and 500
Error POSTing to endpoint is a transport wrapper; the HTTP status and response body decide whether to fix auth, URL paths, protocol headers, or the server.
Diagnose this errorMost 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.