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 filesystem with tool read_file becomes filesystem__read_file
• Backend github with tool search becomes github__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.