mcp-http-bridge

Serve a stdio MCP server over streamable HTTP.

WARNING: this bridge can turn local-only tools into network-reachable remote code execution.

Shell-level MCP servers like shell-0 ship tools (terminal, python_exec, js_exec, fs) that run UNSANDBOXED, with your full user privileges. Put this bridge in front of one and enable those tools and anyone who can reach the port can run commands and read/write files on your machine. There is no undo.

Rules of the road: keep the tool filter tight, stay bound to 127.0.0.1 unless you truly mean otherwise, and never serve execution tools on 0.0.0.0 without authentication and TLS in front (a reverse proxy). The bridge validates the Origin header (allowlist empty by default, so browser cross-origin requests are rejected) and can require a shared-secret header, but it does no TLS of its own. Its auto-generated default filter disables every execution/escape tool and fs on purpose - leave it that way unless you know exactly what you are opening up.

Some MCP clients (llama.cpp's web UI, OpenWebUI, anything that speaks MCP over HTTP instead of spawning a stdio subprocess) want an HTTP endpoint. This bridge takes an MCP server that follows the ToolRegistry convention and re-serves its tools over MCP streamable HTTP at /mcp, gated by a per-tool allow/deny filter.

It was built to sit in front of shell-0, but works with any server that exposes a module-level _TOOL_REGISTRY (get_schemas(), get_dispatch_map(), keys()).

Security, in more detail

Binding to 0.0.0.0 exposes whatever the filter enables to anyone who can reach the port. For a server like shell-0 that means:

• enabling terminal, python_exec, or js_exec over HTTP = remote code execution for the whole network.

• enabling fs = arbitrary read/write of your filesystem, which is itself RCE-equivalent (write a shell rc, a startup script, a git hook).

Even bound to 127.0.0.1 you are not automatically safe: a web page in any browser tab can fetch() a loopback port - the DNS-rebinding / CSRF class the MCP spec says local servers must defend against. So the bridge validates the Origin header against MCP_ALLOWED_ORIGINS (empty by default, so every cross-origin browser request is rejected; non-browser MCP clients send no Origin and are unaffected) and can require a shared secret via MCP_BRIDGE_TOKEN. Its default tool filter also disables every execution/escape tool and fs. Beyond that: keep the filter tight, stay on 127.0.0.1 unless you genuinely mean to expose it, and put TLS + auth in front (a reverse proxy) before exposing anything powerful. The bridge does no TLS of its own.

Related MCP server: MCP HTTP Proxy

How it works

On startup the bridge imports your target server module, reads its _TOOL_REGISTRY, and stands up its own MCP server whose list_tools/call_tool handlers apply the filter and then dispatch into the target's registry. If the target exposes _truncate_output / _sanitize_surrogates (shell-0 does), those are reused so HTTP responses get the same output hygiene as stdio. Transport is the official StreamableHTTPSessionManager behind Starlette + uvicorn.

Rebuilding the server (instead of just wrapping the target's) is deliberate: it lets the bridge enforce the filter even when the underlying server does not, so a stdio server that exposes everything locally can still be served selectively over HTTP.

Install

Requires Python 3.10+.

Install as a package to get an mcp-http-bridge command on your PATH:

pipx install git+https://github.com/cutlerbenjamin1-cmd/mcp-http-bridge

From a local checkout: pip install . Or just install the dependencies and run bridge.py directly:

pip install -r requirements.txt

Run it in front of shell-0

Clone shell-0 next to wherever you like, then run the bridge from inside the shell-0 directory so import server resolves:

cd /path/to/shell-0
mcp-http-bridge      # or: python /path/to/mcp-http-bridge/bridge.py

Point your HTTP MCP client at:

http://127.0.0.1:8818/mcp

On first run the bridge writes an http_tools.json next to you with a safe default (execution tools and fs off, everything else on). Edit it to choose what is reachable over HTTP, then restart. See http_tools.example.json for the shape. To let a browser client in, set MCP_ALLOWED_ORIGINS to its origin; for a shared secret, set MCP_BRIDGE_TOKEN and send it as X-MCP-Token (or Authorization: Bearer).

To expose on the LAN (read the security note again first):

set MCP_HOST=0.0.0.0
mcp-http-bridge      # or: python /path/to/mcp-http-bridge/bridge.py

Configuration

Environment variables:

• MCP_SERVER_MODULE - module to import for the registry (default: server).

• MCP_HOST - bind address (default: 127.0.0.1; 0.0.0.0 for LAN).

• MCP_PORT - port (default: 8818).

• HTTP_TOOLS_CONFIG - path to the tool filter json (default: ./http_tools.json).

• MCP_DEBUG - true for stderr debug logging.

The filter file is {"tool_name": 1 | 0}. Missing tools are treated as disabled.

License

MIT. See LICENSE.