Home/Wiki Errors/MCP
MCP / MCP

MCP server crashed unexpectedly

The MCP host launched the server, but the subprocess exited or the remote transport closed before tools could be used.

MCP server crashed unexpectedlyMCP process exitedMCP server stderr
Paste an error to match it against the wiki. / 粘贴报错后自动匹配。

Error text / 报错原文

  • MCP server crashed unexpectedly
  • server crashed
  • process exited

What it means

The MCP host launched the server, but the subprocess exited or the remote transport closed before tools could be used.

Most common causes

  • Missing env var or secret
  • Wrong Node/Python runtime version
  • Unhandled exception inside the server
  • The server expects stdin/stdout but logs normal text to stdout

Fastest fix

  • Run the exact server command outside the host
  • Inspect stderr and exit code
  • Set required env vars in the host environment
  • Temporarily disable the server to unblock the agent

Safe fix

  • Log diagnostics to stderr, not stdout
  • Pin runtime and package versions
  • Add health checks for custom MCP servers
  • Keep secrets out of config files

What not to do

  • Do not silence crashes by swallowing all exceptions
  • Do not put debug logs on stdout for stdio MCP
  • Do not give a crashing server broad write access

How to confirm the fix

Run the smallest reproducible command first, then retry the agent task only after authentication, quota, and tool discovery are stable.

node --version
python --version
env | sort

Related errors

Related tools

Sources