Fastmcp Mux
FastMCP Proxy Server to other MCP Servers
Ask AI about Fastmcp Mux
Powered by Claude Β· Grounded in docs
I know everything about Fastmcp Mux. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
FastMCP Proxy
A robust MCP (Model Context Protocol) multiplexer that routes requests to multiple MCP server backends. This proxy server enables you to aggregate tools, prompts, and resources from multiple MCP servers into a single endpoint.
Features
- π Multi-Backend Support: Connect to multiple MCP servers simultaneously (stdio and WebSocket)
- π·οΈ Tool Namespacing: Automatic namespacing to avoid tool ID conflicts
- π Hot Reload: Automatically reload configuration without restarting
- π‘οΈ Circuit Breaker: Fault tolerance with circuit breaker pattern
- β»οΈ Retry Logic: Configurable retry with exponential backoff
- π Authentication: Per-backend auth support (Bearer, Basic, Custom)
- β±οΈ Timeouts: Configurable per-backend timeouts
- π₯ Health Checks: Periodic health monitoring of backends
- π Logging: Comprehensive logging with JSON format support
- π HTTP/WebSocket Bridge: Serve MCP over HTTP REST API and WebSocket
- β Schema Validation: Full Pydantic-based configuration validation
- π³ Docker Support: Ready-to-use Dockerfile
Installation
# Install from source
pip install -e .
# Install with development dependencies
pip install -e ".[dev]"
Quick Start
1. Initialize Configuration
fastmcp-proxy init config.json
This creates an example configuration file:
{
"mcpServers": {
"example-stdio": {
"name": "example-stdio",
"transport": "stdio",
"command": ["python", "-m", "example_mcp_server"],
"enabled": false
},
"example-ws": {
"name": "example-ws",
"transport": "ws",
"url": "ws://localhost:8001/mcp",
"enabled": false
}
},
"host": "127.0.0.1",
"port": 8000,
"log_level": "INFO",
"hot_reload": true
}
2. Configure Your MCP Servers
Edit config.json to add your actual MCP servers:
{
"mcpServers": {
"filesystem": {
"transport": "stdio",
"command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
"enabled": true
},
"github": {
"transport": "stdio",
"command": ["npx", "-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_TOKEN": "your-token-here"
},
"enabled": true
},
"custom-ws": {
"transport": "ws",
"url": "ws://localhost:8001/mcp",
"auth": {
"type": "bearer",
"credentials": {
"token": "your-api-key"
}
},
"timeout": 30.0,
"enabled": true
}
},
"host": "0.0.0.0",
"port": 8000,
"log_level": "INFO",
"hot_reload": true
}
3. Start the Proxy
fastmcp-proxy start --config config.json
4. Use the Proxy
HTTP REST API
List all available tools:
curl http://localhost:8000/tools
Call a tool:
curl -X POST http://localhost:8000/tools/call \
-H "Content-Type: application/json" \
-d '{
"name": "filesystem__read_file",
"arguments": {"path": "/tmp/test.txt"}
}'
Check health:
curl http://localhost:8000/health
WebSocket
Connect to ws://localhost:8000/ws and send MCP JSON-RPC messages:
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/list"
}
Configuration Reference
Proxy Configuration
| Field | Type | Default | Description |
|---|---|---|---|
mcpServers | object | {} | Map of MCP server configurations |
host | string | "127.0.0.1" | Host to bind the server |
port | integer | 8000 | Port to bind the server |
log_level | string | "INFO" | Logging level |
hot_reload | boolean | true | Enable hot reload of configuration |
MCP Server Configuration
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Unique name for the server |
transport | string | Yes | Transport type: stdio, ws, or sse |
command | array | For stdio | Command to execute |
args | array | No | Command arguments |
env | object | No | Environment variables |
url | string | For ws/sse | WebSocket/SSE URL |
auth | object | No | Authentication configuration |
timeout | float | 30.0 | Request timeout in seconds |
retry | object | No | Retry configuration |
circuit_breaker | object | No | Circuit breaker configuration |
health_check_interval | float | 60.0 | Health check interval in seconds |
enabled | boolean | true | Whether the server is enabled |
Authentication Configuration
{
"auth": {
"type": "bearer",
"credentials": {
"token": "your-token"
}
}
}
Supported types: bearer, basic, custom
Retry Configuration
{
"retry": {
"max_attempts": 3,
"wait_min": 1.0,
"wait_max": 10.0,
"exponential_base": 2.0
}
}
Circuit Breaker Configuration
{
"circuit_breaker": {
"failure_threshold": 5,
"recovery_timeout": 60.0,
"half_open_max_calls": 1
}
}
Tool Namespacing
Tools from different backends are automatically namespaced to avoid conflicts:
- Backend
filesystemwith toolread_filebecomesfilesystem__read_file - Backend
githubwith toolsearchbecomesgithub__search
The original tool names are preserved in the backend communication.
CLI Commands
Start Server
fastmcp-proxy start --config config.json [OPTIONS]
Options:
-h, --host TEXT Host to bind (overrides config)
-p, --port INTEGER Port to bind (overrides config)
-l, --log-level LEVEL Log level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
--json-logs Output logs in JSON format
--no-hot-reload Disable hot reload
Initialize Config
fastmcp-proxy init config.json
Validate Config
fastmcp-proxy validate config.json
Docker Usage
Build Image
docker build -t fastmcp-proxy .
Run Container
docker run -p 8000:8000 \
-v $(pwd)/config.json:/etc/fastmcp-proxy/config.json \
fastmcp-proxy
Docker Compose
version: '3.8'
services:
fastmcp-proxy:
build: .
ports:
- "8000:8000"
volumes:
- ./config.json:/etc/fastmcp-proxy/config.json
environment:
- LOG_LEVEL=INFO
Development
Setup
# Install in development mode
pip install -e ".[dev]"
Run Tests
pytest
Run Tests with Coverage
pytest --cov=fastmcp_proxy --cov-report=html
Code Formatting
black fastmcp_proxy tests
Linting
ruff check fastmcp_proxy tests
Type Checking
mypy fastmcp_proxy
Architecture
βββββββββββββββ
β Client β
ββββββββ¬βββββββ
β HTTP/WebSocket
β
ββββββββΌβββββββββββββββββββ
β FastMCP Proxy β
β ββββββββββββββββββββ β
β β Connection Mgr β β
β β - Health Checks β β
β β - Hot Reload β β
β ββββββ¬ββββββββββββββ β
β β β
β ββββββΌβββββββ β
β β Router β β
β β Namespace β β
β ββββββ¬βββββββ β
βββββββββΌββββββββββββββββββ
β
ββββββ΄βββββ¬βββββββββ¬βββββββββ
β β β β
ββββΌβββ ββββΌβββ ββββΌβββ ββββΌβββ
βMCP 1β βMCP 2β βMCP 3β βMCP 4β
βstdioβ β WS β βstdioβ β WS β
βββββββ βββββββ βββββββ βββββββ
Error Handling
The proxy provides detailed error messages:
- Circuit Breaker Open: Backend is temporarily unavailable due to repeated failures
- Timeout: Request exceeded configured timeout
- Connection Error: Failed to connect to backend
- Invalid Tool: Requested tool not found
- Backend Error: Error from the backend server
License
MIT License - see LICENSE file for details.
Contributing
Contributions welcome! Please read the contributing guidelines before submitting PRs.
Support
For issues and questions, please open an issue on GitHub.
