MCP Gateway

One endpoint for every MCP server your agent needs — fetch tool schemas on demand instead of loading everything upfront.

MCP Gateway aggregates multiple MCP servers behind a single headless HTTP/SSE endpoint. Its Code Mode exposes five MCP meta-tools (listToolFiles, readToolFile, getToolDocs, executeTool, callManyTool) so agents discover signatures lazily and fan out bounded parallel calls without leaving the MCP surface. The host-side Python call_many helper remains available for direct code use, but the MCP contract exposes callManyTool as the fifth meta-tool.

• CLI: mcp-gway (canonical) or mgw (alias)
• Admin UI: mcp-gway serve --transport http → http://127.0.0.1:8080/

Why MCP Gateway

• Fewer wasted tokens — Agents fetch only the schemas they need, when they need them.
• One connection to manage — Add, remove, or refresh servers in a single registry; agents connect to one endpoint.
• Safe local-first defaults — Binds to 127.0.0.1 by default, screens local commands via an allowlist, masks secrets, and CSRF-protects the admin dashboard.

Who It's For

• Agent developers wiring Pi, Antigravity, Claude Desktop, Cursor, or any MCP-compatible client to multiple MCP servers through one gateway.
• Operators running local-first infrastructure who want a CLI and dashboard with health probes, Prometheus metrics, and structured JSON logs.

Quick Start

1. Install: pip install mcp-gway
2. Add a server: mcp-gway add files --type local --command "npx -y @modelcontextprotocol/server-filesystem /path/to/dir"
3. List servers: mcp-gway list
4. Serve HTTP: mcp-gway serve --transport http
5. Connect: Point your agent to http://127.0.0.1:8080/mcp

For more examples and transports, see the CLI Reference and Integrations.

Features

• Multi-Server Aggregation — Connect to multiple MCP servers (local or remote) and expose them through a single endpoint. One URL for every agent; one registry to manage.
• Code Mode — Five MCP meta-tools let LLMs discover schemas on demand, execute them in a hermetic sandbox, and fan out bounded parallel calls without loading all tool definitions upfront.
• OAuth 2.0 Support — Built-in OAuth flow with Dynamic Client Registration (RFC 7591), secure token storage, and automated /.well-known/oauth-protected-resource discovery metadata (RFC 8707) for OAuth-capable MCP clients.
• Hexagonal Architecture — Strict separation between pure domain models/ports, application use cases, and infrastructure adapters for isolated unit testability without running servers.
• Hermetic Sandbox — Starlark-based sandbox for safe, constrained code execution.
• MCP Protocol Compliant — Implements the Model Context Protocol over HTTP, SSE, and stdio.
• Local-First Security — Local-first design with SSRF guards, command allow-lists, and CSRF protection.
• Built-In Observability — Structured JSON logs, Prometheus metrics, and health probes built in.

Documentation

• Configuration & Usage — add servers, transports, and OAuth
• CLI Reference — commands, options, and the admin dashboard
• Code Mode — lazy-discovery meta-tools and the sandbox
• Security — local-first controls and command allow-lists
• Observability — JSON logs, Prometheus metrics, health probes
• Integrations — Claude Desktop, Pi, Antigravity, OpenCode
• Architecture — system diagram and transports
• Development — tests, lint, and pre-commit

Development

uv sync --all-groups
uv run pytest -v   # 688 tests

See docs/development.md for checks, probes, and pre-commit.

License

MIT