mcp-streamablehttp-proxy

A generic stdio-to-StreamableHTTP bridge for MCP (Model Context Protocol) servers. This proxy enables any stdio-based MCP server to be accessed via HTTP endpoints, making them compatible with web-based clients and HTTP infrastructure like API gateways.

Overview

The mcp-streamablehttp-proxy acts as a translation layer between:

• MCP clients that speak StreamableHTTP (like Claude.ai, web-based IDEs)
• MCP servers that only speak stdio JSON-RPC (like the official MCP servers)

It manages sessions, spawns server subprocesses, and handles the protocol translation transparently.

Features

• Universal MCP Server Support - Works with any stdio-based MCP server
• Session Management - Each client gets an isolated server subprocess
• Full Protocol Support - Handles the complete MCP lifecycle
• Configurable - Flexible timeout, host, and port configuration
• Production Ready - Async implementation with proper cleanup
• Gateway Compatible - Designed for use with Traefik and OAuth gateways

Installation

Via pip

pip install mcp-streamablehttp-proxy

Via pixi

pixi add --pypi mcp-streamablehttp-proxy

Usage

Basic Usage

# Proxy a Python MCP server module
mcp-streamablehttp-proxy python -m mcp_server_fetch

# Proxy an executable MCP server
mcp-streamablehttp-proxy /usr/local/bin/mcp-server-filesystem --root /data

# Proxy an npm-based MCP server
mcp-streamablehttp-proxy npx @modelcontextprotocol/server-memory

Command Line Options

mcp-streamablehttp-proxy [OPTIONS]  [server_args...]

Options:
  --host TEXT         Host to bind to (default: 127.0.0.1)
  --port INTEGER      Port to bind to (default: 3000)
  --timeout INTEGER   Session timeout in seconds (default: 300)
  --log-level TEXT    Log level: debug/info/warning/error (default: info)
  --help             Show this message and exit

Environment Variables

• MCP_BIND_HOST - Override default bind host
• MCP_PORT - Override default port
• LOG_FILE - Enable file logging to specified path

How It Works

1. Client sends HTTP request to /mcp endpoint
2. Proxy creates session on first initialize request
3. Proxy spawns subprocess running the specified MCP server
4. Proxy translates between HTTP and stdio protocols
5. Client includes session ID in subsequent requests
6. Sessions timeout after period of inactivity

API

Endpoint

• POST /mcp - Single endpoint for all MCP protocol messages

Headers

• Mcp-Session-Id - Required for all requests after initialization
• Content-Type - Must be application/json

Request Format

Standard JSON-RPC 2.0 messages:

{
  "jsonrpc": "2.0",
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {
      "name": "example-client",
      "version": "1.0.0"
    }
  },
  "id": 1
}