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 does no auth of its own. Its auto-generated default filter disables every execution and escape tool 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.

So: keep the filter tight, stay on 127.0.0.1 unless you genuinely mean to expose it, and put authentication and TLS in front of it (a reverse proxy) before exposing anything powerful. The bridge itself does no auth. The default filter it generates disables every execution/escape tool for exactly this reason.

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+.

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
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 off, fs on). Edit it to choose what is reachable over HTTP, then restart. See http_tools.example.json for the shape.

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

set MCP_HOST=0.0.0.0
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.