mcp-stdio

Stdio-to-HTTP relay for MCP servers — bridges Claude Desktop/Code to remote Streamable HTTP endpoints.

Why?

MCP clients like Claude Desktop and Claude Code see mcp-stdio as a locally running self-hosted MCP server, while it relays all requests to a remote MCP server over Streamable HTTP:

graph LR
    A[Claude Desktop / Code] -- stdio --> B[mcp-stdio]
    B -- HTTPS --> C[Remote MCP Server]

It also works around known issues with HTTP transport in Claude Code (#28293) where custom headers are not forwarded on tool calls.

Install

pip install mcp-stdio

Or with uv:

uv tool install mcp-stdio

Or run directly without installing:

uvx mcp-stdio https://your-server.example.com:8080/mcp

Quick Start

mcp-stdio https://your-server.example.com:8080/mcp

With Bearer token authentication:

mcp-stdio https://your-server.example.com:8080/mcp --bearer-token YOUR_TOKEN

With custom headers:

mcp-stdio https://your-server.example.com:8080/mcp -H "X-API-Key: YOUR_KEY"

Claude Desktop Configuration

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "my-remote-server": {
      "command": "mcp-stdio",
      "args": [
        "https://your-server.example.com:8080/mcp",
        "--bearer-token", "YOUR_TOKEN"
      ]
    }
  }
}

Config file locations:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Claude Code Configuration

claude mcp add my-remote-server -- \
  mcp-stdio https://your-server.example.com:8080/mcp \
  --bearer-token YOUR_TOKEN

Usage

mcp-stdio [OPTIONS] URL

Arguments:
  URL                    Remote MCP server URL

Options:
  --bearer-token TOKEN   Bearer token (or set MCP_BEARER_TOKEN env var)
  -H 'Key: Value'        Custom header (can be repeated)
  --timeout-connect SEC  Connection timeout (default: 10)
  --timeout-read SEC     Read timeout (default: 120)
  -V, --version          Show version
  -h, --help             Show help

Features

Retry with backoff — retries up to 3 times on connection errors
Session recovery — resets MCP session ID on 404 and retries
Bearer token auth — via --bearer-token flag or MCP_BEARER_TOKEN env var
Custom headers — pass any header with -H (workaround for #28293)
Graceful shutdown — handles SIGTERM/SIGINT
Minimal dependencies — only httpx

How It Works

Reads JSON-RPC messages from stdin (sent by Claude Desktop/Code)
Forwards each message as HTTP POST to the remote MCP server
Parses the response (JSON or SSE) and writes it to stdout
Maintains the Mcp-Session-Id header across requests

License

MIT

MCP Stdio

Quick Install