MCP Server Proxy for SSE and stdio

Overview

MCP Server Proxy for SSE and stdio is a lightweight proxy that makes it easy to stream Model Context Protocol (MCP) events over Server-Sent Events (SSE) or to expose a local process’s stdio as an SSE endpoint. It provides a minimal translation layer so clients that expect SSE can talk to an MCP server, and so local tooling that produces streaming output on stdout/stderr can be published as an SSE stream for browsers or other SSE-aware clients.

This tool is useful when you need simple interoperability between streaming model servers and web clients or CLI tooling. Instead of rewriting clients or embedding complicated adapters, the proxy lets you present a stable SSE endpoint, forward events to/from an MCP server, and quickly test or integrate streaming behavior with curl, browsers, or other services.

Features

• Forward MCP SSE streams to HTTP clients with minimal overhead
• Expose a local process’s stdout/stderr as an SSE endpoint
• Single binary / Docker-friendly deployment for quick integration
• Configurable listen address, upstream target, and CORS settings
• Graceful shutdown and simple logging for troubleshooting
• Works with standard SSE clients (EventSource, fetch with ReadableStream, curl -N)

Installation / Configuration

Clone the repository and run the proxy (example assumes a hosted binary or source build).

Clone the repo:

git clone https://github.com/sparfenyuk/mcp-proxy.git
cd mcp-proxy

If a prebuilt binary is included or released, download and run:

# run the proxy binary on port 8080
./mcp-proxy --listen :8080 --target https://mcp-server.example/sse

Run with Docker (replace image tag if available):

docker run -p 8080:8080 \
  -e TARGET_URL=https://mcp-server.example/sse \
  -e LISTEN_ADDR=:8080 \
  sparfenyuk/mcp-proxy:latest

Expose stdio of a local process as SSE:

# run a local process and publish its stdout/stderr as an SSE stream
./mcp-proxy --listen :8080 --stdio --stdio-cmd "python stream_generator.py"

Basic flags and environment variables (examples):

--listen        : Bind address, e.g. :8080
--target        : Upstream MCP SSE URL to proxy (optional)
--stdio         : Enable stdio mode and run a command
--stdio-cmd     : Command to run for stdio mode (string)
--cors-origin   : CORS allow-origin header (default "*")
--log-level     : Logging level (info, debug, warn)

Note: Replace placeholders with your environment values. Use systemd, Docker Compose, or Kubernetes for production deployments.

Available Resources

• GitHub repository: https://github.com/sparfenyuk/mcp-proxy
• Issues and contributions: open an issue or PR on the repo
• License and release artifacts: see the repo for license and any published releases

Use Cases

1. Browser client consuming MCP events

   • Scenario: You have an MCP-compliant model server that publishes events to SSE, but your browser app needs a stable, local endpoint, or you want to add CORS settings.
   • Solution:
     1. Run the proxy pointing at the MCP SSE URL: ./mcp-proxy –listen :8080 –target https://mcp.example/sse
     2. In the browser, connect using EventSource:

        const es = new EventSource("http://localhost:8080/events");
        es.onmessage = e => { console.log("mcp:", e.data); };
        

2. Expose a CLI tool’s stdout as SSE for frontend testing

   • Scenario: You have a local script that prints incremental JSON lines or SSE-like output. You want to stream that to a browser for debugging or demo.
   • Solution:
     1. Start: ./mcp-proxy –listen :8080 –stdio –stdio-cmd “node demo-stream.js”
     2. Connect from browser or curl:

        curl -N http://localhost:8080/events
        

3. Integration testing and local development

   • Scenario: Quickly validate client handling of streaming model output without deploying a full MCP server.
   • Solution: Use stdio mode with a small generator script that simulates model events, and test client reconnection, parsing, and backpressure logic against the SSE endpoint.

4. Bridging internal model endpoints to external clients

   • Scenario: An internal MCP server is on a private network or uses different transport. You need a public-facing SSE endpoint with controlled CORS and logging.
   • Solution: Run the proxy near the MCP server and expose an SSE endpoint through your gateway or reverse proxy.

Troubleshooting tips

• If clients report CORS errors, check the proxy’s CORS configuration (CORS_ORIGIN or –cors-origin).
• For connection drops, confirm upstream target availability and examine logs for reconnect attempts.
• Use curl -N or a simple EventSource test page to validate the SSE stream before integrating complex clients.

For more details, configuration options, and contributions, see the GitHub repository: https://github.com/sparfenyuk/mcp-proxy