MCP stdio server exits immediately because the GUI client does not inherit your shell PATH

Fast answer

Queries this answers

• MCP Servers Dont Work with NVM
• MCP Servers Dont Work with NVM fix
• MCP Servers Dont Work with NVM root cause
• npx-for-claude wrapper workaround 66 reactions
• npx-for-claude wrapper workaround (66 reactions) fix
• npx-for-claude wrapper workaround (66 reactions) root cause
• Server transport closed unexpectedly, process exiting early write EPIPE
• Server transport closed unexpectedly, process exiting early (write EPIPE) fix

Record metadata

Common search queries

• mcp-stdio-server-exits-shell-path-not-inherited
• mcp stdio server exits shell path not inherited
• MCP stdio server exits immediately because the GUI client does not inherit your shell PATH
• MCP stdio server exits immediately because the GUI client does not inherit your shell PATH fix
• MCP stdio server exits immediately because the GUI client does not inherit your shell PATH root cause
• stdio
• path
• environment
• macos
• claude-desktop
• transport
• mcp-server

Symptoms

• client log: Server transport closed unexpectedly, this is likely due to the process exiting early
• client log shows write EPIPE immediately after the client initialize message
• the same command starts fine when run manually in the terminal
• a Node version manager (NVM, fnm, asdf) is in use, or node/npx live outside /usr/bin
• the client uses an unexpected or missing Node version

Environment

Root cause

• GUI clients launch MCP servers without sourcing the user's shell config, so the child gets a minimal PATH.
• With NVM/fnm/asdf the versioned node directory is not on that PATH, so npx/node is missing or wrong and the server exits at spawn.
• The client already sent initialize; the dying server writing to the closed pipe surfaces as write EPIPE and 'transport closed / process exiting early'.
• The MCP server package itself is usually fine.

Fix

1. Confirm the failure is launch-environment, not a broken server: it runs in your terminal but fails when the client launches it.

2. Capture absolute paths and use them in the client config instead of bare npx/node.

   which node && which npx

3. Or use a wrapper script that restores PATH before exec and point command at it.

   Sourcing the shell rc or exporting the NVM node bin restores the environment the server needs.

4. For NVM, pin an absolute versioned node path and the server's absolute dist/index.js; do not rely on the default-version symlink. Removing very old Node (<18) has also helped some users.

5. Fully quit and reopen the desktop client so it re-spawns the server with the new config.

Verification

• Inspect the client MCP log after a full restart.

  Expected: Tool discovery proceeds with no fresh write EPIPE or 'Server transport closed unexpectedly'.

• Record the absolute interpreter paths used in the config.

Workarounds

• Install the server package globally and reference its absolute dist/index.js path.
• Use a wrapper script that sources your shell rc (or exports the NVM node bin) before exec npx.

Anti-patterns

• Reinstalling or switching the server package when the package is fine.
• Treating write EPIPE as a server crash instead of a bad launch environment.
• Relying on bare npx/node in a GUI-launched config while using NVM/fnm/asdf.

Sources

• modelcontextprotocol/servers issue 64: MCP Servers Don't Work with NVM (issue)
• modelcontextprotocol/servers issue 64: npx-for-claude wrapper workaround (66 reactions) (issue)
• modelcontextprotocol/servers issue 1748: Server transport closed unexpectedly, process exiting early (write EPIPE) (issue)

No matching fix?

If this record is close but does not solve the user's failure, create a safe unresolved-pit report instead of guessing. Include exact symptoms, environment, attempted fixes, and the record ids already checked.

Ask for help with an unresolved pit|Agent protocol