MCP server not working in Cursor, Claude Code or VS Code: the causes, in order
A server that does not show up, hangs on loading tools, or fails every call almost always has one of twelve causes. Here they are, from most to least common, with the check and the fix for each client.
Client-specific statements quote each client's own documentation as read on 19 November 2026 (sources at the end); the generic causes are the ones the MCP quickstart's troubleshooting section and the Serverdex live check surface every day. Work down the list: the first causes are the common ones.
- 1. The config file is not valid JSON
- 2. Right JSON, wrong file or wrong scope
- 3. The command is not on the client's PATH
- 4. Relative paths in args
- 5. A required environment variable is missing
- 6. The hosted server wants a sign-in first (401/403)
- 7. The URL is not an MCP endpoint
- 8. Transport mismatch: SSE where the server speaks Streamable HTTP, or the reverse
- 9. The client has not reloaded the config
- 10. The server crashes on start
- 11. The hosted server is down
- 12. Too many tools for the context
1. The config file is not valid JSON
Looks like: The server never appears; the client shows no servers at all, 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 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. Generate the block instead of typing it: the config generator and every server page on Serverdex output valid JSON for each client.
2. Right JSON, wrong file or wrong scope
Looks like: The config looks correct but the client does not list the server.
Check. Each client reads its own file: Claude Desktop claude_desktop_config.json (macOS ~/Library/Application Support/Claude/, Windows %APPDATA%\Claude\, Linux ~/.config/Claude/), Cursor ~/.cursor/mcp.json (global) or .cursor/mcp.json (project), VS Code .vscode/mcp.json (workspace) with a servers object, not mcpServers; Zed uses the context_servers key in its settings; Cline cline_mcp_settings.json; Codex ~/.codex/config.toml in TOML. Claude Code has three scopes (local, project, user) and the claude mcp list command shows what is loaded.
Fix. Use the path and shape for your client from the client guides (each one quotes its client's docs with the source link). In Claude Code, add with claude mcp add and the scope you mean.
3. The command is not on the client's PATH
Looks like: Spawn error, ENOENT, or “command not found” in the client's log; the server fails before it starts.
Check. Desktop apps are launched by the operating system, not by your shell, so npx, uvx or docker installed through a version manager (nvm, pyenv) may not be visible to them. Run the exact command from the config in a plain terminal first: if it works there but not in the client, PATH is the difference.
Fix. Put the absolute path to the executable in command (for example the output of which npx), or install the runtime system-wide. On Windows, the MCP quickstart adds that npx keeps failing when npm is not installed globally (%APPDATA%\npm missing): run npm install -g npm.
4. Relative paths in args
Looks like: Filesystem-type servers start but cannot see the folders you expect, or exit at once.
Check. The MCP quickstart's checklist: “make sure the file paths […] are valid and that they are absolute and not relative”. The client's working directory is not your project folder.
Fix. Use full absolute paths in args; on Windows escape the backslashes.
5. A required environment variable is missing
Looks like: The server starts and lists tools, but every call fails with an authentication or configuration error.
Check. Open the server's Serverdex page: the “Connect this server” block lists the variables its registry entry marks as required or secret, with placeholders like <your API_KEY> that must be replaced. Values can be given in the env object (Claude Desktop, Cursor, Cline, Windsurf) or with --env (Claude Code, Codex).
Fix. Fill every placeholder and restart. In Claude Code, keep another option between --env and the server name (the docs show --transport stdio) or the CLI reads the name as a second KEY=value pair. On Windows, the quickstart documents an ENOENT with ${APPDATA} in the path, 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 client shows the server but no tools, or an authentication error.
Check. Look at the server's live check on Serverdex: “Needs sign-in” means the endpoint answered our credential-free handshake with HTTP 401 or 403, so it wants an API key in a header or an OAuth login before it lists anything. The needs sign-in list shows the time of each check.
Fix. Give the key in headers (Cursor, VS Code, Cline, Windsurf, Zed) or as a bearer token variable in Codex (bearer_token_env_var), 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; the client reports a parse error or an unexpected status.
Check. Live check “Not an MCP endpoint” on the server page means the URL 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 on the machine that runs it.
Fix. Use the endpoint from the server's own documentation (typically ending in /mcp), or run the server locally from its package instead.
8. Transport mismatch: SSE where the server speaks Streamable HTTP, or the reverse
Looks like: The server is reachable but the handshake never completes; tools never load.
Check. Cline's docs: an entry with a url but no 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 to SSE, earlier versions need --transport sse explicitly. VS Code distinguishes type: http from type: sse.
Fix. Set the transport explicitly to what the server publishes: "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.
Check. Claude Desktop reads the config at startup (the quickstart says to quit it completely and restart). Other clients reload on save or offer a refresh button next to the server.
Fix. Quit and reopen the client; in Claude Desktop, check Settings → Developer for the server and its status, and the “Add files, connectors, and more” menu for its tools.
10. The server crashes on start
Looks like: The server shows up briefly, then disappears, or shows an error state.
Check. Read the server's own 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 in a terminal shows the same error without the client in the way.
Fix. Fix what the log says: a missing runtime version, a missing package argument the server requires (the registry's packageArguments are shown as placeholders on the Serverdex page), a port in use.
11. The hosted server is down
Looks like: A remote server that worked yesterday times out today.
Check. The Serverdex live check calls every listed hosted server about once a day; “Unreachable” with a count of consecutive failed checks means the endpoint itself is not answering.
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 each turn. The server page shows the estimated context cost of a server's tool list (characters ÷ 4), and the State of MCP report gives the median and the heaviest servers.
Fix. Disable servers you are not using in that project, or expose only the tools you need where the client supports it (VS Code's tools field, Cline's per-server toggles, Cursor's per-server enable switch).
Still stuck?
Check 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 and variables from the registry. Per-client setup, with the config paths quoted from the docs: Claude Desktop · Claude Code · Cursor · VS Code · Cline · Windsurf · Zed · JetBrains AI Assistant · Continue · OpenAI Codex CLI.
Sources
- Connect to local MCP servers — modelcontextprotocol.io (troubleshooting section: syntax, absolute paths, logs, ENOENT/APPDATA, npm global)
- Connect to local MCP servers (modelcontextprotocol.io) — read 19 November 2026
- Connect to remote MCP servers (modelcontextprotocol.io) — read 19 November 2026
- Building connectors (claude.com docs) — read 19 November 2026
- Claude Code: Connect to tools via MCP — read 19 November 2026
- Cursor docs: Model Context Protocol — read 19 November 2026
- VS Code: MCP configuration reference — read 19 November 2026
- VS Code: Use MCP servers — read 19 November 2026
- Cline docs: Configuring MCP servers — read 19 November 2026
- Cline docs: MCP overview — read 19 November 2026
- Windsurf docs: Cascade MCP — read 19 November 2026
- Zed docs: Model Context Protocol — read 19 November 2026
- JetBrains AI Assistant: MCP — read 19 November 2026
- Continue docs: MCP — read 19 November 2026
- OpenAI: Model Context Protocol for Codex CLI — read 19 November 2026