Build-Browser-Gateway

One MCP door to four browser engines.

browser-gateway is a Python MCP server that gives an AI agent a single unified door to the web, and routes every request to the engine that does that job best:

There is also a flat tool per engine (browser_pinchtab, browser_bb, browser_reach, browser_playwright) for callers that already know which hand they need.

Design rules the agent cannot talk its way around

• Hard timeouts everywhere. Every engine subprocess gets a hard timeout; a stuck page can no longer pin the whole MCP session forever.

• Explicit truncation. Output is capped by max_chars (default 10000) and list results by limit (default 5) — and the caller is always told what was cut. Silent truncation is worse than no truncation.

• Fail-closed gates. The two risky engines (custom scripts, anything that looks like authentication) are blocked unless two environment variables are deliberately set: BROWSER_GATEWAY_ALLOW_CUSTOM_SCRIPT=1, BROWSER_GATEWAY_ALLOW_SESSION_AUTH=1.

• Silent-zero detection. An adapter that returns "success" with zero results is flagged in the output, because an AI agent will otherwise read it as "the answer is that there is nothing there".

Related MCP server: browserpilot

Install

pip install .
# then point your MCP client at:
python -m browser_gateway_mcp.server

Engines are external binaries found on PATH (or via environment variables below): pinchtab, bb-browser, agent-reach, and a Python interpreter with playwright installed.

Configuration (environment variables)

Notes

• Every account, key and password in the published sources is a mock. Real credentials never leave the machine.

• The engines themselves are separate open-source tools; what this repository contains is the door, the routing and the safety rules.

Licence

MIT