DEV Community

Andrei
Andrei

Posted on Originally published at serverdex.io

Your MCP server "isn't working"? It's one of these 12 things. I checked 21,555 hosted servers to put them in order.

Every week someone posts the same screenshot: an MCP server that shows up in Cursor or Claude Code with no tools, a red dot, or a chat that pretends the server does not exist. The config is "exactly like the docs". It still does not work.

I run Serverdex, a directory synced from the official MCP registry (41,114 listed servers on 20 November 2026). Since 17 November we also call every hosted server with a plain initialize + tools/list request, no credentials, about once a day. After 21,555 of those calls, the failure modes stopped being mysterious: they fall into a short list, and the order is not random.

Here is that list, most common first, with the check and the fix for each. Client-specific statements quote the client's own documentation as read on 19 November 2026; the links are at the end.

1. The config file is not valid JSON

Looks like: the server never appears; the client lists no servers, or ignores the file silently.

Check: paste the file into a JSON validator. The usual culprits: a trailing comma after the last entry, a missing comma between two servers, Windows paths with single backslashes (C:\Users must be C:\\Users), smart quotes copied from a chat window. The MCP quickstart's own first step for a missing server is "check your claude_desktop_config.json file syntax".

Fix: fix the syntax, save, restart the client. Or stop typing it: every server page on Serverdex has the config for each client with the real package name and variables, and the config generator writes it for anything else.

2. Right JSON, wrong file or wrong scope

Looks like: the config is correct but the client does not list the server.

Check: each client reads its own file and shape:

Client Where Shape
Claude Desktop claude_desktop_config.json in ~/Library/Application Support/Claude/ (macOS), %APPDATA%\Claude\ (Windows), ~/.config/Claude/ (Linux) mcpServers
Claude Code claude mcp add with scope local / project / user; project scope writes .mcp.json mcpServers
Cursor ~/.cursor/mcp.json (global) or .cursor/mcp.json (project) mcpServers
VS Code .vscode/mcp.json (workspace) or the user mcp.json servers with a type
Cline cline_mcp_settings.json mcpServers, remote needs "type": "streamableHttp"
Zed settings.json context_servers
Codex CLI ~/.codex/config.toml [mcp_servers.<name>] TOML

Fix: use the path and shape for your client. I keep one page per client with the paths quoted from its docs, for example Claude Code and Cursor.

3. The command is not on the client's PATH

Looks like: spawn error, ENOENT or "command not found" in the client's log.

Check: desktop apps are started by the operating system, not by your shell, so npx, uvx or docker installed through nvm or pyenv may be invisible to them. Run the exact command from the config in a plain terminal: if it works there and not in the client, PATH is the difference.

Fix: put the absolute path to the executable in command (the output of which npx), or install the runtime system-wide. On Windows the quickstart adds: npx keeps failing when npm is not installed globally (%APPDATA%\npm missing), so npm install -g npm.

4. Relative paths in args

Looks like: a filesystem-type server starts but cannot see your folders, or exits at once.

Check: the quickstart's checklist says it: paths must be absolute, not relative. The client's working directory is not your project folder.

Fix: full absolute paths in args; on Windows, escape the backslashes.

5. A required environment variable is missing

Looks like: tools are listed, every call fails with an auth or configuration error.

Check: the server's registry entry declares which variables are required or secret. On Serverdex they appear as <your API_KEY> placeholders in the connect block, and they must be replaced.

Fix: fill every placeholder and restart. Claude Code detail from its docs: keep another option between --env and the server name (--transport stdio works), or the CLI reads the name as a second KEY=value pair. Windows detail from the quickstart: an ENOENT with ${APPDATA} in the path is fixed by adding APPDATA to env.

6. The hosted server wants a sign-in first (401/403)

Looks like: a remote URL is configured, the server shows but has no tools, or you see an authentication error.

Check: of the 21,555 hosted servers I called without credentials, 5,371 answered 401 or 403: they want an API key in a header or an OAuth login before they list anything. The Serverdex page shows "Needs sign-in" for those, with the time of the check.

Fix: give the key in headers (Cursor, VS Code, Cline, Windsurf, Zed) or as a bearer-token variable in Codex, or run the client's OAuth flow: /mcp inside Claude Code (or claude mcp login), codex mcp login, the prompt Zed shows for a URL without an Authorization header, the Connectors dialog in Claude Desktop. Windsurf's docs: OAuth is not available for stdio servers.

7. The URL is not an MCP endpoint

Looks like: connection error, or an HTML page where JSON-RPC was expected.

Check: 1,470 of the hosted servers I called answered, but not with MCP: a docs page, an old path, a placeholder host meant for self-hosting, or a localhost address that only works where the server runs. Serverdex labels those "Not an MCP endpoint".

Fix: use the endpoint from the server's own documentation (typically ending in /mcp), or run it locally from its package.

8. Transport mismatch

Looks like: reachable, but the handshake never completes.

Check: Cline's docs: a url without a type defaults to the legacy sse transport. Claude Code's docs: SSE is deprecated; from v2.1.265 it tries HTTP first and falls back, earlier versions need --transport sse. VS Code separates type: http from type: sse.

Fix: say the transport explicitly: "type": "streamableHttp" in Cline, "type": "http" in VS Code and in a Claude Code .mcp.json, --transport http on the Claude Code command line, type: streamable-http in Continue's YAML.

9. The client has not reloaded the config

Looks like: you edited the file; nothing changed.

Fix: Claude Desktop reads the config at startup, so quit it completely and reopen. Other clients reload on save or have a refresh button next to the server.

10. The server crashes on start

Looks like: it shows up for a moment, then disappears or turns red.

Check: read its stderr. Claude Desktop writes mcp.log and mcp-server-NAME.log under ~/Library/Logs/Claude (macOS), %APPDATA%\Claude\logs (Windows) or ~/.config/Claude/logs (Linux). Running the command by hand shows the same error without the client in the way.

Fix: whatever the log says: a runtime version, a required package argument (Serverdex shows the registry's required arguments as placeholders), a port already in use.

11. The hosted server is down

Looks like: worked yesterday, times out today.

Check: 668 of the hosted servers I called did not answer at all. Serverdex marks those "Unreachable" with the count of consecutive failed checks and never removes them for one miss.

Fix: wait, or switch: the remote servers list shows the ones that answered at the last pass, and each server page lists alternatives in the same category.

12. Too many tools for the context

Looks like: everything connects, but the model gets slow, ignores tools, or the client warns about the number of tools.

Check: every tool definition is sent to the model on every turn. Across the servers that answered, the median server costs about 4.8k tokens of definitions per conversation before any work happens; the heaviest ones cost far more. Serverdex shows the estimate on each page.

Fix: disable servers you are not using in that project, or expose only the tools you need where the client supports it.


Still stuck? Open the server's page on Serverdex: the live check tells you whether its hosted endpoint answers right now and with which tools, the repository section whether it is still maintained, and the connect block gives the config for your client with the real arguments. The full guide with sources is at serverdex.io/articles/mcp-server-not-working.

Sources (read 19 November 2026): modelcontextprotocol.io "Connect to local MCP servers" (troubleshooting section); code.claude.com/docs/en/mcp; cursor.com/docs/context/mcp; code.visualstudio.com/docs/agents/reference/mcp-configuration; docs.cline.bot/mcp/configuring-mcp-servers; docs.devin.ai/windsurf/plugins/cascade/mcp; zed.dev/docs/ai/mcp; learn.chatgpt.com/docs/extend/mcp?surface=cli; the Serverdex live-check figures are from serverdex.io/remote on 20 November 2026 (21,555 called, 13,717 answering, 5,371 needing sign-in, 1,470 not MCP, 668 unreachable); the median context cost from serverdex.io/state-of-mcp the same day.

Top comments (0)