Skip to main content

MCPX_STDIO_EXIT_NONZERO

Severity: error Domain: STDIO

What happened​

mcpproxy spawned the stdio server, but the process exited with a non-zero exit code before the MCP initialize handshake completed. Whatever crashed it usually printed something useful to stderr.

Common causes​

  • Missing language runtime dependency (e.g. Python 3.10+ required, but only 3.9 available).
  • Missing required environment variable / API key.
  • Bad CLI flags or arguments passed via args.
  • Upstream package not installed in the resolved environment (uvx/pipx/npx).
  • Crash on startup due to incompatible OS or arch.

How to fix​

1. Read the last stderr lines​

mcpproxy upstream logs <server-name> --tail 100

The exit was synchronous: the very last lines almost always contain the real error (a Python traceback, a Node error, "module not found", etc.).

2. Run the command manually​

Reproduce in a normal shell with the exact same command, args, and env from your config:

ENV_KEY=value /full/path/to/cmd --flag1 --flag2

If it fails the same way, fix the underlying tool before retrying through mcpproxy.

3. Check required environment​

Many MCP servers require API keys via environment:

mcpproxy upstream inspect <server-name>   # shows resolved env (secrets redacted)

Add missing keys to the upstream env field or to a referenced secret.

4. Check Python/Node version​

python3 --version    # the server may require >=3.10
node --version       # some packages drop support for old Node majors