›_ Codex Issues
Codex Issues / #4180

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

Resolved 💬 5 comments Opened Sep 24, 2025 by cpjet64 Closed Nov 11, 2025
💡 Likely answer: A maintainer (cpjet64, contributor) responded on this thread — see the highlighted reply below.

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.

View original on GitHub ↗

5 Comments

cpjet64 contributor · 11 months ago

A temporary workaround for Windows users experiencing this issue (until the PR gets approved) is as follows:

Replace YOURUSERPROFILEGOESHERE with your actual Windows username before applying this config.

[mcp_servers.docker-mcp-gateway]
command = "docker.exe"
args = ["mcp", "gateway", "run"]
startup_timeout_ms = 10000

[mcp_servers.docker-mcp-gateway.env]
APPDATA       = "C:\\Users\\YOURUSERPROFILEGOESHERE\\AppData\\Roaming"
COMSPEC       = "C:\\Windows\\System32\\cmd.exe"
HOMEDRIVE     = "C:"
HOMEPATH      = "\\Users\\YOURUSERPROFILEGOESHERE"
LOCALAPPDATA  = "C:\\Users\\YOURUSERPROFILEGOESHERE\\AppData\\Local"
POWERSHELL    = "C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe"
PROGRAMDATA   = "C:\\ProgramData"
PROGRAMFILES  = "C:\\Program Files"
PWSH          = "C:\\Program Files\\PowerShell\\7\\pwsh.exe"
SYSTEMDRIVE   = "C:"
SYSTEMROOT    = "C:\\Windows"
TEMP          = "C:\\Users\\YOURUSERPROFILEGOESHERE\\AppData\\Local\\Temp"
TMP           = "C:\\Users\\YOURUSERPROFILEGOESHERE\\AppData\\Local\\Temp"
USERPROFILE   = "C:\\Users\\YOURUSERPROFILEGOESHERE"

Note: This workaround works as long as MCP servers already run in CMD or PowerShell.

taichi · 11 months ago

In addition to the base OS variables already covered by #4182, Windows environments that need to invoke native toolchains such as MSVC (for example, when Rust Analyzer spawns rustc with the MSVC target) require that a set of Visual Studio and Windows SDK related environment variables also be passed through.

Without these, cl.exe, link.exe, and the corresponding headers and libraries cannot be resolved, leading to failed builds inside Serena and downstream tools like Rust Analyzer.

The minimum additional variables to consider including in the whitelist are:

  • Compiler/toolchain paths

PATH, INCLUDE, LIB, LIBPATH

  • Visual Studio installation context

VSINSTALLDIR, VCINSTALLDIR, VCToolsInstallDir, VCToolsVersion, VCToolsRedistDir,
VisualStudioVersion, VS170COMNTOOLS, DevEnvDir, VCIDEInstallDir

  • Windows SDK context

WindowsSdkDir, WindowsSDKVersion, WindowsSDKLibVersion,
WindowsSdkBinPath, WindowsSdkVerBinPath, WindowsLibPath,
UCRTVersion, UniversalCRTSdkDir, ExtensionSdkDir

  • .NET references (used by MSBuild/MSVC toolchain)

FrameworkDir, FrameworkDir64, FrameworkVersion, FrameworkVersion64

  • Developer PowerShell/Command Prompt metadata

variables prefixed with VSCMD_

This list is derived from the environment produced by vcvarsall.bat / Launch-VsDevShell.ps1, and reflects the minimum set required for consistent MSVC/Windows SDK builds.
https://learn.microsoft.com/en-us/visualstudio/ide/reference/command-prompt-powershell?view=vs-2022

Adding these to the whitelist would make Codex → Serena → Rust Analyzer workflows viable without requiring ad-hoc workarounds.

Leo-rq-yu · 10 months ago

Just chiming in as an external user to confirm the impact: on Windows, this prevents certain MCP servers (e.g., Docker or npm/npx-based) from starting as expected. An upstream fix would help a lot since per-user workarounds aren’t practical. Thanks @cpjet64 and the Codex team for looking into it!

cpjet64 contributor · 10 months ago

@taichi I updated my PR to include that brilliant idea!

etraut-openai contributor · 9 months ago

The missing env variables listed above are now preserved. If you see additional missing env variables, please open a new issue.