Overview

This adapter bridges STDIO-only model clients and Streamable HTTP MCP (Model Context Protocol) servers. Many lightweight clients (CLI tools, legacy integrations, or language-specific model wrappers) communicate over standard input/output. Modern MCP servers often expose a streamable HTTP endpoint that accepts chunked streaming requests and produces chunked responses. The adapter lets you run a small process that translates between STDIO and a stream-capable HTTP MCP server, so the server can be used by clients that only know how to read/write STDIO.

Why this is useful: it avoids rewriting existing STDIO clients to speak HTTP, and it enables local or remote MCP servers to be used as drop-in replacements for STDIO-based model backends. The adapter is intentionally lightweight and designed for development, automation, and production proxying scenarios where a simple bridge is preferable to embedding network code into the client.

Features

Translates newline-delimited JSON (NDJSON) or line-based STDIO messages into a single streamable HTTP request
Forward server stream responses back to stdout as they arrive (preserving chunked/line semantics)
Support for authorization headers and custom HTTP headers
Configurable target URL, local listen port, timeouts, and reconnection behavior
Small footprint — intended to be used as a simple wrapper in pipes, scripts, or containers
Basic logging and error forwarding to stderr for debugging

Installation / Configuration

Clone the repository and install dependencies (example uses Python tooling; replace with your environment if different):

git clone https://github.com/pyroprompts/mcp-stdio-to-streamable-http-adapter.git
cd mcp-stdio-to-streamable-http-adapter

# Create a virtual environment and install (Python example)
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# Or install editable package if available
pip install -e .

Basic CLI usage (example flags — check the repository README for exact flag names if you need implementation-specific flags):

# Forward local STDIO to a remote MCP stream endpoint
./mcp_stdio_adapter \
  --target-url "https://mcp.example.com/v1/stream" \
  --auth "Bearer YOUR_API_KEY" \
  --stdio

Common environment variables and options you may see in implementations:

TARGET_URL or –target-url: Remote MCP stream endpoint
PORT or –port: Local port to expose a small HTTP proxy (optional)
AUTH or –auth-header: Authorization header to include
TIMEOUT: Request/idle timeout in seconds
LOG_LEVEL: debug/info/warn

Example Dockerfile snippet for containerized usage:

FROM python:3.11-slim
WORKDIR /app
COPY . /app
RUN pip install -r requirements.txt

CMD ["python", "mcp_stdio_adapter.py", "--target-url", "https://mcp.example.com/v1/stream"]

Available Resources

GitHub repository: https://github.com/pyroprompts/mcp-stdio-to-streamable-http-adapter
MCP (Model Context Protocol) specification: https://mcp.dev (reference to the official spec and streaming semantics)
Example server clients and test harnesses (look in the repo’s examples/ or tests/ directory for ready-made demonstrations)

Behavior and Protocol Mapping

STDIO input: adapter expects newline-delimited JSON messages (NDJSON) or full JSON messages terminated by newline. Each message becomes a chunk (or part) of the outbound HTTP stream.
HTTP outbound: adapter opens a single chunked POST/PUT request to the MCP stream endpoint and forwards STDIO messages as chunks. Required headers (Content-Type: application/mcp-stream or application/json) are included.
Responses: server-sent chunks or event-stream data are read by the adapter and written to stdout immediately. Any non-streaming or final JSON response is also forwarded.
Error handling: HTTP errors and network failures are reported to stderr. The adapter can be configured to retry or exit on error.

Use Cases

Use a legacy CLI model client with a modern remote MCP server:
- You have a tool that writes prompts to stdout and expects model output on stdin/stderr. Run the adapter as a wrapper so the existing tool can communicate with a remote MCP server without code changes.
Local development and testing:
- Run a local STDIO-based test harness while pointing to a staging MCP server. The adapter lets you switch servers by changing a URL or env var instead of changing client code.
CI or batch processing:
- In CI pipelines where scripts produce prompt payloads on stdout, pipe those into the adapter so the pipeline can obtain streamed model responses and assert on partial outputs.
Containerized microservices:
- Package a small STDIO-only model component together with the adapter to expose an HTTP-friendly façade that other services can connect to, while keeping the original STDIO logic unchanged.

Example: Quick test with NDJSON

Write two lines of JSON prompts into the adapter and see streamed responses:

# Example: write messages into adapter's stdin
cat <<EOF | ./mcp_stdio_adapter --target-url "https://mcp.example.com/v1/stream" --auth "Bearer $KEY"
{"type":"input","text":"Hello"}
{"type":"input","text":"Continue"}
EOF

The adapter will open a stream to the target URL, send each JSON line as a chunk, and relay server chunks back to stdout.

Troubleshooting

If the adapter exits immediately, check stderr for HTTP status codes or connection errors.
Enable debug

STDIO to Streamable HTTP Adapter for MCP Server