Skip to content

MCP servers fail to start on Windows due to missing inherited environment variables #4180

@cpjet64

Description

@cpjet64

What version of Codex is running?

codex-cli 0.41.0

Which model were you using?

all models

What platform is your computer?

Microsoft Windows NT 10.0.26100.0 x64

What steps can reproduce the bug?

  1. On Windows, configure an MCP server that shells out to another CLI (e.g., Docker MCP Gateway in ~/.codex/config.toml with command = "docker.exe" and args ["mcp", "gateway", "run"]).
  2. Launch Codex CLI/TUI.
  3. Observe that the MCP server exits immediately. Docker reports the CLI plugin is missing; npm/npx-based servers such as npx @playwright/mcp@latest time out while a “request timed out” error is surfaced in Codex.
  4. Inspect the child process environment (or run the command manually with the same environment) and note that core variables like COMSPEC, SYSTEMROOT, PROGRAMDATA, LOCALAPPDATA, APPDATA, USERPROFILE, etc., are absent.

What is the expected behavior?

Codex should launch MCP servers with the full Windows shell environment (or at least the core variables listed above) so that CLI helpers, DNS resolution, and per-user caches work exactly as they do when the command is executed in PowerShell/CMD. Docker’s docker mcp … plugin and npx-based servers should start successfully without user-specific environment overrides.

What do you see instead?

Only PATH, PATHEXT, USERNAME, USERDOMAIN, USERPROFILE, TEMP, and TMP are preserved. Without COMSPEC the Docker CLI can’t find its plugin binary; without SYSTEMROOT DNS lookups fail (EAI_FAIL); without APPDATA npm/npx can’t locate their cache/config and exit with ENOENT. Codex reports these MCP servers as failed or timed out on start.

Additional information

A simple fix is to expand the Windows DEFAULT_ENV_VARS array in codex-rs/mcp-client/src/mcp_client.rs to include the missing core variables (COMSPEC, SYSTEMROOT, SYSTEMDRIVE, PROGRAMFILES, PROGRAMFILES(X86), PROGRAMDATA, LOCALAPPDATA, APPDATA, USERPROFILE, HOMEDRIVE, HOMEPATH, etc.) and add Windows-specific tests that assert create_env_for_mcp_server propagates each entry. I’ve prepared a branch (fix/windows-compat) that does this and verified it with the Docker gateway and npm-based MCP servers.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions