baoduy2412/mcp-proxy repository overview

⁠drunk-mcp-proxy

⁠Docs

• deep-wiki⁠
• github-docs⁠
• docker-hub⁠

A powerful, production-ready dynamic proxy server for the Model Context Protocol (MCP) and LLM APIs, built with Python and FastMCP. This service enables MCP clients and LLM-compatible applications to seamlessly connect to multiple backend MCP servers and LLM providers through a unified, scalable interface with advanced features including authentication, CORS support, and environment-based configuration.

⁠🎯 Overview

drunk-mcp-proxy acts as a central gateway for both Model Context Protocol (MCP) services and LLM providers, providing:

• Unified Interface: Single endpoint for multiple backend MCP servers and LLM providers
• Dynamic Routing: Automatic routing to configured backend services
• Namespace Isolation: Prevent tool name conflicts with per-server namespaces
• OpenAPI Integration: Automatic conversion of OpenAPI specs to MCP tools
• LLM Proxy: Multi-provider LLM API gateway with OpenAI-compatible endpoints
• Anthropic Compatibility: Proxy Anthropic Messages API requests through OpenAI-compatible backends
• WebSocket Responses API: Native WebSocket support for OpenAI Responses API streaming
• Enterprise Authentication: 14+ pluggable auth providers (JWT, OAuth, GitHub, Azure, etc.)
• Production Ready: Health checks, CORS, structured logging, Docker support

⁠✨ Key Features

• 🚀 Dynamic Proxy Management: Configure multiple MCP and OpenAPI services via YAML
• 🤖 LLM Gateway: Route requests to multiple LLM providers (OpenAI, Ollama, LM Studio, etc.)
• 🔄 Anthropic API Compatibility: Use Anthropic/Claude clients with any OpenAI-compatible backend
• 🔌 WebSocket Responses API: Full WebSocket support for OpenAI Responses API
• 🐳 Docker Support: Multi-stage production Docker image with health checks
• 🔐 Enterprise Auth: JWT, GitHub, Google, Discord, Azure OAuth, and custom auth providers
• 🌐 CORS Ready: Full CORS middleware for web client integration
• 🎨 OpenAPI Support: Convert OpenAPI specs to MCP tools automatically
• 🔍 Health Monitoring: Built-in health check endpoint
• 📊 Structured Logging: Configurable log levels
• 🛡️ JSON Schema Validation: Automatic config validation

⁠🚀 Quick Start

Get up and running with drunk-mcp-proxy using the pre-built Docker image from Docker Hub.

⁠Step 1: Prepare Configuration Files

Create a data/ directory with the required configuration files:

mkdir -p data/mcp data/openapi data/skills

⁠data/config.yaml - Unified Configuration

Define authentication, LLM providers, and MCP/OpenAPI services in a single file:

# Authentication configuration (optional)
auth:
  defaultProvider: basic
  basic:
    base_url: null
    token: $API_KEY
  jwt:
    base_url: null
    jwks_uri: "https://login.microsoftonline.com/common/discovery/keys"
    issuer: "https://sts.windows.net/$AZURE_TENANT_ID/"
    audience: "api://your-client-id"

# LLM provider configuration (optional)
llm:
  - enabled: true
    websocket: true
    provider: openai
    base_url: "https://api.openai.com/v1"
    api_key: $OPENAI_API_KEY

# MCP and OpenAPI service configuration
mcp:
  - path: /
    spec_type: mcp
    skill_dir: skills
    mcp_servers:
      my-server:
        enabled: true
        command: npx
        args: ["@playwright/[email protected]"]
        transport: stdio

  - path: /api
    spec_file: openapi/petstore.yaml
    spec_type: openapi
    base_url: "https://api.example.com"

See the samples in the repository⁠ for more configuration examples.

⁠Step 2: Prepare Docker Compose

Create a docker-compose.yml file:

services:
  mcp-proxy:
    image: baoduy2412/mcp-proxy:latest
    container_name: mcp-proxy-server
    ports:
      - "${FASTMCP_PORT:-9123}:${FASTMCP_PORT:-9123}"
    volumes:
      - ./data:/drunk-proxy/data
    env_file:
      - .env
    environment:
      - FASTMCP_HOST=0.0.0.0
      - FASTMCP_PORT=${FASTMCP_PORT:-9123}
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:9123/health"]
      interval: 30s
      timeout: 10s
      retries: 3

⁠Step 3: Configure Environment & Run

Create a .env file from the sample:

cp .env.sample .env

Edit .env with your settings. Key environment variables:

# Server Configuration
FASTMCP_PORT=9123
FASTMCP_LOG_LEVEL=INFO
FASTMCP_AUTH_ENABLED=false

# Bearer Authentication (API Key)
API_KEY=your-api-key-here

# OAuth Storage (required if using OAuth)
FASTMCP_OAUTH_STORAGE_ENCRYPTION_KEY=your-44-character-encryption-key

# Azure Authentication (if using Azure OAuth)
AZURE_CLIENT_ID=your-client-id
AZURE_CLIENT_SECRET=your-client-secret
AZURE_TENANT_ID=your-tenant-id

Now start the server:

docker-compose up -d

Verify it's running:

curl http://localhost:9123/health

⁠Additional Services (Optional)

The full docker-compose.yml⁠ in the repository includes optional services:

• MCP Inspector - Debug and inspect MCP servers
• OpenWebUI - Web interface for LLM interactions

⁠🛠️ Local Development

⁠Using Docker (Build from Source)

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

docker build -t drunk-mcp-proxy .
docker run -d -p 9123:9123 -v $(pwd)/data:/drunk-proxy/data drunk-mcp-proxy

⁠Running Locally

# Setup environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -e ".[dev]"

# Run the server
python src/main.py

The server will start on http://0.0.0.0:9123 by default.

⁠📖 Configuration

⁠Configuration Directory Structure

data/
├── config.yaml       # Unified configuration (auth, LLM, and MCP/OpenAPI services)
├── mcp/              # MCP server specifications (optional, for external spec files)
│   ├── stock.mcp.json
│   └── wiki.mcp.json
├── openapi/          # OpenAPI specifications
│   └── petstore.yaml
└── skills/           # Skill directories (optional)

⁠Configuration (config.yaml)

The proxy uses a unified YAML configuration file to define authentication, LLM providers, and MCP/OpenAPI services:

# Authentication configuration
auth:
  defaultProvider: basic
  basic:
    token: $API_KEY

# MCP service configuration
mcp:
  - path: /stock
    spec_file: mcp/stock.mcp.json
    spec_type: mcp

  - path: /api
    spec_file: openapi/petstore.yaml
    spec_type: openapi
    base_url: "https://api.example.com"
    filters:
      methods: ["GET", "POST"]
      tags: ["public"]

⁠Environment Variables

Key environment variables (see .env.sample⁠ for complete list):

See Environment Variables⁠ for complete list.

⁠📚 Documentation

• Getting Started

  • Installation Guide⁠
  • Quick Start Guide⁠
  • First Steps⁠

• Configuration

  • Configuration Files⁠
  • Environment Variables⁠
  • Schema Validation⁠

• Features

  • MCP Proxy Management⁠
  • OpenAPI Integration⁠
  • Authentication⁠
  • Pass-Through Authentication⁠

• Architecture

  • System Architecture⁠
  • Component Overview⁠
  • Request Flow⁠

• API Reference

  • REST API Endpoints⁠
  • Python Modules⁠

• Deployment

  • Docker Deployment⁠
  • Production Setup⁠
  • Health Checks & Monitoring⁠

• Development

  • Development Guide⁠
  • Testing⁠
  • Troubleshooting⁠

For comprehensive documentation, see the Documentation Index⁠.

⁠🏗️ Architecture Overview

MCP Client / LLM Client / Anthropic Client
        ↓ (HTTP/SSE/WebSocket + Authorization)
        ↓
┌──────────────────────────────────────────────┐
│  drunk-mcp-proxy Server                      │
│ ┌────────────────────────────────────────┐  │
│ │ Starlette ASGI Application             │  │
│ │ • CORS Middleware                      │  │
│ │ • Auth Validation                      │  │
│ │ • Rate Limiting                        │  │
│ │ • Health Check: /health                │  │
│ │ • Root FastMCP Server (/)              │  │
│ │ • MCP Sub-services:                    │  │
│ │   - /stock (MCP)                       │  │
│ │   - /wiki (MCP)                        │  │
│ │   - /api (OpenAPI)                     │  │
│ │ • LLM Proxy (/api/v1):                │  │
│ │   - POST /chat/completions             │  │
│ │   - POST /messages (Anthropic API)     │  │
│ │   - WS   /responses (WebSocket)        │  │
│ │   - POST /embeddings                   │  │
│ │   - POST /images/generations           │  │
│ │   - POST /audio/transcriptions         │  │
│ │   - POST /audio/translations           │  │
│ │   - GET  /models                       │  │
│ │   - GET  /providers                    │  │
│ └────────────────────────────────────────┘  │
└──────────────────────────────────────────────┘
        ↓ ↓ ↓
   [Backend MCP/OpenAPI/LLM Services]

See System Architecture⁠ for detailed diagrams.

⁠🔐 Authentication

drunk-mcp-proxy supports 14+ authentication providers:

• Token-based: Bearer (API Keys), JWT
• OAuth 2.0: Azure AD, GitHub, Google, Discord, Auth0
• Enterprise: WorkOS, Scalekit, Descope
• Custom: Pass-through, Introspection

⁠Bearer Authentication (API Key)

The simplest option for API key authentication, commonly used by API proxies and gateways:

auth:
  defaultProvider: basic
  basic:
    token: $API_KEY

Set the API_KEY environment variable in your .env file.

⁠OAuth 2.0 Authentication (Azure AD Example)

auth:
  defaultProvider: azure
  azure:
    client_id: $AZURE_CLIENT_ID
    client_secret: $AZURE_CLIENT_SECRET
    tenant_id: $AZURE_TENANT_ID

See Authentication Guide⁠ for details.

⁠🧪 Testing

# Run all tests
python -m pytest

# Run specific test file
python -m pytest tests/test_server.py

# Run with coverage
python -m pytest --cov=src --cov-report=html

⁠🤖 LLM Proxy

When LLM providers are configured, drunk-mcp-proxy exposes a full OpenAI-compatible LLM gateway at /api/v1. All endpoints use the model ID format provider_modelname (e.g., openai_gpt-4o, lms_llama3.2) to route requests to the appropriate backend.

⁠LLM Provider Configuration

Add providers to the llm section of config.yaml:

llm:
  - enabled: true
    websocket: true       # Enable for providers that support native WebSocket Responses API
                          # When false, HTTP Responses API is used as fallback
    provider: openai      # Short provider name used as prefix in model IDs
    base_url: "https://api.openai.com/v1"
    api_key: $OPENAI_API_KEY

  - enabled: true
    websocket: false
    provider: lms         # LM Studio
    base_url: "http://host.docker.internal:1234/v1"

  - enabled: false
    provider: oll         # Ollama
    base_url: "http://host.docker.internal:11434/v1"

⁠Model ID Format

All LLM endpoints expect the model ID to include a provider prefix separated by an underscore:

{provider}_{model_name}

Examples:

• openai_gpt-4o → routes to the openai provider, model gpt-4o
• lms_llama3.2 → routes to the lms (LM Studio) provider, model llama3.2
• ort_claude-3-5-sonnet → routes to the ort (OpenRouter) provider, model claude-3-5-sonnet

⁠Available Endpoints

All endpoints are mounted at /api/v1 (configurable via FASTMCP_LLM_ROUTE_PREFIX):

⁠Chat Completions

Standard OpenAI-compatible chat completions:

curl -X POST http://localhost:9123/api/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "openai_gpt-4o",
    "messages": [{"role": "user", "content": "Hello!"}],
    "stream": false
  }'

⁠Anthropic Messages API Compatibility

The /messages endpoint accepts Anthropic Messages API format and transparently converts to/from the OpenAI format, letting Anthropic/Claude clients use any OpenAI-compatible backend:

curl -X POST http://localhost:9123/api/v1/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "lms_llama3.2",
    "messages": [{"role": "user", "content": "Hello!"}],
    "max_tokens": 1024
  }'

Supported conversions:

• System prompts (string and block array)
• Multimodal content (text, base64 images, URL images)
• Tool use and tool results
• Streaming SSE events in Anthropic format
• stop_sequences → stop, metadata.user_id → user, finish reason mapping

⁠Use with Claude Code CLI

Point the Claude Code CLI at the proxy to use any backend model with the Anthropic-compatible endpoint:

export ANTHROPIC_BASE_URL=http://localhost:9123/api/v1
export ANTHROPIC_AUTH_TOKEN=YOUR_API_KEY_HERE
claude --model lms_llama3.2

⁠WebSocket Responses API

The /responses WebSocket endpoint provides OpenAI Responses API streaming. Clients connect via WebSocket and exchange JSON messages using the OpenAI Responses API protocol.

Connection URL: ws://localhost:9123/api/v1/responses

Message flow:

1. Client connects with Authorization: Bearer <token> header
2. Client sends a response.create event with model: "provider_modelname"
3. Proxy routes to the configured backend and streams response events back
4. For providers with websocket: true, native WebSocket is used for lowest latency
5. For other providers, the HTTP Responses API is used as fallback

const ws = new WebSocket("ws://localhost:9123/api/v1/responses", {
  headers: { "Authorization": "Bearer YOUR_API_KEY" }
});

ws.send(JSON.stringify({
  type: "response.create",
  response: {
    model: "openai_gpt-4o",
    instructions: "You are a helpful assistant.",
    input: [{ type: "message", role: "user", content: "Hello!" }]
  }
}));

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log(data.type, data);  // response.created, response.output_text.delta, response.done, etc.
};

Provider WebSocket support: Set websocket: true in the provider config for providers that natively support the /responses WebSocket endpoint (e.g., OpenAI). For all other providers, the HTTP Responses API is used as a fallback.

⁠List Models and Providers

# List all models across all configured providers
curl http://localhost:9123/api/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

# Filter by provider
curl "http://localhost:9123/api/v1/models?provider=openai" \
  -H "Authorization: Bearer YOUR_API_KEY"

# List configured providers
curl http://localhost:9123/api/v1/providers \
  -H "Authorization: Bearer YOUR_API_KEY"

⁠🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

⁠📄 License

This project is licensed under the MIT License - see the LICENSE⁠ file for details.

⁠🙏 Acknowledgments

• Built with FastMCP⁠ framework
• Powered by Starlette⁠ ASGI framework
• Authentication via FastMCP's pluggable auth system

⁠📞 Support

• 📖 Documentation⁠
• 🐛 Issue Tracker⁠
• 💬 Discussions⁠

Note: For detailed technical documentation, API references, and advanced configuration, please refer to the comprehensive documentation⁠.