# 🌐 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.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)

---

## ✨ Why a Gateway?

Instead of configuring each MCP server individually in your client:

```json
// ❌ 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

```bash
# 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:

```bash
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

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

### Streamable HTTP Mode

```bash
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