[FEATURE] Add cross-platform uvx command support to StdioServerParameters

[DennisTraub]

Problem Statement

Issue

Current behavior: StdioServerParameters requires users to manually handle platform-specific uvx command syntax, leading to Windows compatibility issues and a poor developer experience.

Expected behavior: StdioServerParameters should automatically handle cross-platform uvx commands, allowing the same code to work on Windows, macOS, and Linux.

Root Cause

The uvx package manager uses different command syntax across platforms:

macOS/Linux:

uvx package-name@version

Windows:

uvx --from package-name@version package-name.exe

This forces users to write platform-specific code or encounter runtime errors like MCPClientInitializationError: background thread did not start in 30 seconds on Windows.

Current Workaround

Users must implement platform detection manually:

import platform
from mcp import stdio_client, StdioServerParameters

def get_platform_args(base_args):
    """Convert base uvx args to platform-specific format"""
    if platform.system() == "Windows":
        package_name = base_args[0].split("@")[0]
        return ["--from"] + base_args + [f"{package_name}.exe"]
    return base_args

# Platform-aware usage
stdio_mcp_client = MCPClient(lambda: stdio_client(
    StdioServerParameters(
        command="uvx", 
        args=get_platform_args(["awslabs.aws-documentation-mcp-server@latest"])
    )
))

Proposed Solution

Enhance StdioServerParameters to automatically detect and transform uvx commands based on the current platform:

Implementation Approach

1. Detect uvx commands - Check if command="uvx"
2. Platform detection - Use platform.system() to identify Windows vs Unix-like systems
3. Automatic transformation - Convert arguments for Windows compatibility when needed
4. Backward compatibility - Preserve existing behavior for non-uvx commands

Example API

# This should work identically on all platforms:
StdioServerParameters(
    command="uvx", 
    args=["awslabs.aws-documentation-mcp-server@latest"]
)

# Internally transforms to Windows format when on Windows:
# args=["--from", "awslabs.aws-documentation-mcp-server@latest", "awslabs.aws-documentation-mcp-server.exe"]

Benefits

• Better developer experience - Write once, run anywhere
• Reduced support burden - Eliminate platform-specific documentation and troubleshooting
• Lower barrier to entry - New users don't need to understand platform differences
• Backward compatibility - Existing code continues to work unchanged

Related Issues

#71

This enhancement addresses user-reported, internally reproducible compatibility issues where Windows users encounter MCPClientInitializationError when following cross-platform documentation examples.

Use Case

As a developer building applications with Strands Agents
I want to use MCP stdio connections with uvx commands that work across all platforms
So that I can write portable code without needing to handle platform-specific command syntax

Current User Journey (Problematic)

1. Developer follows documentation example using uvx command
2. Code works fine on macOS/Linux during development
3. When deployed/tested on Windows, encounters MCPClientInitializationError: background thread did not start in 30 seconds
4. Developer must research the issue, discover platform differences, and implement custom platform detection
5. Developer maintains separate code paths or conditional logic for different platforms

Desired User Journey

1. Developer follows documentation example using uvx command
2. Same code works seamlessly on Windows, macOS, and Linux
3. No platform-specific considerations needed
4. Focus remains on business logic rather than infrastructure compatibility

umentation examples.

Alternatives Solutions

No response

Additional Context

As a preliminary workaround, we've updated the documentation to include clear platform-specific examples for Windows and macOS/Linux users. This change was merged in strands-agents/docs#47 and provides immediate relief for users encountering this issue.
Current documentation workaround:

• Shows separate Windows and macOS/Linux examples with correct uvx syntax
• Provides copy-paste ready solutions for both platforms

While this documentation fix helps users get unblocked immediately, the underlying framework enhancement is still needed to provide a seamless developer experience without requiring platform-specific code or awareness.

Links:

• Documentation fix PR: Add Windows compatibility guidance for MCP stdio connections docs#47
• Original user report: Exception has occurred: MCPClientInitializationError #71

[dbschmigelski]

Hi, thanks for raising this. I have some concerns with adding this automatic transformation, though.

For example, when should we decide to perform this transformation? Is it anytime we see see uvx? What if the users already has ["--from package-name@version package-name.exe"] or ["--from", "package-name@version", "package-name.exe"] provided?

My fear is that performing this transformation on behalf of customers, will lead to unexpected failures when they progress to more complex scenarios.

To me, this seems like an issue that can and should be solved via two paths.

1. We track and contribute to cross-platform support in MCP. This allows us to maintain usage of the Transport abstraction - StdioServerParameters is not defined by strands but is instead an implementation of a Transport that MCPClient accepts.
2. We maintain accurate platform-aware documentation so customers are less likely to encounter this issue while following our guides. Thank you for Add Windows compatibility guidance for MCP stdio connections docs#47

Please let me know if these align with your expectations, thanks!

[dbschmigelski]

Regarding path #1, it appears an attempt has already been made to address the windows compatibility issues. This was initially deployed in version 1.6.0 which is lower than Strands' min version of 1.8.0 for MCP.

The PR states "This change should fix most cases of modelcontextprotocol/python-sdk#359, with issues spawning stdio MCP servers on Windows.", so we need to understand why the fix is incomplete.

[dbschmigelski]

Hi, @DennisTraub thanks for raising this. I know it has been a long time. Like I mentioned above it seems there are efforts in the MCP sdk to address platform issues. Because of this, we are going to close this PR out.

Thanks for raising this and the other issues/contributions as well!