mcp-gateway

A generic MCP gateway: a single FastMCP endpoint that aggregates many upstream MCP servers, driven entirely by a servers.json config. The machinery is deployment-agnostic — bring your own config and auth.

Extracted as the reusable core of a personal MCP gateway so it can be consumed as a package (each consumer provides its own servers.json + auth), rather than forked.

What it does

• Config-driven aggregation — declare upstreams in servers.json (stdio or streamable-http); the gateway mounts each as a proxy and exposes one flat tool surface.

• Tool subset / rename — expose only the tools you want, renamed to a clean cross-server vocabulary (or "*" to pass through).

• Multi-instance routing — one logical server, N backends keyed by an injected account/host/instance param (e.g. personal+work, or laptop+desktop+vm). Enum-in-schema, fail-at-call-time error enrichment.

• Middleware — e.g. image downscaling on outbound content blocks.

• Pluggable auth — single-user (bearer/OAuth) today; a multi-tenant provider (per-user identity forwarded to each upstream) is the next milestone.

Related MCP server: mcpstead

Config

Set MCP_SERVERS_FILE to a servers.json. Each entry declares a transport + tools; an instances block turns it multi-instance.

Run

gateway-local     # stdio gateway (local clients)
gateway-remote    # streamable-http gateway (behind a reverse proxy)

Consuming as a package

mcp-gateway @ git+https://github.com/klutometis/mcp-gateway.git

The consumer owns its servers.json and auth config; this package never imports consumer code.

Status

Phase 0 extraction (generic machinery + tests). Multi-tenant auth provider is the next milestone — see the extraction plan in the personal gateway repo.