MCP-AI-Gateway

Unified local MCP AI Gateway that routes across Groq, OpenRouter, Mistral, and local Ollama providers, with OpenAI-compatible APIs, MCP tools, fallback/racing router, monitoring, and web dashboard.

🚀 Features

• Async Python gateway with provider abstraction layer
• Built-in providers:
  • Groq (openai/gpt-oss-120b default, plus moonshotai/kimi-k2-instruct-0905)
  • OpenRouter (openai/gpt-4o-mini default)
  • Mistral (codestral-latest default, plus devstral-medium-latest)
  • Ollama
• Intelligent router:
  • priority routing
  • fallback routing
  • parallel racing mode
  • rate-limit aware provider scoring
• MCP server capabilities:
  • tool registration/discovery
  • prompt template discovery/rendering
  • schema validation
  • SSE and HTTP transport
• OpenAI-compatible API:
  • POST /v1/chat/completions
  • POST /v1/completions
  • GET /v1/models
• Web UI (React + Vite + Tailwind):
  • Dashboard
  • Providers
  • Models
  • Chat
  • Logs
  • Stats
  • Runtime gateway API key generation
• Observability:
  • Prometheus metrics (/metrics)
  • structured logs
  • SQLite request statistics
• Extensible plugin system for additional providers
• CLI: mcp-ai start|stop|status|providers|models
• Docker + docker-compose support
• GitHub Actions CI for backend lint/tests and frontend build

🗂️ Repository Structure

mcp-ai-gateway/
  api/
  providers/
  router/
  mcp_server/
  plugins/
  database/
  web_ui/
  config/
  cli/
  tests/
  Dockerfile
  docker-compose.yml
  README.md

⚡ Quick Start (Local)

1) 📦 Prerequisites

• Python 3.11+
• Node.js 20+
• Optional: local Ollama daemon at http://localhost:11434

2) 🐍 Install backend

python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -e .[dev]

3) 🔐 Configure environment

cp .env.example .env
# edit .env values

4) ⚙️ Edit config

config/config.yaml controls providers, routing, security, and default models.

5) ▶️ Start backend

uvicorn api.main:app --host 0.0.0.0 --port 8000 --reload

6) 🖥️ Start web UI

cd web_ui
npm install
VITE_API_BASE=http://localhost:8000 VITE_API_KEY=change-me npm run dev

Open http://localhost:3000

🐳 Docker Deployment

docker compose up --build

Services:

• Gateway API: http://localhost:8000
• Web UI: http://localhost:3000
• Redis: localhost:6379 (optional cache/rate-limit backend)

🧩 API Overview

OpenAI-Compatible 🤝

• POST /v1/chat/completions
• POST /v1/completions
• GET /v1/models

Use header X-API-Key: <key> (or Authorization: Bearer <key>).

MCP Endpoints 🔌

• JSON-RPC MCP transport: POST /mcp
• SSE streaming output: POST /mcp/stream

Supported MCP methods:

• initialize
• notifications/initialized
• ping
• tools/list
• tools/call
• prompts/list
• prompts/get

Dashboard APIs 📊

• GET /api/dashboard
• GET /api/providers
• POST /api/providers/{name}/toggle
• POST /api/providers/{name}/priority
• POST /api/providers/{name}/config
• GET /api/models
• GET /api/settings
• POST /api/settings/default-model
• POST /api/settings/api-key/generate
• GET /api/logs
• GET /api/stats

Monitoring 📈

• GET /health
• GET /metrics

🛠️ CLI

mcp-ai start
mcp-ai status
mcp-ai providers
mcp-ai models
mcp-ai stop

🧭 Warp MCP Integration

Add this to Warp MCP config:

{
  "mcpServers": {
    "mcp-ai-gateway": {
      "url": "http://localhost:8000/mcp",
      "headers": {
        "Authorization": "Bearer REPLACE_WITH_MCP_GATEWAY_API_KEY"
      }
    }
  }
}

🧱 Configuration Example

providers:
  groq:
    enabled: true
    api_key: ${GROQ_API_KEY}
    priority: 1
    default_model: openai/gpt-oss-120b
  mistral:
    enabled: false
    api_key: ${MISTRAL_API_KEY}
    priority: 12
    default_model: codestral-latest
  openrouter:
    enabled: true
    priority: 2
    default_model: openai/gpt-4o-mini
  ollama:
    enabled: true
    priority: 3
routing:
  fallback_enabled: true
  racing_mode: false

🧪 Plugin Providers

New providers can be added under plugins/ by implementing ProviderPlugin and enabling provider config in config/config.yaml.

Included plugin examples:

• openai_provider.py
• together_provider.py
• openrouter_provider.py

✅ Testing

pytest

CI runs on pushes and pull requests to main via .github/workflows/ci.yml:

• Backend job: ruff check . and pytest -q
• Frontend job: npm install and npm run build in web_ui/

🔄 Release Workflow

• Open PR from dev/* branch to main
• Ensure CI is green
• Merge using GitHub CLI or GitHub UI

📚 Developer Guide

Detailed guide: docs/developer-guide.md