# How TUUI Resolves MCP Server Spawn Errors on Windows and macOS

> Resolve MCP server spawn errors on Windows and macOS with TUUI's platform-specific strategies. Learn about SDK patches, absolute paths, and environment adjustments.

- Repository: [AIQL/tuui](https://github.com/ai-ql/tuui)
- Tags: how-to-guide
- Published: 2026-02-23

---

**TUUI mitigates MCP server spawn failures by applying platform-specific workarounds: using the official SDK's Windows patch for `ENOENT` errors while requiring absolute paths and environment adjustments on macOS.**

When integrating Model Context Protocol (MCP) servers into the TUUI application, developers frequently encounter spawn errors—particularly `ENOENT` on Windows and path-resolution failures on macOS. According to the TUUI source code, these issues stem from platform-specific quirks in how child processes resolve executables. The repository implements a bifurcated remediation strategy that leverages SDK patches for Windows while relying on manual configuration for macOS users.

## Understanding MCP Server Spawn Errors

MCP servers typically launch as child processes via `stdio` transports. When TUUI attempts to spawn these servers, the underlying Node.js `child_process` API can fail with `ENOENT` (Error NO ENTity), indicating the system cannot locate the specified executable.

In [`src/main/IPCs.ts`](https://github.com/ai-ql/tuui/blob/main/src/main/IPCs.ts) (lines 135-143), TUUI demonstrates the generic spawn pattern used for child processes. This same pattern is vulnerable to platform-specific path resolution issues when applied to MCP server binaries.

## Platform-Specific Resolution Strategies

TUUI's documentation in [`README.md`](https://github.com/ai-ql/tuui/blob/main/README.md) (lines 165-176) outlines distinct approaches for Windows and macOS environments.

### Windows: SDK Workaround and Issue 101

On Windows, the primary cause of `ENOENT` errors involves how the system resolves `npx` and other Node.js executables through the `child_process` API. The Windows path handling often fails to locate the executable when using relative paths or shell commands.

**The Fix:** TUUI relies on the official `@modelcontextprotocol/sdk` package, which bundles a dedicated workaround for this issue. The SDK patches the child-process spawning logic to correctly resolve Windows executables.

To apply this fix, ensure you have the latest SDK version installed:

```bash
npm i @modelcontextprotocol/sdk@latest

```

This automatically pulls in the resolution for **Issue 101** of the TypeScript SDK, which injects a Windows-specific shim that avoids the `ENOENT` lookup problem.

### macOS: Absolute Paths and Environment Workarounds

macOS presents different challenges, primarily involving path-resolution quirks when commands are invoked through wrapper scripts like NVM (Node Version Manager). When TUUI spawns a process through a shell that loads `.bashrc` or `.zshrc` with NVM configurations, the executable path often becomes unreachable.

**The Fix:** TUUI recommends using an **absolute path** to the MCP server binary rather than relying on shell resolution or relative paths.

In [`src/main/mcp/client.ts`](https://github.com/ai-ql/tuui/blob/main/src/main/mcp/client.ts), the implementation demonstrates this approach by resolving the executable path before creating the transport:

```typescript
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'
import { resolve } from 'path'

async function startMcpServer(serverConfig) {
  // Resolve absolute path to eliminate ENOENT risks
  const absoluteCmd = resolve(process.cwd(), serverConfig.command)

  const transport = new StdioClientTransport({
    command: absoluteCmd,  // Absolute path ensures macOS can locate the binary
    args: serverConfig.args ?? [],
    cwd: serverConfig.cwd,
    env: serverConfig.env,
    stderr: 'pipe',
  })
  
  // Client connection logic follows...
}

```

For users encountering NVM-related issues, TUUI references **Issue 2** (a community-maintained guide) which suggests disabling NVM or pre-installing the server's runtime in a global context:

```bash

# Bypass NVM which can break path resolution

export NVM_DIR=""
export PATH="/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"

# Then launch TUUI

npm run dev

```

## Generic Troubleshooting Steps

Regardless of platform, TUUI's documentation advises a universal first-step diagnostic: **manually run the MCP server** from your terminal using the intended command, then provide its absolute path to TUUI. This verifies that the binary exists and is executable before TUUI attempts to spawn it as a child process.

## Summary

- **Windows users** should update to the latest `@modelcontextprotocol/sdk` to automatically receive the Issue 101 patch that resolves `ENOENT` errors through Windows-specific path handling.
- **macOS users** must provide absolute paths to MCP server binaries in their TUUI configuration to bypass NVM and shell wrapper complications.
- **All platforms** benefit from verifying MCP server executability manually before configuring TUUI, as implemented in [`src/main/mcp/client.ts`](https://github.com/ai-ql/tuui/blob/main/src/main/mcp/client.ts) using `resolve(process.cwd(), command)`.

## Frequently Asked Questions

### Why does TUUI fail with ENOENT on Windows but not macOS?

Windows handles executable path resolution differently than Unix-based systems, particularly when spawning processes through `npx` or npm scripts. The Windows environment often fails to locate the executable in the system PATH when using relative commands, triggering `ENOENT`. TUUI relies on the MCP SDK's Windows-specific patch (Issue 101) to inject a shim that correctly resolves these paths.

### Can I use relative paths for MCP servers on macOS with TUUI?

While technically possible, TUUI explicitly recommends against using relative paths on macOS due to complications with shell wrappers like NVM. When TUUI spawns a child process, it may not inherit the same environment variables or PATH modifications that your interactive shell has. Using an absolute path, as shown in [`src/main/mcp/client.ts`](https://github.com/ai-ql/tuui/blob/main/src/main/mcp/client.ts), ensures the binary is located regardless of the spawning context.

### What is the MCP SDK Issue 101 mentioned in TUUI's documentation?

Issue 101 refers to a specific bug fix in the TypeScript Model Context Protocol SDK that addresses Windows spawn failures. The fix modifies how the SDK creates child processes on Windows, adding a shim that correctly handles executable resolution and avoids the `ENOENT` errors that occur when the system cannot find `npx` or node binaries. TUUI users on Windows should ensure they have the latest SDK version to benefit from this fix.