MCP troubleshooting

10 pages, each built from errors we recorded while installing and starting MCP servers. Every page quotes the exact output, names the servers it came from, and links official docs for the fix.

• MCP error -32000: Connection closed. Why MCP servers exit on startup
  Stdio MCP servers we launched: 34 of 231 failed to start or answer the handshake (32 exited, 1 failed to install, 1 timed out). Verbatim errors grouped by cause, from our 2026-11-10 tests. Updated 2026-11-10.
• MCP protocol version mismatch: HTTP 400 on initialize
  Qt's docs MCP server answered HTTP 400 to protocol 2025-06-18 in our test, while 20 listed servers negotiated an older version. Cause, spec rules and fixes. Updated 2026-11-11.
• Python MCP server error: 'Server' object has no attribute 'list_tools' / 'list_resources'
  7 Python MCP servers crashed with mcp SDK 2.x errors in our 2026-11-10 tests. Verbatim errors, affected versions, and the mcp<2 pin (not tested by us). Updated 2026-11-10.
• MCP remote server returns 401 Unauthorized
  35 remote MCP servers answered our no-credential request with HTTP 401 and an OAuth challenge, 1 with 401 asking for an API key. Verbatim headers, cause and fixes. Updated 2026-11-11.
• MCP server exits on start: missing environment variable
  20 stdio MCP servers we list exited at launch asking for an environment variable. Verbatim messages, why a terminal export isn't enough, and the env block fix. Updated 2026-11-11.
• MCP server native module won't load
  MCP servers that failed on a native Node add-on in our tests: a missing SQLite binding with install scripts off, and an ONNX Runtime library mismatch. Verbatim errors and fixes. Updated 2026-11-11.
• MCP server can't find a program it needs
  MCP servers that exited because a program they wrap was missing (lbrain, gcloud) in our tests. Verbatim errors, the PATH check, and npx/uvx install links. Updated 2026-11-11.
• MCP server timeout: no answer to initialize or tools/list
  Why MCP servers time out, from our tests: an HTTP server started instead of stdio, and a scripts-off install that never answered tools/list. Large tool lists were not the cause. Updated 2026-11-11.
• MCP server exits with 'unknown command' or a usage error
  MCP servers that exited with a usage error in our tests: Prisma 8.0.0-rc.33 has no mcp command, 3 listed servers need a subcommand or argument, 3 have no entry point. Updated 2026-11-11.
• MCP 'tool not found' right after the server starts
  MUI MCP listed 2 tools at start and 3 about 8 s later; the first call failed with 'Tool useMuiDocs not found'. Cause and fix. Updated 2026-11-11.

We launch each server with our own MCP client and no credentials. We have not run these servers inside Claude Code, Claude Desktop or Cursor. How we test: methodology. Guides: all guides.