mcp-relay

🇯🇵 日本語版: README.ja.md

Relay a stdio MCP server to authenticated HTTP on 127.0.0.1, so a sandboxed MCP client can use a server that has to run outside the sandbox.

Why

An MCP client starts its stdio servers as child processes, so they inherit whatever sandbox the client runs in. Some servers cannot work from there: a server that talks to the desktop session (calendar and reminder access, permission prompts, other applications) is refused by the operating system as soon as it is confined.

Loosening the sandbox until the server works defeats the sandbox. The relay keeps the two apart instead:

  inside the sandbox                 outside the sandbox
┌─────────────────────┐            ┌───────────────────────────────────┐
│ MCP client          │  HTTP on   │ mcp-relay ── stdio ── MCP server  │
│ (type: http)        ├───────────►│ 127.0.0.1, bearer token           │
└─────────────────────┘            └───────────────────────────────────┘

The sandbox only has to allow a connection to one loopback port. What the client can do outside is exactly what that one server offers.

How it behaves

• Listens on 127.0.0.1 only. There is no option to listen anywhere else.

• Every request needs Authorization: Bearer <token>. The token is read from a file or an environment variable, never from the command line.

• Requests whose Host header is not the loopback address are refused, which closes the DNS rebinding route from a browser.

• One server process per client session. The process is stopped when the session ends, when the relay stops, or when the watched process is gone.

• The token is removed from the environment of the server processes.

Requirements

• Node.js 20 or later

• Task to run the development commands

Quick start

git clone https://github.com/Synforger/mcp-relay.git
cd mcp-relay
task setup

export MCP_RELAY_TOKEN="$(openssl rand -hex 24)"
node bin/mcp-relay.mjs --port 8765 -- npx -y @modelcontextprotocol/server-everything

Register the relay in the client as an HTTP server. For a client that reads .mcp.json and expands environment variables:

{
  "mcpServers": {
    "everything": {
      "type": "http",
      "url": "http://127.0.0.1:8765/mcp",
      "headers": { "Authorization": "Bearer ${MCP_RELAY_TOKEN}" }
    }
  }
}

To tie the relay to the lifetime of the client, start it from the script that launches the client and pass that script's process id:

node bin/mcp-relay.mjs --port 8765 --watch-pid $$ -- <server command> &

Documentation

• Setup: installing, starting, stopping

• Reference: every option, the HTTP surface, the library entry point

• Troubleshooting: what each refusal means

• Internals: design notes and the development flow

Limits

• A notification the server sends on its own, outside the answer to a request, reaches the client only while the client holds its event stream open.

• The relay does not inspect tool calls. Restricting what the client may call is the job of the client's own permission settings.

License

Apache-2.0 (LICENSE). Dependencies are listed in THIRD_PARTY_NOTICES.md; vulnerability reports go through SECURITY.md.