Quick answer: "Claude could not connect to MCP server" almost always comes down to one of five things: a broken local path or config, a missing environment variable, a stale process still holding the connection, an expired auth token, or the server being reachable but pointed at the wrong endpoint. Which one you're hitting depends on whether you're running a local (stdio) server or connecting to a remote (OAuth) one — the fixes below are ordered easiest-first for both.
You added the server, the config looks right, and Claude still throws some version of "failed to connect," "couldn't reach the MCP server," or an error code like -32000. It's one of the most common pain points anyone hits extending Claude with MCP — and it's rarely as mysterious as the error message makes it sound.
What This Error Actually Looks Like
- "Failed to connect" or "Connection closed" in Claude Code or Claude Desktop
- "Couldn't reach the MCP server" in Claude 's Connectors settings
- "Authorization with the MCP server failed"
- A server listed as disconnected when you run
claude mcp list - MCP error codes
-32000 (connection closed), -32001 (request timed out), or -32601 (unimplemented method — usually harmless) - The server connects, but shows zero tools available
Why This Happens
It splits cleanly into two categories, depending on how the server is set up.
Local (stdio) servers — the kind you run yourself via a config file in Claude Desktop or Claude Code — fail almost entirely due to environment problems: wrong paths, missing variables, or a process that never actually started. Claude isn't rejecting the server; it's failing to launch it in the first place.
Remote (HTTP/OAuth) servers — the kind you connect to via a URL, like most hosted gateways — fail differently: authentication expiring, the endpoint being wrong, or the server being temporarily unreachable. Claude did reach out; it just didn't get a valid response back.
Fix 1: Check for a Relative Path or Missing Absolute Path
The single most common local-server failure. If your config points to a script or binary using a relative path, it works when launched from one directory and silently breaks from any other. Use an absolute path, or rely on a PATH-resolvable command like npx instead of a hardcoded file location.
Fix 2: Confirm Environment Variables Are Actually Reaching the Server
API keys and secrets placed in the wrong config location are a frequent, invisible cause of failure — they don't error loudly, the server just starts without the credentials it needs. Environment variables need to be set directly on the server's own config entry (or passed at add-time), not dropped into a separate settings file that doesn't propagate to the server process.
Claude Desktop and Claude Code use different config locations and formats. A config that's correctly written but sitting in the wrong file, or nested inside the wrong folder, will simply never load — Claude won't complain, it just won't see it.
Fix 4: Run the Server's Command Directly in a Terminal
If the config looks right and it still won't connect, take the exact command Claude is trying to run and execute it yourself in a terminal. If it fails there — missing dependency, wrong runtime version, bad argument — that's your real error, and it has nothing to do with Claude itself. This single step resolves a large share of "mysterious" local connection failures.
Fix 5: Kill Stale or Duplicate Server Processes
If a server connected fine before and now fails intermittently — especially after resuming a session — check whether a previous instance of the process is still running in the background. Multiple copies of the same server competing for the same connection is a common, easy-to-miss cause. Kill any lingering processes and restart.
Fix 6: Re-authenticate if You're Seeing 401/403
For remote, OAuth-based servers, a 401 or 403 response almost always just means the token expired. Re-run the authentication flow rather than troubleshooting further — Claude won't retry an expired auth error on its own, so waiting it out doesn't help.
Fix 7: Double-Check the Server URL for 404/405 Errors
A 404 or 405 means Claude successfully reached a server — just not the right endpoint. Double-check the URL for typos, trailing slashes, or an outdated path from an old setup guide.
Fix 8: Give It a Moment on 5xx or Timeout Errors
Server-side errors or timeouts are usually transient. Claude retries automatically a handful of times on its own; if it's still failing after that, the issue is on the server's hosting side, not your configuration.
Still Not Fixed?
If you've worked through all of this and the server still won't connect, the fastest remaining step is running the server's diagnostic or doctor command if the platform has one — it surfaces the majority of misconfigurations in a single pass. Beyond that, it's worth checking whether the server itself has a known issue: search the server's repository or documentation for the exact error code you're seeing before assuming the problem is on your end.
Where This Gets Genuinely Easier
Here's the honest pattern in almost everything above: most of these failures — the path issues, the missing environment variables, the wrong config location, the stale processes, the runtime version mismatches — only exist because you're running the server yourself, locally. There's no config file to misplace and no process to go stale if there's no local server to manage in the first place.
A hosted MCP gateway like MCP Express removes that entire category of failure. You're not editing a JSON config or tracking down a relative path — you connect once via OAuth, and the server runs on infrastructure you don't have to maintain. That doesn't make authentication issues disappear entirely (an expired token is still an expired token, on any platform) — but it does mean the most common causes of "Claude could not connect" simply aren't things you have to debug anymore.
You’ll find a number of integrations ready to connect in just under 5 minutes. Get your credentials, configure actions allowed, and connect to Claude. No coding required on your part. Easy as that!
Sign up today for free at MCP Express.
FAQ
- What does MCP error -32000 mean?
It means the connection closed, usually right after the server tried to start — almost always a local launch failure (bad path, missing dependency, or crashed process), not a Claude-side problem.
- Why does my MCP server show as connected but with zero tools?
The server started, but isn't returning any tool definitions — usually a permissions or configuration issue on the server itself, not a connection failure.
- Do I need to restart Claude after fixing my MCP config?
Often yes, especially for local servers — a full restart clears old connection state that a simple reconnect attempt won't.
- Why did my MCP server work yesterday and fail today with no changes?
Check for a stale process still holding the old connection, or an expired auth token if it's a remote server — both are common causes of failures that appear with no configuration changes at all.
- Is a "Claude could not connect to MCP server" error something I did wrong?
Not usually — it's one of the most common issues anyone extending Claude with MCP runs into, local and remote setups alike. It's a debugging step, not a sign something's fundamentally broken.
Stop Debugging Config Files
If this list feels like more troubleshooting than you signed up for, that's a fair reaction — local MCP setup genuinely has a lot of small places to go wrong. Connect a hosted MCP server instead → No credit card required, nothing to configure locally.
