pip install tiny-mcp-gateway   # coming soon

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

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"}
    }
  }'

# 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"}}'

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()

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]

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

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 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}]}

# 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()

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