tiny-mcp-gateway

Zero-dependency MCP proxy/gateway server. Aggregate multiple MCP servers, route by tool prefix, load-balance, and enforce auth + rate limits. Like a reverse proxy for AI agent tool infrastructure.

pip install tiny-mcp-gateway   # coming soon

Why?

• Multiple MCP servers — Claude Desktop, Cursor, and custom servers all need separate clients
• No aggregation layer — no standard way to expose multiple MCP servers behind one endpoint
• No routing — can't route github/* tools to a GitHub backend and file/* to a filesystem backend

tiny-mcp-gateway is one file that solves all three: proxy, router, load balancer, auth gateway — zero deps.

Quick Start

from tiny_mcp_gateway import MCPGateway, Backend

gw = MCPGateway(port=8080)

# Register backends
gw.add_backend(Backend(name="github",   url="https://api.github.com/mcp"))
gw.add_backend(Backend(name="files",     url="stdio:python -m mcp_fileserver"))
gw.add_backend(Backend(name="database",  url="https://db.internal/mcp"))

# Route by tool prefix
gw.route_tool("github/", "github",   priority=10)
gw.route_tool("file/",   "files",    priority=10)
gw.route_tool("db/",      "database", priority=10)
gw.set_default_backend("github")

# Generate an API key
key = gw.add_api_key(label="my-agent", rate_limit=100, scopes=["read"])

print(f"Gateway running. Key: {key}")

# Run the server
gw.run()  # starts on port 8080

Making Requests

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "github/repo",
      "arguments": {"owner": "openai", "repo": "GPT-5"}
    }
  }'

Auth & Rate Limiting

# Create keys with different scopes and rate limits
gw.add_api_key(label="read-only-agent", scopes=["read"], rate_limit=50)
gw.add_api_key(label="full-agent",      scopes=["read", "write"], rate_limit=200)

# Pass key in params (works with all backends)
curl -X POST http://localhost:8080/mcp \
  -d '{"method": "tools/call", "params": {"name": "github/repo", "_api_key": "mcp_xxx"}}'

HMAC Signing (for webhook backends)

import os

# Set HMAC secret (shared with your backend)
os.environ["MCP_GATEWAY_HMAC_SECRET"] = "super-secret-key"

gw = MCPGateway(hmac_secret=os.environ["MCP_GATEWAY_HMAC_SECRET"])
gw.add_backend(Backend(
    name="secure-service",
    url="https://secure.internal/mcp",
    secret="super-secret-key",  # backend verifies HMAC signature
))
gw.run()

Architecture

Clients                          tiny-mcp-gateway
  |                                    |
  |-- POST /mcp (auth)  -----------> [Auth] --> [Router] --> [Backend Pool]
  |   tools/call github/repo               |            |
  |                                         v            v
  |-- GET  /health ---------> [Health]     [GitHub MCP]  [Files MCP]
  |-- GET  /routes --------> [Route Map]   [DB MCP]

Backend Types

HTTP Backend

gw.add_backend(Backend(name="api", url="https://api.example.com/mcp"))

Stdio Backend (local subprocess)

gw.add_backend(Backend(
    name="files",
    url="stdio:npx @anthropic/mcp-server-filesystem ./data"
))
gw.add_backend(Backend(
    name="github",
    url="stdio:python -m mcp_github --token $GITHUB_TOKEN"
))

Health & Monitoring

# Health check
curl http://localhost:8080/health
# {"status": "ok", "backends": [{"name": "github", "healthy": true, "failures": 0}]}

# Route map
curl http://localhost:8080/routes
# {"backends": [...], "routes": [{"prefix": "github/", "backend": "github", "priority": 10}]}

ASGI / WSGI Compatible

Works with any ASGI server (uvicorn, hypercorn) or as a plain Python module:

# uvicorn
import uvicorn
from tiny_mcp_gateway import MCPGateway
app = MCPGateway(port=8080)
uvicorn.run(app, host="0.0.0.0", port=8080)

# Or run directly
app.run()

AI Agent Fit

tiny-mcp-gateway is the backbone of a multi-tool agent architecture:

• Single endpoint — agents connect to one gateway, access all tools
• Tool routing — automatic routing by prefix, no manual tool dispatch
• Load balancing — weighted round-robin across backend replicas
• Circuit breaking — unhealthy backends are skipped automatically
• Auth enforcement — per-key rate limits and scopes

This is the architecture that makes tiny-agent-service work with external MCP servers:

tiny-agent (reasoning) --> tiny-mcp-client --> tiny-mcp-gateway --> [MCP Servers]
                                                    |
                                                    +-> GitHub tools
                                                    +-> Filesystem tools
                                                    +-> Database tools

API Reference

Method	Description
MCPGateway(port)	Create gateway
gw.add_backend(Backend)	Register a backend
gw.route_tool(prefix, backend, priority)	Add routing rule
gw.set_default_backend(name)	Set fallback backend
gw.add_api_key(label, scopes, rate_limit, ttl)	Create API key
gw.run(host, port)	Start server
gw.handle(scope, receive, send)	ASGI entry point

Ecosystem

Part of the tiny-* zero-dependency toolkit for Python agent infrastructure:

• tiny-agent — zero-dep agent framework
• tiny-mcp-client — MCP client (stdio + SSE)
• tiny-task — durable task queue
• tiny-retry — retry + circuit breaker
• tiny-webhook — production webhook handler
• fast-cache — LRU + TTL + SWR cache
• snapdb — lightning-fast embedded DB

All single-file, MIT, zero dependencies. Built by OpenClaw.

License

MIT © 2026 OpenClaw (hussain-alsaibai)