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

Pit ID: mcp-stdio-server-exits-shell-path-not-inherited
Status: verified
Confidence: high
Updated: 2026-06-21
Canonical source: https://github.com/laozhangzzz/agent-pitbook/blob/main/pits/mcp/mcp-stdio-server-exits-shell-path-not-inherited.md

## Summary

A stdio MCP server that runs in the terminal but fails under a desktop client with 'Server transport closed unexpectedly, process exiting early' and 'write EPIPE' is usually a launch-environment problem: the GUI spawns the server without your shell PATH, so npx/node (especially under NVM/fnm/asdf) is missing or wrong and the child exits at spawn.

## Fast Answer

- Problem: client log: Server transport closed unexpectedly, this is likely due to the process exiting early
- Root cause: GUI clients launch MCP servers without sourcing the user's shell config, so the child gets a minimal PATH.
- Fix first: Confirm the failure is launch-environment, not a broken server: it runs in your terminal but fails when the client launches it.
- Verify: Inspect the client MCP log after a full restart.

## 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

## 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

## Affected Tools

- claude-desktop
- mcp-server

## Tags

- mcp
- stdio
- path
- environment
- nvm
- npx
- macos
- claude-desktop
- transport

## 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

- os: macOS
- runtime: Node.js
- constraints: GUI desktop client spawns the stdio MCP server without the login-shell PATH, Node version manager (NVM/fnm/asdf) places node outside the default PATH

## 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.

```bash
which node && which npx
```
3. Or use a wrapper script that restores PATH before exec and point command at it.

Rationale: 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.

## Sources

- modelcontextprotocol/servers issue 64: MCP Servers Don't Work with NVM (issue): https://github.com/modelcontextprotocol/servers/issues/64
- modelcontextprotocol/servers issue 64: npx-for-claude wrapper workaround (66 reactions) (issue): https://github.com/modelcontextprotocol/servers/issues/64#issuecomment-2730913259
- modelcontextprotocol/servers issue 1748: Server transport closed unexpectedly, process exiting early (write EPIPE) (issue): https://github.com/modelcontextprotocol/servers/issues/1748

## 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.