fix: resolve Windows MCP server execution for script-based tools #3828

25621 · 2025-09-18T02:15:49Z

What?

Fixes MCP server initialization failures on Windows when using script-based tools like npx, pnpm, and yarn that rely on .cmd/.bat files rather than .exe binaries.

Fixes #2945

Why?

Windows users encounter "program not found" errors when configuring MCP servers with commands like npx in their ~/.codex/config.toml. This happens because:

Tools like npx are batch scripts (npx.cmd) on Windows, not executable binaries
Rust's std::process::Command bypasses the shell and cannot execute these scripts directly
The Windows shell normally handles this by checking PATHEXT for executable extensions

Without this fix, Windows users must specify full paths or add .cmd extensions manually, which breaks cross-platform compatibility.

How?

Added platform-specific program resolution using the which crate to find the correct executable path:

Windows: Resolves programs through PATH/PATHEXT to find .cmd/.bat scripts
Unix: Returns the program unchanged (no-op, as Unix handles scripts natively)

Changes

Added which = "6" dependency to mcp-client/Cargo.toml
Implemented program_resolver module in mcp_client.rs with platform-specific resolution
Added comprehensive tests for both Windows and Unix behavior

Testing

Added platform-specific tests to verify:

Unix systems execute scripts without extensions
Windows fails without proper extensions
Windows succeeds with explicit extensions
Cross-platform resolution enables successful execution

Tested on:

Windows 11 (NT 10.0.26100.0 x64)
PowerShell 5.1 & 7+, CMD, Git Bash
MCP servers: playwright, context7, supabase
WSL (verified no regression)

Local checks passed:

cargo test && cargo clippy --tests && cargo fmt -- --config imports_granularity=Item

Results

Before:

🖐 MCP client for `playwright` failed to start: program not found

After:

🖐 MCP client for `playwright` failed to start: request timed out

Windows users can now use simple commands like npx in their config without specifying full paths or extensions. The timeout issue is a separate concern that will be addressed in a follow-up PR.

github-actions · 2025-09-18T02:15:57Z

All contributors have signed the CLA ✍️ ✅
_{Posted by the CLA Assistant Lite bot.}

25621 · 2025-09-18T02:18:17Z

I have read the CLA Document and I hereby sign the CLA

# Preserve PATH precedence & fix Windows MCP env propagation ## Problem & intent Preserve user PATH precedence and reduce Windows setup friction for MCP servers by avoiding PATH reordering and ensuring Windows child processes receive essential env vars. - Addresses: #4180 #5225 #2945 #3245 #3385 #2892 #3310 #3457 #4370 - Supersedes: #4182, #3866, #3828 (overlapping/inferior once this merges) - Notes: #2626 / #2646 are the original PATH-mutation sources being corrected. --- ## Before / After **Before** - PATH was **prepended** with an `apply_patch` helper dir (Rust + Node wrapper), reordering tools and breaking virtualenvs/shims on macOS/Linux. - On Windows, MCP servers missed core env vars and often failed to start without explicit per-server env blocks. **After** - Helper dir is **appended** to PATH (preserves user/tool precedence). - Windows MCP child env now includes common core variables and mirrors `PATH` → `Path`, so typical CLIs/plugins work **without** per-server env blocks. --- ## Scope of change ### `codex-rs/arg0/src/lib.rs` - Append temp/helper dir to `PATH` instead of prepending. ### `codex-cli/bin/codex.js` - Mirror the same append behavior for the Node wrapper. ### `codex-rs/rmcp-client/src/utils.rs` - Expand Windows `DEFAULT_ENV_VARS` (e.g., `COMSPEC`, `SYSTEMROOT`, `PROGRAMFILES*`, `APPDATA`, etc.). - Mirror `PATH` → `Path` for Windows child processes. - Small unit test; conditional `mut` + `clippy` cleanup. --- ## Security effects No broadened privileges. Only environment propagation for well-known Windows keys on stdio MCP child processes. No sandbox policy changes and no network additions. --- ## Testing evidence **Static** - `cargo fmt` - `cargo clippy -p codex-arg0 -D warnings` → **clean** - `cargo clippy -p codex-rmcp-client -D warnings` → **clean** - `cargo test -p codex-rmcp-client` → **13 passed** **Manual** - Local verification on Windows PowerShell 5/7 and WSL (no `unused_mut` warnings on non-Windows targets). --- ## Checklist - [x] Append (not prepend) helper dir to PATH in Rust and Node wrappers - [x] Windows MCP child inherits core env vars; `PATH` mirrored to `Path` - [x] `cargo fmt` / `clippy` clean across touched crates - [x] Unit tests updated/passing where applicable - [x] Cross-platform behavior preserved (macOS/Linux PATH precedence intact)

…#5579) # Preserve PATH precedence & fix Windows MCP env propagation ## Problem & intent Preserve user PATH precedence and reduce Windows setup friction for MCP servers by avoiding PATH reordering and ensuring Windows child processes receive essential env vars. - Addresses: openai#4180 openai#5225 openai#2945 openai#3245 openai#3385 openai#2892 openai#3310 openai#3457 openai#4370 - Supersedes: openai#4182, openai#3866, openai#3828 (overlapping/inferior once this merges) - Notes: openai#2626 / openai#2646 are the original PATH-mutation sources being corrected. --- ## Before / After **Before** - PATH was **prepended** with an `apply_patch` helper dir (Rust + Node wrapper), reordering tools and breaking virtualenvs/shims on macOS/Linux. - On Windows, MCP servers missed core env vars and often failed to start without explicit per-server env blocks. **After** - Helper dir is **appended** to PATH (preserves user/tool precedence). - Windows MCP child env now includes common core variables and mirrors `PATH` → `Path`, so typical CLIs/plugins work **without** per-server env blocks. --- ## Scope of change ### `codex-rs/arg0/src/lib.rs` - Append temp/helper dir to `PATH` instead of prepending. ### `codex-cli/bin/codex.js` - Mirror the same append behavior for the Node wrapper. ### `codex-rs/rmcp-client/src/utils.rs` - Expand Windows `DEFAULT_ENV_VARS` (e.g., `COMSPEC`, `SYSTEMROOT`, `PROGRAMFILES*`, `APPDATA`, etc.). - Mirror `PATH` → `Path` for Windows child processes. - Small unit test; conditional `mut` + `clippy` cleanup. --- ## Security effects No broadened privileges. Only environment propagation for well-known Windows keys on stdio MCP child processes. No sandbox policy changes and no network additions. --- ## Testing evidence **Static** - `cargo fmt` - `cargo clippy -p codex-arg0 -D warnings` → **clean** - `cargo clippy -p codex-rmcp-client -D warnings` → **clean** - `cargo test -p codex-rmcp-client` → **13 passed** **Manual** - Local verification on Windows PowerShell 5/7 and WSL (no `unused_mut` warnings on non-Windows targets). --- ## Checklist - [x] Append (not prepend) helper dir to PATH in Rust and Node wrappers - [x] Windows MCP child inherits core env vars; `PATH` mirrored to `Path` - [x] `cargo fmt` / `clippy` clean across touched crates - [x] Unit tests updated/passing where applicable - [x] Cross-platform behavior preserved (macOS/Linux PATH precedence intact)

etraut-openai · 2025-11-07T00:11:38Z

Thanks for the contribution, and apologies for the slow response. We received a large number of PRs, and we're just now getting through the backlog.

It looks like this PR has gone stale. If this PR is still relevant, could you please resolve the merge conflicts and make sure the tests still run? Thanks!

…ed tools This ports the fix from the original PR openai#3828 to rmcp-client, which replaced mcp-client in PR openai#5529. On Windows, script-based MCP servers (e.g., npx, pnpm, yarn) that rely on .cmd or .bat files fail to execute. This happens because Rust's Command does not resolve scripts via PATHEXT like the shell does. This fix uses the which crate to resolve the full executable path (including .cmd/.bat extensions) before spawning the process, allowing these tools to run correctly. Changes: - Add which crate dependency to rmcp-client/Cargo.toml - Implement program_resolver module with platform-specific logic: * Windows: Resolves .cmd/.bat scripts using which::which_in * Unix: No-op (OS handles shebangs natively) - Modify new_stdio_client to resolve program path before Command::new - Add unit tests for program resolution on both platforms Fixes: openai#2945

25621 · 2025-11-07T15:41:56Z

Hi @etraut-openai,

Thank you for reviewing! I've resolved the conflicts and updated the PR:

✅ Rebased on latest main
✅ Applied fix to rmcp-client (which replaced mcp-client in [MCP] Remove the legacy stdio client in favor of rmcp #5529)
✅ Verified issue MCP client for playwright failed to start: program not found #2945 still reproduces on v0.55.0 and main
✅ All tests pass: cargo test -p codex-rmcp-client

The Windows script resolution logic remains unchanged - using the which crate to properly resolve .cmd/.bat scripts that Windows requires for tools like npx, pnpm, and yarn.

Ready for merge. Let me know if you need any adjustments!

etraut-openai · 2025-11-07T20:14:11Z

@25621, looks like there are some lint (cargo clippy) issues remaining.

…ed tools This ports the fix from the original PR openai#3828 to rmcp-client, which replaced mcp-client in PR openai#5529. On Windows, script-based MCP servers (e.g., npx, pnpm, yarn) that rely on .cmd or .bat files fail to execute. This happens because Rust's Command does not resolve scripts via PATHEXT like the shell does. This fix uses the which crate to resolve the full executable path (including .cmd/.bat extensions) before spawning the process, allowing these tools to run correctly. Changes: - Add which crate dependency to rmcp-client/Cargo.toml - Implement program_resolver module with platform-specific logic: * Windows: Resolves .cmd/.bat scripts using which::which_in * Unix: No-op (OS handles shebangs natively) - Modify new_stdio_client to resolve program path before Command::new - Add unit tests for program resolution on both platforms Fixes: openai#2945

github-actions bot added a commit that referenced this pull request Sep 18, 2025

@25621 has signed the CLA in #3828

ecc132a

25621 mentioned this pull request Sep 18, 2025

MCP client for playwright failed to start: program not found #2945

Open

wbdb mentioned this pull request Sep 22, 2025

Codex for Native Windows? #4063

Open

cpjet64 mentioned this pull request Oct 23, 2025

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

Merged

5 tasks

etraut-openai added the needs-response Additional information is requested label Nov 7, 2025

25621 force-pushed the fix/windows-mcp-script-resolution branch from b12b045 to 5c75710 Compare November 7, 2025 15:07

25621 force-pushed the fix/windows-mcp-script-resolution branch from 5c75710 to 74e4237 Compare November 7, 2025 15:17

25621 force-pushed the fix/windows-mcp-script-resolution branch from 74e4237 to 577b2a6 Compare November 8, 2025 01:35

Merge branch 'main' into fix/windows-mcp-script-resolution

86f67e6

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix: resolve Windows MCP server execution for script-based tools #3828

fix: resolve Windows MCP server execution for script-based tools #3828

25621 commented Sep 18, 2025

Uh oh!

github-actions bot commented Sep 18, 2025 •

edited

Loading

Uh oh!

25621 commented Sep 18, 2025

Uh oh!

etraut-openai commented Nov 7, 2025

Uh oh!

25621 commented Nov 7, 2025

Uh oh!

etraut-openai commented Nov 7, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

fix: resolve Windows MCP server execution for script-based tools #3828

Are you sure you want to change the base?

fix: resolve Windows MCP server execution for script-based tools #3828

Conversation

25621 commented Sep 18, 2025

What?

Why?

How?

Changes

Testing

Results

Uh oh!

github-actions bot commented Sep 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

25621 commented Sep 18, 2025

Uh oh!

etraut-openai commented Nov 7, 2025

Uh oh!

25621 commented Nov 7, 2025

Uh oh!

etraut-openai commented Nov 7, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

github-actions bot commented Sep 18, 2025 •

edited

Loading