# How to Configure MCP Servers on Windows and WSL

> Configure MCP servers on Windows and WSL to prevent stdin/stdout issues and achieve POSIX compatibility. Learn the steps to set up your MCP server efficiently.

- Repository: [Composio/awesome-codex-skills](https://github.com/composiohq/awesome-codex-skills)
- Tags: how-to-guide
- Published: 2026-04-26

---

**Run MCP servers inside Windows Subsystem for Linux (WSL) to avoid stdin/stdout connection issues and ensure POSIX compatibility.**

Model Context Protocol (MCP) servers are long-running processes that expose **tools** to LLMs. On native Windows, they frequently encounter connection problems because the SDK expects a Unix-like environment with POSIX paths and standard I/O streams. According to the `ComposioHQ/awesome-codex-skills` repository, the recommended pattern is to configure and deploy servers inside WSL while letting your Windows client communicate through the WSL network interface.

## Why Native Windows Causes MCP Failures

Native Windows environments conflict with MCP SDK assumptions in three critical ways:

- **Line-ending and buffering quirks** – The Windows console handles stdin/stdout differently than Unix terminals, causing stream corruption during tool execution.
- **Path conventions** – Python `FastMCP` and Node MCP SDKs assume Unix paths (`/tmp`, `~/.config`) that do not exist on Windows without translation.
- **Process spawning** – Client libraries like `mcp` expect POSIX process signals and file descriptors that Windows does not natively support.

## Why WSL Solves These Issues

Deploying servers inside WSL provides the Linux environment the SDKs expect while maintaining accessibility from Windows applications:

**Standard I/O handling** – WSL provides a true Linux terminal that respects byte streams and avoids Windows console buffering, ensuring reliable communication over stdio or HTTP/SSE transports.

**POSIX file layout** – WSL maps Windows drives under `/mnt/c`, making the expected layout available without code changes while allowing servers to reference `/tmp` and `~/.config` naturally.

**Network transparency** – WSL’s virtual Ethernet adapter assigns `127.0.0.1` to the server, which the host Windows client can reach using `http://localhost:XXXX` or direct process spawning.

The repository specifically documents this approach in [`linear/SKILL.md`](https://github.com/ComposioHQ/awesome-codex-skills/blob/main/linear/SKILL.md) for the Linear MCP server, noting that the same technique applies to any Python or Node implementation built with the official SDKs.

## Step-by-Step WSL Configuration

### 1. Install WSL and Your Distribution

Install Windows Subsystem for Linux and a Linux distribution (Ubuntu recommended) via the Microsoft Store or `wsl --install`. Verify installation with `wsl -l -v`.

### 2. Prepare the Server Environment

Inside the WSL terminal, navigate to your project using the mounted Windows path:

```bash
cd /mnt/c/Path/To/your/repo/mcp-builder

```

Create an isolated environment specific to your SDK:

- **Python**: `python -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt`
- **Node**: `npm install && npx tsc`

### 3. Launch and Expose the Server

Start the server using the SDK entry point, ensuring it binds to the WSL network interface:

- **stdio transport** – The client spawns the server process directly; no network configuration required.
- **HTTP/SSE transport** – Bind to `0.0.0.0` or `127.0.0.1` and note the port for Windows client configuration.

Configure your Instagit workflow or client JSON to point at `http://localhost:8000/mcp` (adjusting for your specific port).

## Code Examples for WSL Deployment

### Python FastMCP Server in WSL

Create and run a Python MCP server inside WSL that exposes an HTTP endpoint accessible from Windows:

```bash

# Inside WSL terminal

cd /mnt/c/Path/To/your/repo/mcp-builder
source .venv/bin/activate

cat > example_mcp.py <<'EOF'
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("example_mcp")

@mcp.tool
def echo(message: str) -> str:
    """Return the received message."""
    return message

if __name__ == "__main__":
    mcp.serve(host="0.0.0.0", port=8000)   # HTTP transport

EOF

python example_mcp.py

```

Configure your Windows client to connect:

```json
{
  "mcpServers": [
    {
      "name": "example_mcp",
      "url": "http://localhost:8000/mcp"
    }
  ]
}

```

### Node.js TypeScript MCP Server in WSL

Deploy a TypeScript server using the MCP SDK inside WSL:

```bash

# Inside WSL terminal

cd /mnt/c/Path/To/your/repo/mcp-builder
npm install
npx tsc

cat > src/example_mcp.ts <<'EOF'
import { FastMCP } from "mcp-sdk";

const mcp = new FastMCP("example_mcp");

mcp.tool({
  name: "add",
  description: "Add two numbers",
  input_schema: {
    type: "object",
    properties: {
      a: { type: "number" },
      b: { type: "number" }
    },
    required: ["a", "b"]
  },
  func: ({ a, b }: { a: number; b: number }) => {
    return a + b;
  }
});

mcp.serve({ host: "0.0.0.0", port: 8080 });
EOF

npm run build
node dist/example_mcp.js

```

### Running the Linear MCP Server from Windows

Launch the Linear MCP server from a Windows PowerShell prompt while executing inside WSL:

```powershell
wsl -e bash -c "cd /mnt/c/Path/To/awesome-codex-skills/linear && python linear_mcp.py"

```

This command instantiates the server in the Linux environment while your Instagit workflow on Windows invokes Linear tools without encountering platform-specific errors.

## Key Source Files and References

The `ComposioHQ/awesome-codex-skills` repository contains specific documentation supporting this configuration:

- **[`linear/SKILL.md`](https://github.com/ComposioHQ/awesome-codex-skills/blob/main/linear/SKILL.md)** – Documents the Windows/WSL note for the Linear MCP server implementation.
- **[`mcp-builder/reference/python_mcp_server.md`](https://github.com/ComposioHQ/awesome-codex-skills/blob/main/mcp-builder/reference/python_mcp_server.md)** – Complete guide for building Python MCP servers with `FastMCP`.
- **[`mcp-builder/reference/node_mcp_server.md`](https://github.com/ComposioHQ/awesome-codex-skills/blob/main/mcp-builder/reference/node_mcp_server.md)** – Reference for Node/TypeScript MCP server construction.
- **[`mcp-builder/reference/mcp_best_practices.md`](https://github.com/ComposioHQ/awesome-codex-skills/blob/main/mcp-builder/reference/mcp_best_practices.md)** – Platform-agnostic checklist for reliable server deployment.
- **[`mcp-builder/scripts/evaluation.py`](https://github.com/ComposioHQ/awesome-codex-skills/blob/main/mcp-builder/scripts/evaluation.py)** – Test harness for validating server connectivity, useful for verifying WSL network configuration.

## Summary

- **Run MCP servers in WSL** to avoid Windows-specific POSIX and stdio compatibility issues.
- **Use `/mnt/c` paths** to access Windows repositories from inside WSL without file synchronization.
- **Bind to `0.0.0.0`** for HTTP transports to ensure Windows clients can reach the server via `localhost`.
- **Reference [`linear/SKILL.md`](https://github.com/ComposioHQ/awesome-codex-skills/blob/main/linear/SKILL.md)** for the canonical example of this pattern in the repository.
- **Test with [`evaluation.py`](https://github.com/ComposioHQ/awesome-codex-skills/blob/main/evaluation.py)** to confirm connectivity before integrating with production workflows.

## Frequently Asked Questions

### Can I run MCP servers natively on Windows without WSL?

Running natively is possible but not recommended. The Python `FastMCP` and Node MCP SDKs assume Unix-like stdin/stdout handling and POSIX file paths that cause intermittent connection failures and path resolution errors on Windows. WSL eliminates these variables by providing a genuine Linux execution environment.

### How do I access WSL files from my Windows MCP client?

Windows accesses WSL files through the `\\wsl$\` UNC path or by referencing the mounted drive locations inside WSL (e.g., `/mnt/c/Users/username/project`). For client configuration, you typically do not need direct file access; instead, you connect via `localhost` networking or allow the client library to spawn the WSL process using `wsl -e` commands.

### What transport method should I use for WSL deployment?

Choose **stdio** transport when the client library supports spawning the WSL process directly, as this avoids port management entirely. Choose **HTTP/SSE** transport when you need persistent connections or when using external clients that cannot spawn processes, ensuring the server binds to `0.0.0.0` inside WSL to accept connections from the Windows host.

### Where can I find the Linear MCP server example mentioned in the documentation?

The Linear implementation reference resides in [`linear/SKILL.md`](https://github.com/ComposioHQ/awesome-codex-skills/blob/main/linear/SKILL.md) within the `ComposioHQ/awesome-codex-skills` repository. This file documents the specific Windows/WSL workaround and provides the template for running [`linear_mcp.py`](https://github.com/ComposioHQ/awesome-codex-skills/blob/main/linear_mcp.py) from both native Windows prompts and inside WSL terminals.