MCP server “Failed to connect”: how to find the cause

Quick checklist

1. 1. Run the command yourself
2. 2. Check the config file
3. 3. Check Node, npx and uvx
4. 4. Does it need something else running?
5. 5. Test the server outside your app
6. 6. Read your app's logs

1. Run the command yourself

Copy the exact command and args into a terminal and run them. A stdio server that starts correctly just waits silently for input (press Ctrl+C to stop). An error, a “command not found” or a crash here is the real problem, and the app's log will show the same thing.

2. Check the config file

One stray comma breaks the whole file, and then no server loads. JSON doesn't allow trailing commas or comments, and every key and string needs double quotes. Check the file with:

python3 -m json.tool your-config.json

It prints the file back if it's valid, or the line and column of the first error.

3. Check Node, npx and uvx

Most servers start with npx -y … (Node.js) or uvx … (uv). In our tests context-mode needed Node 22.5+ and failed under Node 20.19. See Node, npx and uvx errors.

4. Does it need something else running?

Jupyter MCP only connects to a running Jupyter server, and Draw.io MCP acts on an open draw.io editor. We failed Jupyter until a local JupyterLab was started.

5. Test the server outside your app

The official MCP Inspector starts a server and lists its tools, so you can tell a server problem from an app problem: npx @modelcontextprotocol/inspector <command> <args>.

6. Read your app's logs

Each app logs MCP startup errors in a different place. The app guides below show where.

Sources

• MCP docs: Debugging
• MCP docs: Inspector

Links checked 2026-10-14. Items marked “Our tests” come from our own harness runs, shown on each server page with the date.