Skip to content

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

Closed
Closed
MCP servers fail to start on Windows due to missing inherited environment variables#4180
Labels
bugSomething isn't workingmcpIssues related to the use of model context protocol (MCP) serverswindows-osIssues related to Codex on Windows systems

Description

@cpjet64
cpjet64
opened on Sep 24, 2025

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.

Activity

  1. cpjet64
    added
    bugSomething isn't working
    on Sep 24, 2025
  2. gpeal
    added
    mcpIssues related to the use of model context protocol (MCP) servers
    on Sep 24, 2025

  3. cpjet64 commented on Sep 25, 2025

    @cpjet64
    cpjet64
    on Sep 25, 2025
    ContributorAuthor

    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.

  4. seratch
    added
    windows-osIssues related to Codex on Windows systems
    on Sep 25, 2025

  5. taichi commented on Oct 2, 2025

    @taichi
    taichi
    on Oct 2, 2025

    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.

  6. Leo-rq-yu commented on Oct 3, 2025

    @Leo-rq-yu
    Leo-rq-yu
    on Oct 3, 2025

    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!

  7. cpjet64 commented on Oct 4, 2025

    @cpjet64
    cpjet64
    on Oct 4, 2025
    ContributorAuthor

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

  8. Scriptwonder
    added 2 commits that reference this issue on Oct 17, 2025

    Update to support Codex CLI

    3d9860e

    Update to support Codex CLI (#325)

    4a0e633
  9. dylan-hurd-oai
    added a commit that references this issue on Oct 29, 2025

    fix(windows-path): preserve PATH order; include core env vars (#5579)

    e9135fa
  10. DioNanos
    added a commit that references this issue on Nov 10, 2025

    fix(windows-path): preserve PATH order; include core env vars (openai…

    32d266a

  11. etraut-openai commented on Nov 11, 2025

    @etraut-openai
    etraut-openai
    on Nov 11, 2025
    Contributor

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

  12. etraut-openai
    closed this as completedon Nov 11, 2025
  13. willy3087
    added a commit that references this issue on Nov 14, 2025

    fix(windows-path): preserve PATH order; include core env vars (openai…

    122a288
  14. takumi-earth
    added a commit that references this issue on Dec 2, 2025

    fix(windows-path): preserve PATH order; include core env vars (openai…

    8ec5cd8

  15. jbeckton commented on Oct 3, 2026

    @jbeckton
    jbeckton
    on Oct 3, 2026

    Github MCP does not work with Codex CLI on Windows in 2026 for this very reason. I found a fix for this. Open your terminal and type claude.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't workingmcpIssues related to the use of model context protocol (MCP) serverswindows-osIssues related to Codex on Windows systems

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions