How to fix: MCP server not connecting / tools not showing up

Last verified: June 2026· Claude Code, Cursor, and other MCP clients

Where this shows up

Claude Code, Cursor, and other MCP clients

How it shows up

The same root cause surfaces in a few different ways. If any of these match, you're in the right place.

The client starts normally but the server's tools never appear in the tool list — no error, just absence.
The server shows as "failed" or "disconnected" in the client's MCP status view.
Logs show spawn ENOENT, meaning the client could not find the command it was told to run.
The server connects, then drops within seconds — usually the process exited or wrote to stdout.
Tools appear but every call returns 401 or an auth prompt that never completes.

Diagnose it first

Confirm which cause you actually have before changing anything — most wasted time here comes from fixing the wrong one.

Check	What the result tells you
Run the exact command from your config manually in a terminal.	If it fails there, the problem is the command or its environment, not MCP. `ENOENT` means the binary is not on the PATH the client uses.
Check whether the server writes anything to stdout on startup.	On stdio transport, stdout is the protocol channel. Any log line, banner, or stray `print` corrupts the JSON-RPC stream and the handshake fails. Logs must go to stderr.
Confirm the transport in the config matches the server: stdio versus HTTP/SSE.	Pointing a stdio config at a URL, or an HTTP config at a local command, fails at connect time with a transport error rather than a useful message.
Read the client's own MCP log file, not just the console.	Most clients write a dedicated MCP log that records the handshake and the server's stderr — this is where the real cause almost always appears.
Test whether the server is reachable from the client's environment, not yours.	A server on localhost is unreachable from a containerised or remote client. Success from your shell proves nothing about the client's network namespace.

The fix

1Verify the server config in your client (command/URL, transport type) matches what the server expects.
2Check authentication — many hosted MCP servers need OAuth, not a plain API key; the two are different auth systems.
3Confirm the server is actually running and reachable from the client’s environment (network/firewall).
4Restart the client after config changes so it re-discovers the server’s tools.
5Read the server logs — most connection failures are auth or transport mismatches that the logs name directly.

Provider-specific behaviour

The error means roughly the same thing everywhere, but each provider signals it differently.

Claude Code: Servers are managed with claude mcp add and scoped to local, project, or user level. A server added at the wrong scope simply will not appear in a different project. claude mcp list shows configured servers and their connection state — start there rather than editing config by hand.
Cursor: Reads MCP servers from its own settings rather than Claude Code's config, so a server that works in one does not carry over. Cursor needs a restart (not just a window reload) to re-run discovery after a config change.
Hosted / remote servers: Most require OAuth rather than a static API key. If your config supplies an API key to a server expecting an OAuth flow, the connection is refused with a 401 that looks like a bad credential but is actually the wrong auth scheme entirely.
Node-based servers via npx: npx resolves against the PATH of the process that spawned it. GUI applications frequently do not inherit the shell PATH set in your profile, which is why an npx-based server works in a terminal and fails from the client. An absolute path to the binary removes the ambiguity.

What doesn't work

Common fixes for this error that look right and aren't.

Reloading the window instead of restarting the client.
Tool discovery runs at client startup. A window reload leaves the previous server list in place, so a corrected config appears not to have worked and you go on to change something that was never broken.
Adding logging to stdout to debug a stdio server.
This is the one change guaranteed to break a working stdio server, because stdout carries the JSON-RPC protocol. It converts a config problem into a protocol problem. Log to stderr instead.
Assuming a 401 from the server means your API key is wrong.
For hosted MCP servers the more common cause is that the server expects OAuth and no token has been issued yet. Rotating the key changes nothing because the key was never the credential being checked.

Prevent it

Use a well-built MCP server with clear auth, health checks, and logging so connection issues are obvious and rare.

Common variations and related errors

You'll usually hit this same root cause under a few different names. Same fix.

"MCP server not found"
"tool not available"
"spawn ENOENT"
"connection refused"
"401 from MCP server"
"OAuth callback failed"
"MCP transport error"

Frequently asked questions

What causes “MCP server not connecting / tools not showing up”?

The server config, transport, or auth is misconfigured, so the client can’t reach or authenticate to the MCP server.

How do I prevent “MCP server not connecting / tools not showing up” from recurring?

Use a well-built MCP server with clear auth, health checks, and logging so connection issues are obvious and rare.

Why do my MCP tools work in Claude Code but not in Cursor?

Each client keeps its own MCP configuration — there is no shared registry. A server registered with `claude mcp add` is unknown to Cursor until you add it separately in Cursor's settings. Server scope compounds this: a server added at project scope in one tool will not appear in another project at all, even in the same client.

What does `spawn ENOENT` mean for an MCP server?

The client tried to launch the command in your config and the operating system could not find that executable on its PATH. It is a "command not found" error, not an MCP protocol error. It usually means the tool is not installed, or the client is a GUI application that did not inherit the PATH from your shell profile. Using an absolute path to the binary resolves it.

My MCP server connects but the tools do not appear. Why?

The transport connected but the handshake did not complete, so the client never received a tool list. The two usual causes are the server writing non-protocol output to stdout, or the server erroring during initialisation after the connection opened. The client's MCP log will show the handshake stopping partway, and the server's stderr will name the underlying error.