MCP Server Not Working? 12 Causes and Fixes

MCP (Model Context Protocol) has crossed roughly 97 million installs as of mid-2026, and nearly everyone who's connected a server to Claude Code, Cursor, or another coding agent has hit at least one of the failures on this page. Most "MCP not working" problems fall into a small number of categories, and the fastest way to fix yours is to first answer one question: is your server a local stdio process, or a remote HTTP server? The two failure modes barely overlap.

Step 1: Identify Your Server Type

Stdio server (runs on your machine, launched by your IDE)

Your config has a "command" field, something like "command": "npx", "args": ["-y", "some-package"]. Failures here are almost always environment problems — your app can't find the right binary, or the process crashes on startup.

Remote HTTP server (runs at a URL somewhere else)

Your config has a "url" field instead. Failures here are almost always about authentication, timeouts, or the connection dropping — not about finding a binary on your machine.

Skip straight to whichever section below matches your setup.

Stdio Server Failures

"Command not found" or spawn ENOENT

This is the single most common MCP failure, and it's almost never actually about the MCP server itself. GUI applications like Claude Desktop, Cursor, and VS Code often run with a different PATH than your terminal — especially on macOS when Node.js is installed via nvm or Homebrew. The app simply can't see where npx, uvx, or python actually live, even though your terminal can find them fine.

Fix:

●      Run the exact command from your config directly in a terminal first — if it works there but not in the app, this is your problem

●      Replace a bare "npx" in your config with the full absolute path to the binary (find it by running `which npx` or `where npx`)

●      On macOS specifically, this is common enough that it's worth checking first before assuming anything else is wrong

Server starts but tools never show up

Two different things get confused under this symptom. First, check whether the config actually loaded — a syntax error (a stray trailing comma is enough) will make some apps silently ignore the entire config file rather than showing an error. Validate your JSON with a linter before troubleshooting anything else.

Second, if the config is valid, confirm the client fully restarted. A window reload is often not enough — you frequently need a full application quit (Cmd+Q on Mac, or Exit from the taskbar icon on Windows) before the new server registers.

Server crashes immediately on startup

Run the server command directly in your terminal, outside the IDE. If it prints an error and exits, the problem is the server itself — usually a missing credential, a missing dependency, or an incompatible runtime version — not your IDE's MCP integration.

Remote HTTP Server Failures

Connection drops after about a minute

This is a classic SSE (Server-Sent Events) timeout. Some remote MCP servers still use the older SSE transport, which is more prone to idle-connection drops than the newer Streamable HTTP transport. Check whether the server offers Streamable HTTP, and separately check whether any reverse proxy sitting in front of the server is closing idle connections before the MCP session naturally would.

401 Unauthorized

Confirm your bearer token or API key is actually being sent — some clients require it under a specific config key name, and a slightly wrong field name fails silently rather than throwing a clear error. If the server uses OAuth instead of a static token, this often traces back to a token-exchange mismatch: some MCP clients authenticate using client_secret_basic (credentials sent in an Authorization header), while some server implementations only read client_id from the request body. When that mismatch happens, the authorization step can appear to succeed while the actual token exchange fails silently, leaving you with an empty access token.

OAuth flow loops without ever completing

This usually traces back to the server's metadata endpoint. MCP's OAuth flow expects a valid /.well-known/oauth-authorization-server endpoint; if that's missing or misconfigured (sometimes accidentally deleted during a refactor), some clients fall back to guessing the right paths and fail. Clear any cached credentials in your client and retry after the server-side fix is deployed — retrying against a broken endpoint from the client side won't resolve it.

Client-Specific Issues

Claude Code / IDE extensions

A version-specific bug worth knowing about: the VS Code and Cursor extension's embedded MCP integration has, in some releases, thrown a "MCP error -32601: Method not found" error that then cascades into a broader tool-concurrency failure — while the standalone CLI version of the same tool works fine in the identical environment. If you hit this, the fastest diagnostic step is testing whether the CLI reproduces the problem; if it doesn't, the bug is isolated to the extension's MCP implementation, not the underlying model or your server config. This is one more reason CLI-first tools and IDE-embedded ones behave differently under the hood, as covered in Why CLI Agents Are Beating IDE Assistants.

Cursor specifically

Cursor's MCP support is gated behind a settings toggle that defaults to off in some installs. Open Settings, search "MCP," and confirm "Enable MCP Servers" is checked, then fully restart Cursor. From the Command Palette, run "MCP: View Server Status" to confirm your servers actually loaded rather than guessing from whether tools appear in a chat.

Version Gating (Check This Before Anything Else)

Remote server support, Streamable HTTP transport, and OAuth-based auth were all added to major clients at different points through 2025–2026. If you're running an older version of Claude Desktop, Cursor, or a VS Code extension, some of the fixes above simply won't apply because the feature they depend on doesn't exist yet in your version. Update first, then troubleshoot.

Full Diagnostic Table

A Note on Security-Related Failures

Occasionally an MCP call fails not because anything is broken, but because a client-side or server-side safeguard correctly blocked it — for example, a tool call that looks like it's trying to exfiltrate data through an unexpected channel. Don't reflexively work around a block like this without understanding why it fired first; it may be legitimate protection against exactly the kind of prompt injection risk covered in our security guide. If you're granting an MCP server broad workspace or credential access, it's worth reviewing that guide's permission-scoping principles before troubleshooting further.

Frequently Asked Questions

1. Do I need to restart my whole computer, or just the app?

Just the app — but a full quit (not just closing the window) is required for most clients. A simple window or tab reload frequently isn't enough to pick up a new or changed MCP config.

2. Why does the same server work in Claude Desktop but not in Cursor?

Config file locations and specific key names differ slightly between clients even though both implement the same underlying MCP spec. Double-check you're not just copy-pasting a config verbatim between apps without adjusting the file path or a client-specific field name.

3. Is it safe to just keep restarting the server until it works?

For a server that's being intermittently rate-limited by its own upstream API, a restart is a legitimate short-term fix. It's not a fix for a genuinely broken config, a version mismatch, or a security-related block — those need to be addressed directly or the same failure will just recur.

4. Where do I go from here if none of this fixes it?

Test the server command in isolation outside your IDE first — it's the fastest way to tell whether the problem is the server itself or the client's integration with it. If the server runs cleanly on its own, the bug is almost always on the client side, and checking the client's own GitHub issues for your exact error string is usually faster than continuing to guess.