Fix: "MCP handshake failed / Connection closed"
2 min · 4 steps
A stdio MCP server that connects fine in your terminal but fails in Avery is almost always a PATH / interpreter problem — Avery spawns it with a minimal environment.
When you click Connect and see "MCP handshake failed: … Connection closed", the child process Avery spawned started and then exited before completing the MCP handshake. Avery now appends the server's own stderr (the real error) to that message — read it first. The #1 cause for local servers: Avery spawns the command with a MINIMAL PATH that does NOT include your shell's Python venv, conda env, or nvm/fnm node. So a bare `python` (or `node`) resolves to a different interpreter that doesn't have the server's dependencies installed — you'll see something like `ModuleNotFoundError: No module named 'fastmcp'` in the appended stderr. The fix is to point Command at the ABSOLUTE interpreter path that has the deps. Find it by running, in the same shell where the server works: `python -c "import sys; print(sys.executable)"` — then use that full path (e.g. `/Users/you/proj/.venv/bin/python`) as the Command, with the server script as the first argument.
Steps
- Read the appended stderr.
The error now includes a '--- server stderr (last lines) ---' section with the child process's actual output. A Python traceback, a 'command not found', or a missing-module error tells you exactly what failed.
- Find the interpreter that has the deps.
In the terminal where the server runs correctly: `python -c "import sys; print(sys.executable)"` (or `which node`). Copy the absolute path it prints.
- Use the absolute path as Command.
Edit the connector (or delete + re-add it from the MCP Clients screen) and set Command to that absolute path — e.g. `/Users/you/EODHD-MCP-Server/.venv/bin/python` — with the server script (e.g. `/Users/you/EODHD-MCP-Server/server.py`) as the first argument and any flags (e.g. `--stdio`) on the following lines.
- Reconnect.
Click Connect again. If it still fails, the appended stderr will show the next problem (e.g. a missing API key — set it in the Env vars field as KEY=VALUE).
Live recipes need the desktop
This article is a static preview. The in-app Help sidecar inside Avery NXR can fire each step against your live project — install the desktop to use it interactively.