Content
# MCP Hub
Aggregates multiple MCP servers, unified into a standard MCP interface for other agents (such as Claude Code, Cursor, etc.) to integrate.
## Features
- **Multi MCP Aggregation**: Connect multiple downstream MCP servers, unify all tools exposure
- **Tool Namespace**: Automatic prefix isolation, `server_id_tool_name` format
- **Dual Transmission Support**: Support both stdio and HTTP (Streamable HTTP) transmission methods
- **Hot Management**: Register/enable/disable downstream servers **automatic hot reload**, no need to restart the gateway
- **Management API**: RESTful HTTP API manages all downstream servers
- **SQLite Persistence**: Server configuration persistent storage, zero external dependencies
- **Self-Inspection Tool**: Built-in `gateway__list_servers` and `gateway__list_all_tools`
## Installation
### Prerequisites
- Python >= 3.10
- Node.js >= 16 (if you need to run npm MCP package)
### Installation Steps
```bash
# Clone or enter the project directory
cd mcp_demo
# Install (development mode)
pip install -e .
```
### Dependencies
```
fastmcp >= 2.0 # MCP framework
pydantic >= 2.0 # Data model validation
typer # CLI command line
uvicorn # HTTP server
starlette # HTTP management API
aiosqlite # SQLite storage
httpx # HTTP client
```
## Quick Start
### 1. Register Downstream MCP Servers
```bash
# Register local Python MCP server
mcp-gateway register \
--server-id math \
--display-name "Math Server" \
--command python \
--args "examples/downstream_servers/math_server.py"
# Register weather server
mcp-gateway register \
--server-id weather \
--display-name "Weather Server" \
--command python \
--args "examples/downstream_servers/weather_server.py"
# Register bing-search (Windows need cmd /c package)
mcp-gateway register \
--server-id bing \
--display-name "Bing Search" \
--command cmd \
--args "/c,npx,-y,bing-cn-mcp"
# Register HTTP type MCP server
mcp-gateway register \
--server-id remote-api \
--display-name "Remote API" \
--transport http \
--url "https://api.example.com/mcp"
```
### 2. View Registered Servers
```bash
# Basic list
mcp-gateway list
# Display connection status and tools
mcp-gateway list --status --tools
# JSON format output
mcp-gateway list --json
```
### 3. Start Gateway
```bash
# stdio mode (for Claude Code and other agents to integrate as subprocesses)
mcp-gateway serve
# HTTP mode (for remote agents to connect)
mcp-gateway serve --transport http --port 8000
# Complete parameters
mcp-gateway serve \
--transport http \
--host 0.0.0.0 \
--port 8000 \
--path /mcp \
--management-port 9000 \
--store gateway.db
```
## CLI Command Reference
| Command | Description |
|---|---|
| `mcp-gateway serve` | Start gateway server |
| `mcp-gateway register` | Register new downstream MCP server (automatically notify running gateway hot reload) |
| `mcp-gateway list` | List all registered servers |
| `mcp-gateway enable <id>` | Enable server (automatically notify running gateway hot reload) |
| `mcp-gateway disable <id>` | Disable server (automatically notify running gateway hot reload) |
| `mcp-gateway remove <id>` | Permanently remove server (automatically notify running gateway hot reload) |
| `mcp-gateway health <id>` | Check server health status |
| `mcp-gateway reload` | Manual reload configuration prompt |
| `mcp-gateway export-config` | Export server configuration |
| `mcp-gateway import-config <file>` | Import configuration from JSON file (automatically notify running gateway hot reload) |
### `serve` Parameters
| Parameter | Default Value | Description |
|---|---|---|
| `--transport`, `-t` | `stdio` | Transmission type: `stdio` or `http` |
| `--host` | `127.0.0.1` | HTTP listening address |
| `--port`, `-p` | `8000` | HTTP port |
| `--path` | `/mcp` | MCP protocol HTTP path |
| `--management-port` | `9000` | Management API port |
| `--no-management` | — | Disable management API |
| `--store` | `gateway_config.db` | SQLite database path |
| `--name` | `MCP Gateway` | Gateway name |
| `--log-level` | `INFO` | Log level |
### `register` Parameters
| Parameter | Description |
|---|---|
| `--server-id` | Unique server identifier (required) |
| `--display-name` | Readable name |
| `--transport` | `stdio` (default) or `http` |
| `--command` | stdio mode startup command |
| `--args` | Comma-separated command parameters |
| `--url` | HTTP mode server URL |
| `--management-port` | Management API port for automatic hot reload (default 9000) |
| `--no-auto-discover` | Do not connect immediately after registration |
| `--tags` | Comma-separated tags |
| `--store` | Storage path |
> **Note**: `register`, `enable`, `disable`, `remove`, `import-config` commands will automatically notify the running gateway to hot reload (through management API). If the gateway is not running, the reload request will silently fail without affecting command execution.
## HTTP Management API
Management API runs on an independent port (default 9000).
### Endpoint List
```
GET /api/v1/servers List all servers
POST /api/v1/servers Register new server
GET /api/v1/servers/{server_id} Get server details
PUT /api/v1/servers/{server_id} Update server configuration
DELETE /api/v1/servers/{server_id} Delete server
POST /api/v1/servers/{server_id}/enable Enable server
POST /api/v1/servers/{server_id}/disable Disable server
GET /api/v1/servers/{server_id}/health Health check
GET /api/v1/tools View all aggregated tools
GET /api/v1/gateway/status Gateway status overview
POST /api/v1/gateway/reload Hot reload configuration
GET /api/v1/gateway/export Export configuration
POST /api/v1/gateway/import Import configuration
```
### Usage Example
```bash
# Register server
curl -X POST http://localhost:9000/api/v1/servers \
-H "Content-Type: application/json" \
-d '{
"server_id": "weather",
"display_name": "Weather Service",
"transport": "stdio",
"stdio_config": {"command": "python", "args": ["weather_server.py"]}
}'
# View all servers
curl http://localhost:9000/api/v1/servers
# View aggregated tools
curl http://localhost:9000/api/v1/tools
# View gateway status
curl http://localhost:9000/api/v1/gateway/status
# Enable/disable
curl -X POST http://localhost:9000/api/v1/servers/weather/enable
curl -X POST http://localhost:9000/api/v1/servers/weather/disable
# Hot reload
curl -X POST http://localhost:9000/api/v1/gateway/reload
```
## Integration with Other Agents
### Claude Code Integration
Create `.mcp.json` in the project root directory:
```json
{
"mcpServers": {
"gateway": {
"command": "python",
"args": ["-m", "mcp_gateway", "serve", "--transport", "stdio"]
}
}
}
```
Or use global CLI command:
```bash
claude mcp add gateway -s project -- python -m mcp_gateway serve --transport stdio
```
### Custom Agent Integration
```python
# Through stdio
from fastmcp import Client
from fastmcp.client.transports import StdioTransport
async with Client(StdioTransport(
command="python",
args=["-m", "mcp_gateway", "serve", "--transport", "stdio"],
)) as client:
# List all tools (including namespace prefix)
tools = await client.list_tools()
for tool in tools:
print(tool.name) # Such as: math__add, weather__get_forecast
# Call proxy tool
result = await client.call_tool("math__add", {"a": 3, "b": 5})
print(result)
```
```python
# Through HTTP
from fastmcp import Client
async with Client("http://localhost:8000/mcp") as client:
tools = await client.list_tools()
result = await client.call_tool("weather__get_current", {"city": "Beijing"})
print(result)
```
### Remote Agent Integration
As a standard MCP HTTP server, any agent supporting MCP Streamable HTTP protocol can connect:
```json
{
"mcpServers": {
"gateway": {
"type": "http",
"url": "http://gateway-host:8000/mcp"
}
}
}
```
## Tool Naming Rules
All tools of downstream servers automatically add `server_id_` prefix:
| Downstream Server | Original Tool Name | Name in Gateway |
|---|---|---|
| math | `add` | `math_add` |
| math | `multiply` | `math_multiply` |
| weather | `get_forecast` | `weather_get_forecast` |
| bing | `bing_search` | `bing_bing_search` |
| bing | `crawl_webpage` | `bing_crawl_webpage` |
Gateway self-inspection tools use double underline `gateway__` prefix (not rewritten by mount):
| Tool Name | Function |
|---|---|
| `gateway__list_servers` | List all servers and connection status |
| `gateway__list_all_tools` | List all aggregated tools |
## Project Architecture
```
External Agent (Claude Code / Cursor / Others)
│
┌────┴────┐
stdio HTTP (streamable-http)
└────┬────┘
▼
┌──────────────────┐
│ GatewayServer │ ← Unified FastMCP instance
│ (FastMCP) │
└────┬────┬─────────┘
│ │
┌────▼─┐ ┌▼────────────┐
│Proxy │ │Management │
│Manager│ │API │
└──┬──┬─┘ └─────────────┘
│ │
┌───▼┐ ┌▼────┐
│MCP A│ │MCP B│ ...
└────┘ └─────┘
```
## Configuration Import/Export
```bash
# Export current configuration
mcp-gateway export-config --output servers.json
# Import from JSON file
mcp-gateway import-config servers.json
# Example configuration file format (examples/config.yaml)
```
Example configuration (`examples/config.yaml`):
```json
{
"mcpServers": {
"math": {
"command": "python",
"args": ["examples/downstream_servers/math_server.py"]
},
"weather": {
"command": "python",
"args": ["examples/downstream_servers/weather_server.py"]
},
"bing-search": {
"command": "cmd",
"args": ["/c", "npx", "-y", "bing-cn-mcp"]
}
}
}
```
## Notes
1. **Windows stdio**: Windows registered npm class MCP needs to use `cmd` command: `--command cmd --args "/c,npx,-y,<package-name>"`
2. **Network environment**: HTTP type downstream server needs accessible network connection
3. **Port conflict**: Default MCP port 8000, management port 9000, ensure not occupied
4. **No unmount**: FastMCP does not support runtime unmount, disable/delete server and then restart gateway to get clean state
5. **Single machine design**: SQLite suitable for single machine deployment, if you need cluster, you can extend PostgreSQL and other databases through `AbstractStore` interface
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available