Mcp Bridge

mcp-bridge

A tiny Rust stdio ↔ HTTP transport bridge for the Model Context Protocol. It is a drop-in replacement for npx mcp-remote: it speaks JSON-RPC over stdin/stdout to a host agent, and proxies that traffic to a remote MCP server over streamable-HTTP (2025-03-26 spec) or legacy SSE.

It exists because the Node version was eating the host alive.

The problem we hit with Hermes

Our agent stack runs Hermes Agent (by Nous Research) on a single, memory-constrained host. Hermes connects to a couple dozen MCP servers — a mix of native streamable-HTTP backends and a handful that only speak legacy SSE.

Hermes can talk to a streamable-HTTP MCP server directly (mcp_servers..url). But for any server that only speaks the legacy SSE transport, the agent needs a stdio bridge subprocess in between. The canonical bridge is npx mcp-remote, a Node program.

That bridge turned out to be the single most expensive thing on the box:

• ~95 MB resident per instance. Six legacy-SSE backends meant ~570 MB just in bridge processes — for what is, functionally, a byte shuffler between a pipe and an HTTP socket.
• The gateway kept getting OOM-killed. Two things compounded: the gateway unit shipped with oom_score_adj=100, marking it as the kernel's preferred victim, and the bridge processes left no headroom. Under any memory pressure, the kernel killed the gateway — taking down every messaging channel at once.

We fixed the operational side two ways:

1. Moved most MCPs off bridges entirely. Where the upstream supports streamable-HTTP, Hermes connects directly via url: + headers: — no subprocess at all. (In one case we rebuilt an upstream server from HEAD to pick up native streamable-HTTP and retired its bridge.)
2. Replaced the remaining bridges with this binary. For the backends that genuinely only speak legacy SSE, mcp-bridge does the same job as npx mcp-remote at ~2 MB resident instead of ~95 MB.

We also set OOMScoreAdjust=-500 on the gateway unit so it's no longer the kernel's first pick. Net effect: the bridge layer went from ~570 MB to a couple of MB, and the OOM kills stopped.

What it does

host agent  ──stdin/stdout (JSON-RPC lines)──▶  mcp-bridge  ──HTTP──▶  MCP server

• Streamable-HTTP (default): POSTs each stdin line to the server; relays JSON or text/event-stream responses back to stdout. Tracks Mcp-Session-Id. Opens a background GET subscription for server-initiated messages, with exponential-backoff reconnect (and quietly gives up if the server answers 405/404, meaning it doesn't support GET subscriptions).
• Legacy SSE: connects GET /sse, waits for the server's endpoint event to learn the POST URL, then forwards stdin lines there. Reconnects with backoff if the stream drops.
• Transport auto-detection: a URL path ending in /sse (or containing /sse/) is treated as legacy SSE; everything else is streamable-HTTP. Override with --transport.
• HTTPS by default: plain http:// is rejected unless the host is loopback or you pass --allow-http.

It is ~400 lines of Rust, built for size (opt-level = "z", LTO, stripped, panic = "abort"), producing a ~2 MB static binary.

Usage

mcp-bridge  [--header "K: V"]... [--allow-http] [--transport http|sse|auto] [-v]

| Flag | Default | Meaning | |---|---|---| | ` | — | MCP server URL (…/mcp for streamable-HTTP, …/sse for legacy SSE) | | --header "K: V" | — | Add an HTTP header; repeatable (e.g. auth tokens) | | --allow-http | off | Permit non-loopback plain http:// URLs | | --transport | auto | Force http, sse, or auto-detect from the path | | -v, --verbose` | off | Diagnostic logging to stderr (stdout stays pure JSON-RPC) |

Examples:

# Legacy SSE backend on localhost (auto-detected from the /sse suffix)
mcp-bridge http://127.0.0.1:9801/sse

# Remote streamable-HTTP MCP with an auth header
mcp-bridge https://mcp.example.com/mcp --header "X-API-Key: $TOKEN"

# Force legacy SSE and watch the handshake
mcp-bridge https://mcp.example.com/stream --transport sse -v

> Note: diagnostics go to stderr only. stdout carries the JSON-RPC stream and must never be polluted, or the host agent's parser will choke.

Build

Standard Cargo project, no build scripts.

Native (build where you'll run it)

cargo build --release
# binary at target/release/mcp-bridge

Cross-compile from macOS to a Linux server (how we ship it)

We develop on macOS and run on Ubuntu x8664. A fully static musl binary cross-builds cleanly with cargo-zigbuild:

# one-time toolchain setup
brew install zig
cargo install cargo-zigbuild
rustup target add x86_64-unknown-linux-musl

# build the static binary
cargo zigbuild --release --target x86_64-unknown-linux-musl
# binary at target/x86_64-unknown-linux-musl/release/mcp-bridge (~2 MB, no libc dependency)

scp -i ~/.ssh/your-key.pem \
    target/x86_64-unknown-linux-musl/release/mcp-bridge \
    root@:/usr/local/bin/mcp-bridge
ssh -i ~/.ssh/your-key.pem root@ 'chmod +x /usr/local/bin/mcp-bridge'

mcp_servers:
  mcp-foo:
    command: /usr/local/bin/mcp-bridge
    args: [http://127.0.0.1:9801/sse]

src/main.rs    # the whole bridge (~400 lines): arg parsing, streamable-HTTP, legacy SSE
Cargo.toml     # deps + size-optimized release profile