FastMCP Proxy Server

This project provides a simple and flexible proxy server built with FastMCP. It is designed to expose one or more underlying MCP (Model Context Protocol) servers over various transport protocols, making them accessible to a wider range of clients.

The server is containerized using Docker for easy and consistent deployment, optimized for production environments.

Features

Multiple Transports: Expose MCP servers over stdio, sse (Server-Sent Events), or http.
Flexible Configuration: Easily configure which MCP servers to proxy by editing the servers.json file.
Lightweight & Fast: Built on the efficient FastMCP library and runs in a small Alpine Linux container.
Production Ready: Optimized Docker configuration for production deployment.
MCP Server Support: Supports both Node.js (npx) and Python (uvx) based MCP servers.

Requirements

Docker and Docker Compose

How to Run

This project is designed for production deployment using Docker. You can run it using either Docker Compose or direct Docker commands:

Prerequisites

Clone the repository:

git clone https://github.com/sokunmin/mcp-proxy.git
cd mcp-proxy

Method 1: Using Docker Compose (Recommended)

The easiest way to run the proxy with predefined configuration:

# Run with default settings (SSE transport, port 8000)
docker-compose up --build

# Run in background
docker-compose up -d --build

# Stop the service
docker-compose down

Override Environment Variables

You can override the default transport without editing files:

# Run with HTTP transport
TRANSPORT=http PORT=8001 docker-compose up

# Run with custom port
PORT=9000 docker-compose up

# Run with multiple overrides
TRANSPORT=http PORT=8080 docker-compose up

Method 2: Using Docker Run

For more control over the container configuration:

Step 1: Build the Image

docker build -t mcp-proxy .

Step 2: Run the Container

Option A: Using environment variables directly

# SSE Transport (Default)
docker run -d --name mcp-proxy \
  -p 8000:8000 \
  -e TRANSPORT=sse \
  -e HOST=0.0.0.0 \
  -e PORT=8000 \
  -e TZ=Etc/UTC \
  mcp-proxy

# HTTP Transport
docker run -d --name mcp-proxy-http \
  -p 8001:8001 \
  -e TRANSPORT=http \
  -e HOST=0.0.0.0 \
  -e PORT=8001 \
  -e TZ=Etc/UTC \
  mcp-proxy

Option B: Using .env file with consistent PORT variable

# Load environment variables from .env file
source .env

# Run with loaded variables
docker run -d --name mcp-proxy \
  -p ${PORT}:${PORT} \
  -e TRANSPORT=${TRANSPORT} \
  -e HOST=${HOST} \
  -e PORT=${PORT} \
  -e TZ=${TZ} \
  mcp-proxy

# For HTTP transport, override specific variables
TRANSPORT=http PORT=8001 docker run -d --name mcp-proxy-http \
  -p ${PORT}:${PORT} \
  -e TRANSPORT=${TRANSPORT} \
  -e HOST=${HOST} \
  -e PORT=${PORT} \
  -e TZ=${TZ} \
  mcp-proxy

Option C: Using --env-file

# Use .env file directly
docker run -d --name mcp-proxy \
  --env-file .env \
  -p 8000:8000 \
  mcp-proxy

# Override specific variables
docker run -d --name mcp-proxy-http \
  --env-file .env \
  -e TRANSPORT=http \
  -e PORT=8001 \
  -p 8001:8001 \
  mcp-proxy

Container Management

# View logs
docker logs mcp-proxy

# Stop the container
docker stop mcp-proxy

# Remove the container
docker rm mcp-proxy

# View running containers
docker ps

Environment Variables

The following environment variables can be configured in the .env file or passed directly:

TRANSPORT: Transport protocol (sse, http, stdio) - Default: sse
HOST: Host to bind to - Default: 0.0.0.0
PORT: Port number for the service - Default: 8000
TZ: Timezone - Default: Etc/UTC

Quick Start Examples

# Default SSE on port 8000
docker-compose up

# HTTP on port 8001
TRANSPORT=http PORT=8001 docker-compose up

# Custom port
PORT=9000 docker-compose up

# Run in background
docker-compose up -d

Configuration

To configure the proxy, edit the servers.json file. You can add, remove, or modify the MCP servers that you want to expose.

{
  "mcpServers": {
    "context7": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    },
    "fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"]
    },
    "time": {
      "transport": "stdio",
      "command": "uvx",
      "args": ["mcp-server-time", "--local-timezone", "Etc/UTC"]
    }
  }
}

The servers.json file is mounted as a volume, so changes take effect on container restart.

How to Test

You can test the running proxy using any MCP-compliant client or a tool like curl.

Testing SSE Transport (Port 8000)

# Test the SSE endpoint
curl http://localhost:8000/sse/

# Check server health
curl http://localhost:8000/

Testing HTTP Transport (Port 8001)

# Test the HTTP endpoint
curl http://localhost:8001/

# Check server health
curl http://localhost:8001/

Testing with Different Services

# Test SSE service
docker-compose up mcp-proxy-sse
curl http://localhost:8000/sse/

# Test HTTP service
docker-compose up mcp-proxy-http
curl http://localhost:8001/

Testing MCP Servers

The proxy currently supports these MCP servers:

context7: Document search and context retrieval (Node.js via npx)
fetch: Web content fetching (Python via uvx)
time: Time and timezone operations (Python via uvx)

All servers are automatically started by the proxy when needed.

Production Deployment

Docker Configuration Details

Base Image: ghcr.io/astral-sh/uv:python3.12-alpine
Optimized: Small size, production-ready
Security: Runs as non-root user
Environment: Configurable via environment variables

Best Practices

Use environment variables for configuration instead of modifying files
Mount servers.json as a volume for easy configuration updates
Use Docker Compose for consistent deployment
Monitor logs using docker-compose logs -f
Use health checks to ensure service availability

Scaling

For high-availability deployment, consider:

Using multiple replicas behind a load balancer
Implementing proper logging and monitoring
Using container orchestration (Kubernetes, Docker Swarm)

Troubleshooting

Common Issues

Port conflicts: Make sure ports 8000/8001 are not in use by other applications
Container build issues: Use docker-compose down and docker-compose up --build to force a clean rebuild
Configuration errors: Check servers.json syntax and ensure all required fields are present

Monitoring

Check service health:

# View logs
docker-compose logs -f mcp-proxy-sse

# Check container status
docker-compose ps

# Access container shell (if needed)
docker-compose exec mcp-proxy-sse sh

Contributing

Contributions are welcome! Please feel free to submit a pull request or open an issue to discuss any changes.

For development setup, please use the dev branch which includes development-optimized configurations.

mcp-proxy

README Documentation