---
title: "MCP Server Not Working? Fixes for Common Errors"
url: "https://mcpshelf.co/guides/mcp-server-errors"
description: "What spawn npx ENOENT, Connection closed, -32000, -32001 timeouts, missing tools and sign-in errors mean in Claude, Cursor, VS Code and Codex, and the fixes."
updated: "2026-11-01"
site: "MCP Shelf"
---

# Fixing MCP server errors

By Sophie Filer · Updated 1 Nov 2026

Most MCP problems come down to five things: the app cannot find the command, the server crashes on start, it starts too slowly, the config has a typo, or the sign-in failed. Find the real error message first, then look it up below.

## First, find the real error

| App | Where the error is |
| --- | --- |
| [Claude Desktop](https://mcpshelf.co/guides/claude-desktop) | Settings → Developer, or the log files: `~/Library/Logs/Claude` on macOS, `%APPDATA%\Claude\logs` on Windows. mcp-server-NAME.log has what the server printed. |
| [Claude Code](https://mcpshelf.co/guides/claude-code) | `claude mcp list` for a status per server, `claude mcp get NAME` for the error, `/mcp` inside a session. |
| [Cursor](https://mcpshelf.co/guides/cursor) | Output panel (Cmd/Ctrl + Shift + U), then MCP Logs in the dropdown. |
| [VS Code](https://mcpshelf.co/guides/vs-code) | MCP: List Servers, pick the server, Show Output. |
| [Codex](https://mcpshelf.co/guides/codex) | `codex mcp list`, and `/mcp` in the terminal UI. |
| [ChatGPT](https://mcpshelf.co/guides/chatgpt) | The error shown when you create or refresh the plugin. |

Then run the same command in a terminal, or better, in [MCP Inspector](https://mcpshelf.co/guides/test-an-mcp-server). If it fails there too, the server or its setup is the problem. If it works there, your app is starting it differently.

## "spawn npx ENOENT" or "command not found"

ENOENT means "no such file": the app could not find the program in "command". Usually Node.js (for npx) or uv (for uvx) is not installed, or the app cannot see it. Apps started from the Dock, Start menu or a launcher do not read your shell profile, so a PATH set in .zshrc, or by nvm, may be missing.

1. Check it is installed: `node --version`, `npx --version`, or `uvx --version` in a terminal.
2. Find the full path: `which npx` on macOS and Linux, `where npx` on Windows.
3. Put that full path in "command", for example `"command": "/opt/homebrew/bin/npx"`. With nvm the path includes the Node version, so update it when you switch versions.
4. Restart the app completely.

On Windows, npx is a script that some apps cannot start directly. Run it through cmd instead: `"command": "cmd"` and `"args": ["/c", "npx", "-y", "package-name"]`. If a Claude Desktop log mentions ${APPDATA}, add your real AppData\Roaming path as "APPDATA" in the env block.

## "Connection closed" or "MCP error -32000"

The server started and then quit before it could answer. Something made it crash, and the reason is in its own output, not in the app's message. Run the command in a terminal and read what it prints. The usual causes:

- A missing or wrong API key, so the server exits at start-up. Check the "env" block, and that the key is not just exported in your terminal.
- Node.js or Python is too old for the package. The server page lists what it needs.
- A wrong argument, such as a folder path that does not exist.
- Docker run with `-d` (detached), or without `-i`. A stdio server needs `docker run -i --rm ...` so it stays attached.
- A server you wrote yourself that prints logs to standard output. In stdio mode that is the message channel; log to standard error instead.

## "Request timed out" or "MCP error -32001"

The server was too slow. Most often it is the first run, while npx or uvx downloads the package. Run the command once in a terminal so it is cached, or give the app longer:

| App | Setting |
| --- | --- |
| Claude Code | MCP_TIMEOUT=60000 claude (start-up), MCP_TOOL_TIMEOUT for long tool calls |
| Codex | startup_timeout_sec = 60 and tool_timeout_sec under the server in config.toml |
| MCP Inspector | --connect-timeout 120000 |
| mcp-remote | --connect-timeout 30, or --auth-timeout 60 for a slow sign-in |

## Config errors

| What you see | Cause and fix |
| --- | --- |
| Every server vanished after an edit | The JSON no longer parses. Look for a trailing comma, a missing comma between servers, curly quotes pasted from a web page, or a comment (JSON has none). Paste the file into a JSON validator. |
| A Windows path breaks the file | Backslashes must be doubled in JSON: `"C:\\Users\\you\\project"`. Forward slashes also work. |
| Claude Code: "Invalid environment variable format" | The -e flag came straight before the server name. Put it after: `claude mcp add NAME -e KEY=value -- command`. |
| Claude Code: "Invalid configuration" from add-json | The JSON has a "url" but no "type". Add `"type": "http"`. |
| VS Code ignores a pasted config | Its .vscode/mcp.json uses "servers", not "mcpServers", and each entry needs a "type". |
| Codex: the server is not listed | A TOML mistake, such as JSON-style `"env": {}` instead of an `[mcp_servers.NAME.env]` table. `codex mcp list` shows what Codex could read. |
| Claude Desktop ignores a "url" entry | Its config file only starts programs. Add the URL under Settings → Connectors, or use [mcp-remote](https://mcpshelf.co/guides/mcp-remote). |

## The server is connected but tools are missing

- It needs sign-in first: look for "Needs authentication" or an Authenticate button.
- It is switched off in the app's tool picker or server list.
- Too many tools from other servers. Some apps cap the total; turn off servers you are not using.
- The app cached an old tool list. In VS Code run MCP: Reset Cached Tools; elsewhere, restart the app.
- The tools exist but the model does not choose them. Name the server in your request, for example "use the Playwright tools to open...".

## Sign-in errors: 401, 403, "Needs authentication"

- Sign in again from the app: `/mcp` in Claude Code, `codex mcp login NAME` in Codex, the server's entry in Cursor, VS Code or ChatGPT.
- For a key or token, check it has the permissions the tool needs. A read-only token gets 403 on writes.
- Check for a stray space or newline pasted at the end of a token. Claude Code warns about this in `claude mcp list`.
- With mcp-remote, a stuck sign-in usually clears after you quit the app and delete the ~/.mcp-auth folder.
- A 404 from a remote server usually means the wrong path: try /mcp instead of /sse, or the other way round.

## Still stuck?

Search the server's GitHub issues for the exact message; every server page on MCP Shelf links to its repository. If nobody has reported it, open an issue with the command you ran, your system, your Node or Python version and the log lines.

## Questions

### It works in my terminal but not in the app. Why?

The app starts the server with a different environment. It does not read your shell profile, so PATH entries and exported keys are missing. Use full paths in "command" and put keys in the config's "env" block.

### What do MCP error codes -32000 and -32001 mean?

In the official MCP SDKs, -32000 means the connection closed, usually because the server process exited, and -32001 means a request timed out. Other negative codes such as -32602 (invalid params) are standard JSON-RPC errors.

### How do I see what a server prints when it starts?

Claude Desktop writes it to mcp-server-NAME.log. Cursor and VS Code show it in their output panels. Or run the server under MCP Inspector, which shows its output as it connects.

---

From [MCP Shelf](https://mcpshelf.co/): A short shelf of MCP servers that are worth installing. Index for agents: https://mcpshelf.co/llms.txt