[DOCS] Inconsistent Windows `npx` wrapper requirements in MCP and Agent SDK examples

Documentation Type

Unclear/confusing documentation

Documentation Location

• https://code.claude.com/docs/en/mcp - https://platform.claude.com/docs/en/agent-sdk/overview - https://platform.claude.com/docs/en/agent-sdk/mcp

Section/Topic

MCP server configuration examples, specifically those involving npx on native Windows environments.

Current Documentation

The file docs/en/mcp.md contains a specific warning:

"Windows Users: On native Windows (not WSL), local MCP servers that use npx require the cmd /c wrapper to ensure proper execution. claude mcp add --transport stdio my-server -- cmd /c npx -y @some/package"

However, the Agent SDK documentation (e.g., docs/en/agent-sdk/overview.md) shows snippets like this without any Windows-specific caveat:

mcp_servers={
    "playwright": {"command": "npx", "args": ["@playwright/mcp@latest"]}
}

What's Wrong or Missing?

The critical requirement to use cmd /c for npx on native Windows is only mentioned in the CLI-specific MCP documentation. It is missing from:

1. The Agent SDK Overview, where users are likely to copy-paste their first MCP connection code.
2. The Agent SDK MCP guide.
3. The Quickstart guides.

A user on native Windows following the SDK documentation will encounter "Connection closed" errors because Windows cannot execute npx directly as a process without the shell wrapper.

Suggested Improvement

Every code example that uses npx as a command for an MCP server should either:

• Include a tabbed code block for Windows vs. POSIX.
• Include a standardized footnote warning about the cmd /c requirement for native Windows.

Suggested Footnote/Note Text:

Note for Native Windows Users: If you are using Cmd or PowerShell (not WSL), you must wrap npx commands. Set the command to "cmd" and add "/c", "npx" to the start of your arguments list.

Example of corrected SDK snippet:

# For macOS/Linux/WSL
"playwright": {"command": "npx", "args": ["@playwright/mcp@latest"]}

# For Native Windows
"playwright": {"command": "cmd", "args": ["/c", "npx", "-y", "@playwright/mcp@latest"]}

Impact

High - Prevents users from using a feature

Additional Context

• This issue is particularly high-friction for new users because the resulting error message ("Connection closed") is generic and does not explicitly point to a shell execution failure.
• Related documentation link: Claude Code MCP - Installing MCP Servers (where the warning currently exists but is easily missed by SDK users).