Issue Station
Sign In
Tools hereToolbox

claude-code - 💡(How to fix) Fix [DOCS] MCP docs still describe `cmd /c` as a Windows config requirement [1 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
anthropics/claude-code#52630•Fetched 2026-04-24 06:01:59
View on GitHub
Comments
0
Participants
1
Timeline
4
Reactions
0
Author
coygeekcoygeek
Participants
coygeekcoygeek
Timeline (top)
labeled ×4

Root Cause

Windows Users: On native Windows (not WSL), local MCP servers that use npx require the cmd /c wrapper to ensure proper execution.

# This creates command="cmd" which Windows can execute
claude mcp add --transport stdio my-server -- cmd /c npx -y @some/package

Without the cmd /c wrapper, you'll encounter "Connection closed" errors because Windows cannot directly execute npx.

Code Example

> # This creates command="cmd" which Windows can execute
> claude mcp add --transport stdio my-server -- cmd /c npx -y @some/package
>
RAW_BUFFERClick to expand / collapse

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/mcp

Section/Topic

Option 3: Add a local stdio server / native Windows cmd /c warning for MCP configuration

Current Documentation

The docs currently say:

Windows Users: On native Windows (not WSL), local MCP servers that use npx require the cmd /c wrapper to ensure proper execution.

# This creates command="cmd" which Windows can execute
claude mcp add --transport stdio my-server -- cmd /c npx -y @some/package

Without the cmd /c wrapper, you'll encounter "Connection closed" errors because Windows cannot directly execute npx.

Later on the same page, the config/policy examples use plain npx command arrays:

{ "serverCommand": ["npx", "-y", "@modelcontextprotocol/server-filesystem"] },

* Example: ["npx", "-y", "server"] will NOT match ["npx", "server"] or ["npx", "-y", "server", "--flag"]

What's Wrong or Missing?

Changelog v2.1.119 says: Windows: removed false-positive Windows requires cmd /c wrapper MCP config warning.

The current MCP page still presents cmd /c as a blanket Windows requirement. That is outdated for at least some MCP configuration flows, and it leaves Windows users unsure how native Windows configs should actually be written.

This is especially confusing because the same page also documents .mcp.json/policy command arrays using bare npx entries. After v2.1.119, the docs should no longer imply that every Windows MCP config needs a cmd /c wrapper.

Suggested Improvement

Update https://code.claude.com/docs/en/mcp to reflect the v2.1.119 behavior change:

  • Remove or rewrite the blanket warning that says native Windows MCP configs require cmd /c.
  • Clarify which cases, if any, still need a wrapper versus which config forms should use plain command/arg arrays.
  • Add one explicit Windows example for persisted MCP configuration (.mcp.json, claude mcp add-json, or allowedMcpServers.serverCommand) so users know the correct representation.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

PageContext
https://code.claude.com/docs/en/mcpNative Windows warning still says npx servers require cmd /c, while the same page also documents bare npx command arrays for MCP config and policy matching

Total scope: 1 page affected

Source: Changelog v2.1.119

Exact changelog entry: Windows: removed false-positive Windows requires cmd /c wrapper MCP config warning

extent analysis

TL;DR

Update the MCP documentation to reflect the removal of the cmd /c wrapper requirement for native Windows configurations.

Guidance

  • Review the changelog entry for v2.1.119 to understand the behavior change.
  • Remove or rewrite the blanket warning on the MCP documentation page that implies every Windows MCP config needs a cmd /c wrapper.
  • Add explicit Windows examples for persisted MCP configuration to clarify the correct representation.
  • Verify the updated documentation by checking for consistency in the usage of npx commands and command arrays.

Example

No code snippet is provided as the issue is related to documentation updates.

Notes

The documentation update should ensure that users are not confused about the usage of cmd /c wrappers in Windows MCP configurations. The changelog entry provides clear information about the behavior change, and the documentation should be updated to reflect this.

Recommendation

Apply workaround: Update the documentation to reflect the correct usage of npx commands and command arrays for Windows MCP configurations, as the cmd /c wrapper is no longer required.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#prompt formatting#chain error#conversation history#tool integration#LLM response

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING

claude-code - 💡(How to fix) Fix [DOCS] MCP docs still describe `cmd /c` as a Windows config requirement [1 participants]