🌐 MCP Multi-Server Gateway

Aggregate, route, and orchestrate multiple MCP backend servers behind a single MCP endpoint. Connect one gateway to Claude Desktop/Cursor and access all your MCP servers — weather, database, file system, and more.

---

✨ Why a Gateway?

Instead of configuring each MCP server individually in your client:

// ❌ Without Gateway: 3 entries in claude_desktop_config.json
{
  "weather": { "command": "...", "args": ["weather_server.py"] },
  "sqlite": { "command": "...", "args": ["sqlite_server.py", "--db-path", "..."] },
  "filesystem": { "command": "...", "args": ["filesystem_server.py", "--sandbox", "..."] }
}

// ✅ With Gateway: 1 entry — register/unregister servers at runtime
{
  "gateway": { "command": "python", "args": ["gateway.py"] }
}

---

✨ Features

• 🔧 5 Tools: register_server, remove_server, list_servers, call_backend, route_pipeline
• ⏱️ Async Routing: Concurrent tool execution across backends via asyncio
• 📋 Pipeline Support: Pre-configured multi-step workflows (weather-analysis, database-report)
• 📝 Auto-Registration: Load backend config from JSON file on startup
• 🔌 Runtime Dynamic: Register/unregister servers without restarting
• ⏲️ Timeout Handling: 10-second per-backend timeout prevents hangs
• 🖥️ Dual Transport: stdio and Streamable HTTP

---

🚀 Quick Start

# 1. Setup
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# 2. Start the gateway
python gateway.py

# 3. Register backend servers (from MCP client)
register_server(name="weather", command="python", args="weather_server.py", description="Weather alerts")
register_server(name="sqlite", command="python", args="sqlite_server.py --db-path /tmp/sample.db", description="Database queries")

With auto-registration:

python gateway.py --auto-register gateway-config.json

---

🛠️ Tools Reference

register_server(name, command, args, description) -> str

Register a new backend MCP server at runtime.

remove_server(name) -> str

Remove a registered server.

list_servers() -> str

List all registered backends with status and tool counts.

call_backend(server, tool, params) -> str

Execute a tool on a specific backend. params is a JSON string.

route_pipeline(scenario) -> str

Execute a pre-configured multi-step pipeline:

• "weather-analysis" — alerts + forecast
• "database-report" — schema inspection + query
• "custom" — compose your own workflow

---

🔌 Connecting to Clients

Claude Desktop

{
  "mcpServers": {
    "gateway": {
      "command": "python",
      "args": ["/ABSOLUTE/PATH/mcp-multi-server-gateway/gateway.py"]
    }
  }
}

Streamable HTTP Mode

python gateway.py --transport streamable-http --port 8003

---

📁 Project Structure

mcp-multi-server-gateway/
├── gateway.py              # Main gateway server (FastMCP + asyncio)
├── gateway-config.json     # Example auto-registration config
├── requirements.txt
├── setup.sh
├── README.md
└── .gitignore

---

🏗️ Architecture

         ┌─────────────────────────────────────┐
         │       MCP Client (Claude, etc)       │
         └──────────────┬──────────────────────┘
                        │  single MCP connection
         ┌──────────────▼──────────────────────┐
         │     MCP Multi-Server Gateway         │
         │     (gateway.py on :8003)            │
         │                                      │
         │  register / call_backend / pipeline  │
         └──┬──────────┬──────────┬───────────┘
            │          │          │
     ┌──────▼──┐ ┌─────▼────┐ ┌──▼────────┐
     │ Weather  │ │  SQLite  │ │ FileSystem│
     │ Server   │ │  Server  │ │  Server   │
     └─────────┘ └──────────┘ └───────────┘

---

💡 Use Cases

Scenario	Tools Involved	Example
DevOps Debugging	sqlite.query + filesystem.read_file	"Check DB schema, then read config file"
Data Analysis	sqlite.list_tables + sqlite.query	"What tables exist? Give me top 10 customers"
Multi-weather check	weather.get_alerts × 2	"Alerts for CA and TX simultaneously"
Automated report	All servers in sequence	"Get weather data → query DB → write report"

---

📜 License

MIT