
Security News
Meet Socket at Black Hat and DEF CON 2025 in Las Vegas
Meet Socket at Black Hat & DEF CON 2025 for 1:1s, insider security talks at Allegiant Stadium, and a private dinner with top minds in software supply chain security.
mcp-streamablehttp-proxy
Advanced tools
A generic stdio-to-streamable-HTTP proxy for MCP (Model Context Protocol) servers
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.
The mcp-streamablehttp-proxy
acts as a translation layer between:
It manages sessions, spawns server subprocesses, and handles the protocol translation transparently.
pip install mcp-streamablehttp-proxy
pixi add --pypi mcp-streamablehttp-proxy
# 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
mcp-streamablehttp-proxy [OPTIONS] <server_command> [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
MCP_BIND_HOST
- Override default bind hostMCP_PORT
- Override default portLOG_FILE
- Enable file logging to specified path/mcp
endpointinitialize
requestapplication/json
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
}
JSON-RPC 2.0 responses with session ID header:
{
"jsonrpc": "2.0",
"result": {
"protocolVersion": "2024-11-05",
"capabilities": {},
"serverInfo": {
"name": "example-server",
"version": "1.0.0"
}
},
"id": 1
}
Response includes header: Mcp-Session-Id: <uuid>
# Start the proxy
mcp-streamablehttp-proxy python -m mcp_server_fetch
# Initialize session
SESSION_ID=$(curl -s -X POST http://localhost:3000/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05"},"id":1}' \
-i | grep -i mcp-session-id | cut -d' ' -f2 | tr -d '\r')
# List available tools
curl -X POST http://localhost:3000/mcp \
-H "Content-Type: application/json" \
-H "Mcp-Session-Id: $SESSION_ID" \
-d '{"jsonrpc":"2.0","method":"tools/list","id":2}'
FROM python:3.11-slim
RUN pip install mcp-streamablehttp-proxy mcp-server-fetch
# Bind to 0.0.0.0 for container networking
CMD ["mcp-streamablehttp-proxy", "--host", "0.0.0.0", "python", "-m", "mcp_server_fetch"]
services:
mcp-fetch:
build: .
environment:
- MCP_BIND_HOST=0.0.0.0
- MCP_PORT=3000
labels:
- "traefik.enable=true"
- "traefik.http.routers.mcp-fetch.rule=Host(`mcp-fetch.example.com`)"
- "traefik.http.services.mcp-fetch.loadbalancer.server.port=3000"
- "traefik.http.routers.mcp-fetch.middlewares=mcp-auth"
- "traefik.http.middlewares.mcp-auth.forwardauth.address=http://auth:8000/verify"
initialize
requestError | Cause | Solution |
---|---|---|
Session not found | Invalid or expired session ID | Initialize new session |
Request timeout | Server took >30s to respond | Check server health |
Subprocess died | Server crashed | Check server logs |
Invalid request | Malformed JSON-RPC | Verify request format |
Enable debug logging:
mcp-streamablehttp-proxy --log-level debug python -m mcp_server_fetch
# Or with file logging
export LOG_FILE=/tmp/mcp-proxy.log
mcp-streamablehttp-proxy --log-level debug python -m mcp_server_fetch
For high-load scenarios, consider:
â ď¸ This proxy provides NO authentication or authorization!
Always deploy behind an authenticating reverse proxy like Traefik with:
Never expose the proxy directly to the internet!
This proxy is designed to work seamlessly with the MCP OAuth Gateway:
# Install dev dependencies
pip install -e ".[dev]"
# Run tests
pytest tests/
# Run with coverage
pytest --cov=mcp_streamablehttp_proxy tests/
mypy src/
ruff check src/
ruff format src/
--timeout
optionContributions are welcome! Please:
This project is licensed under the MIT License - see the LICENSE file for details.
FAQs
A generic stdio-to-streamable-HTTP proxy for MCP (Model Context Protocol) servers
We found that mcp-streamablehttp-proxy demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Meet Socket at Black Hat & DEF CON 2025 for 1:1s, insider security talks at Allegiant Stadium, and a private dinner with top minds in software supply chain security.
Security News
CAI is a new open source AI framework that automates penetration testing tasks like scanning and exploitation up to 3,600Ă faster than humans.
Security News
Deno 2.4 brings back bundling, improves dependency updates and telemetry, and makes the runtime more practical for real-world JavaScript projects.