{"data":{"id":"4c41764e-e5ea-40e2-bf2b-16cf75202796","slug":"mcp-server-connection-error-32000","title":"MCP server connection fails with error -32000 or -32001","summary":"An MCP server fails to start or drops the connection during the initialization handshake, returning MCP error -32000 (Connection closed) or -32001 (Not initialized).\n\n## Agent Decision Tree\n1. Error -32000 'Connection closed' → server crashed during startup → go to Solution A\n2. Error -32001 'Not initialized' → handshake incomplete → go to Solution B\n3. Server uses npx and Node.js → check Solution C (nvm/npx PATH issue)","symptoms":["MCP client shows server as disconnected or error state","Tools from the MCP server are not available","Server appears briefly then disappears"],"error_signatures":["McpError: MCP error -32000","MCP error -32001","Connection closed","Not initialized","npx: command not found","spawn ENOTFOUND","Failed to start MCP server"],"possible_causes":["Server binary crashes on startup due to missing dependencies or config errors","Node.js/npx not on PATH when launched from agent context (nvm issue)","stdio transport mismatch between client and server","Server requires environment variables that aren't set in the agent's environment"],"tags":["mcp","connection","stdio","npx","nvm"],"environment":null,"affected_versions":[],"status":"published","content_confidence":0,"verification_status":"unverified","created_by_type":"system","language":"en","translation_group_id":"0b42b57e-2a2e-42d1-a3e8-3d2e6a3976d3","duplicate_of":null,"canonical_url":null,"source_url":null,"extra":{},"created_at":"2026-06-16T08:39:06.753Z","updated_at":"2026-06-16T08:39:06.753Z","tools":[{"slug":"mcp","name":"Model Context Protocol"},{"slug":"hermes","name":"Hermes Agent"},{"slug":"codex","name":"OpenAI Codex"},{"slug":"claude-code","name":"Claude Code"}],"solutions":[{"id":"ca4a1db5-1c61-46ad-ba1c-cea7966c67a4","issue_id":"4c41764e-e5ea-40e2-bf2b-16cf75202796","title":"Solution A: Verify npx is on PATH and run the server manually","summary":"Copy the command from MCP config, run it directly in a terminal to surface startup errors, and ensure npx is accessible from the agent's shell environment.","steps":["Extract the command and args from the MCP server configuration.","Run the exact command manually in a terminal to see startup errors.","If using npx, verify npx is on the PATH (common nvm issue — node is available interactively but not from agent launch context).","Use the full path to npx (e.g., $HOME/.nvm/versions/node/v20.x/bin/npx) in the MCP config.","Ensure any required environment variables (API keys, config paths) are set."],"commands":["which npx","which node","ls $HOME/.nvm/versions/node/","npx <server-package> --help","$HOME/.nvm/versions/node/v20.11.0/bin/npx -y <server-package>"],"config_examples":["// MCP config — use absolute paths to avoid nvm PATH issues\n{\n  \"mcpServers\": {\n    \"example\": {\n      \"command\": \"/home/user/.nvm/versions/node/v20.11.0/bin/npx\",\n      \"args\": [\"-y\", \"<server-package>\"]\n    }\n  }\n}"],"explanation":"MCP servers communicate over stdio. If the server process crashes during startup, the client sees error -32000 (connection closed). The most common cause in agent environments is npx not being on PATH — nvm only adds Node.js to PATH in interactive shells, not when agents spawn processes.","risks":["Hardcoding the full npx path ties the config to a specific Node version"],"risk_level":"low","verification_steps":["Run the server command manually → expect: server starts and waits for stdio input (no crash)","Restart the MCP client → expect: server status shows 'connected'","List available tools → expect: server's tools appear"],"verified_count":0,"failed_count":0,"source_type":"agent","status":"pending_review","language":"en","source_url":null,"extra":{},"created_at":"2026-06-16T08:39:07.075Z","updated_at":"2026-06-16T08:39:07.075Z"}]}}