ContextQMD
Back to Mcpproxy Go

MCPX_STDIO_HANDSHAKE_INVALID

docs/errors/MCPX_STDIO_HANDSHAKE_INVALID.md

0.38.11.7 KB
Original Source

MCPX_STDIO_HANDSHAKE_INVALID

Severity: error Domain: STDIO

What happened

The stdio server emitted bytes on stdout in response to initialize, but mcpproxy could not parse them as a valid MCP / JSON-RPC frame. Common shapes: HTML, a stack trace, ANSI-coloured logs, partial JSON, or an MCP frame for an unsupported protocol version.

Common causes

  • The server logs to stdout in addition to JSON-RPC frames.
  • The server speaks an older / newer MCP protocol version that mcpproxy can't negotiate.
  • An npm/pip wrapper script printed a deprecation warning before the real process took over.
  • A shell wrapper added stdout content (e.g. set -x, echo "starting…").

How to fix

Read the captured frame

upstream logs records the raw stdout stream — find the offending payload:

bash
mcpproxy upstream logs <server-name> --tail 200

Silence non-JSON output

  • Redirect informational output to stderr in your wrapper script: echo "starting" >&2.
  • Disable colour: NO_COLOR=1, TERM=dumb.
  • Remove set -x or set -v from start-up scripts.

Negotiate a compatible protocol

mcpproxy currently advertises a recent protocol version. If the upstream server only supports an old one, update the server. Project maintainers should target the MCP protocol versions that mcpproxy understands.

Try Docker isolation

Running the server inside a clean container removes most sources of contamination from your shell profile and runtime:

json
{
  "isolation": { "enabled": true }
}