AI MCP Gateway

Model Context Protocol (MCP) server and AI gateway that orchestrates multiple models with layered routing, database-driven configuration, and an admin dashboard.

Features

• HTTP API Gateway - Express server with N-layer, priority-based routing

• Database-driven Configuration - All settings stored in PostgreSQL

• Admin Dashboard - React-based web UI for monitoring and management

• Settings UI - Complete interface for system, providers, layers, tasks, and features

• MCP Server Mode - Standalone MCP server for Claude Desktop, VS Code

See docs/FEATURE_SUMMARY.md for complete feature list.

🚀 Quick Start (Docker)

Prerequisites

• Docker & Docker Compose

• At least one LLM provider API key (OpenRouter recommended)

1. Clone & Configure

git clone https://github.com/babasida246/ai-mcp-gateway.git
cd ai-mcp-gateway
copy .env.docker.example .env.docker

2. Edit .env.docker

Add your API keys:

OPENROUTER_API_KEY=sk-or-v1-your-key-here
# Optional: OPENAI_API_KEY, ANTHROPIC_API_KEY

3. Start Services

docker-compose up -d

4. Access Services

• API Gateway: http://localhost:3000

• Admin Dashboard: http://localhost:5173

• Settings UI: http://localhost:5173/settings

• Health Check: http://localhost:3000/health

Running Services

✅ mcp-gateway       - Main API server (port 3000)
✅ ai-mcp-dashboard  - Web UI (port 5173)
✅ ai-mcp-postgres   - PostgreSQL database (port 5432)
✅ ai-mcp-redis      - Redis cache (port 6379)

⚙️ Configuration

All configuration managed through Settings UI at http://localhost:5173/settings

Settings Tabs

1. System Config

• API settings (port, host, CORS)

• Logging configuration

• Cost tracking thresholds

• Default layer, auto-escalation

2. Provider Credentials

• Manage API keys (OpenRouter, OpenAI, Anthropic)

• Enable/disable providers

• Configure API endpoints

• Encrypted storage in PostgreSQL

3. Layer Configuration

• L0 (Free) - Free models (Llama, Grok)

• L1 (Cheap) - Affordable models (GPT-4o-mini, Gemini)

• L2 (Balanced) - Claude Haiku, GPT-4o

• L3 (Premium) - Claude Sonnet, o1-preview

• Enable/disable layers, set priorities

4. Task Configuration

• Chat - Conversational models

• Code - Code generation (Qwen Coder, DeepSeek)

• Analyze - Code review models

• Create Project - Scaffolding models

• Set preferred & fallback models per task

5. Feature Flags

• Auto-escalate between layers

• Cross-check responses

• Cost tracking

• Advanced routing features

All changes saved to PostgreSQL - No restart required!

🏗️ Local Development

Prerequisites

• Node.js 20+

• PostgreSQL 15+

• Redis 7+

Setup

npm install
copy .env.example .env

Edit .env

# Database
DB_HOST=localhost
DB_PORT=5432
DB_NAME=ai_mcp_gateway
DB_USER=postgres
DB_PASSWORD=postgres
CONFIG_ENCRYPTION_KEY=your-32-character-encryption-key-here

# Provider API Keys (at least one)
OPENROUTER_API_KEY=sk-or-v1-...
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379

# API Server
API_PORT=3000
API_HOST=0.0.0.0

Build & Run

npm run build
npm run start:api     # Start API server
# or
npm run start:mcp     # Start MCP server

🎯 Architecture

N-Layer Routing

Requests automatically route through layers based on cost/capability:

L0 (Free)     → meta-llama/llama-3.3-70b-instruct:free, x-ai/grok-4.1-fast:free
L1 (Cheap)    → google/gemini-flash-1.5, openai/gpt-4o-mini  
L2 (Balanced) → anthropic/claude-3-haiku, openai/gpt-4o
L3 (Premium)  → anthropic/claude-3.5-sonnet, openai/o1-preview

Auto-escalation: Failed requests automatically try next layer.

Task-Specific Routing

Different tasks use optimized models:

• Chat: Conversational models

• Code: Code-specialized models (Qwen Coder, DeepSeek)

• Analyze: Analysis-focused models

• Create Project: Scaffolding models

Database Schema

All configuration in PostgreSQL:

system_config         - System settings (key-value pairs)
provider_credentials  - API keys (AES-256 encrypted)
layer_config          - Layer assignments & priorities
task_config           - Task routing rules
feature_flags         - Feature toggles

📊 Admin Dashboard

Access at http://localhost:5173

Pages

• Dashboard - Real-time metrics, request volume, costs

• Settings - Complete configuration management (5 tabs)

• Monitoring - Request logs, performance analytics

• Providers - Provider status, rate limits

Settings UI Features

• ✅ Live configuration editing

• ✅ Encrypted credential storage

• ✅ Input validation

• ✅ Instant save to database

• ✅ No service restart required

• ✅ Responsive design

🔧 API Endpoints

Health & Status

GET  /health              # Health check
GET  /v1/status          # Gateway status  
GET  /v1/server-stats    # Server statistics

Configuration API

# System Config
GET    /v1/config/system
PUT    /v1/config/system

# Providers
GET    /v1/config/providers
POST   /v1/config/providers
PUT    /v1/config/providers/:id
DELETE /v1/config/providers/:id

# Layers
GET    /v1/config/layers
PUT    /v1/config/layers/:id

# Tasks
GET    /v1/config/tasks
PUT    /v1/config/tasks/:id

# Features
GET    /v1/config/features
PUT    /v1/config/features/:id

Chat & Generation

POST /v1/chat/completions    # OpenAI-compatible chat
POST /v1/generate            # Text generation
POST /v1/mcp-cli             # MCP CLI commands

📖 Documentation

Setup & Deployment

• docs/DEPLOYMENT_QUICK_START.md - Complete deployment guide

• docs/DOCKER-DEPLOYMENT.md - Docker setup details

Features & Usage

• docs/FEATURE_SUMMARY.md - All features explained

• docs/SETTINGS_UI.md - Settings UI documentation

• docs/API-GUIDE.md - API reference

Technical Details

• docs/ARCHITECTURE.md - System architecture

• docs/HYBRID_CONFIG_GUIDE.md - Configuration system

🔐 Security

Encryption

• Provider API keys encrypted with AES-256-CBC

• Encryption key from CONFIG_ENCRYPTION_KEY environment variable

• 32-character key required

Best Practices

• Never commit .env or .env.docker to git

• Use .env.example as template only

• Rotate encryption keys periodically

• Use environment variables in production

🚢 Deployment

Docker Production

# 1. Configure production environment
copy .env.docker.example .env.docker
# Edit with production API keys

# 2. Start services
docker-compose up -d

# 3. Verify health
curl http://localhost:3000/health

Environment Variables (Docker)

Required in docker-compose.yml:

environment:
  DB_HOST: postgres
  DB_PORT: 5432
  DB_NAME: ai_mcp_gateway
  DB_USER: postgres
  DB_PASSWORD: postgres
  CONFIG_ENCRYPTION_KEY: your-key-here
  OPENROUTER_API_KEY: ${OPENROUTER_API_KEY}

🛠️ Development

Project Structure

ai-mcp-gateway/
├── src/
│   ├── api/           # Express API server
│   ├── db/            # Database & bootstrap
│   ├── services/      # Business logic
│   ├── config/        # Configuration service
│   └── index.ts       # Main entry point
├── admin-dashboard/   # React admin UI
│   ├── src/
│   │   ├── pages/     # Settings.tsx, etc.
│   │   └── components/
│   └── Dockerfile
├── docker-compose.yml # Container orchestration
├── migrations/        # Database migrations
└── docs/              # Documentation

Build Commands

npm run build         # Build TypeScript
npm run dev           # Development mode
npm run start:api     # Start API server
npm run start:mcp     # Start MCP server

Database Migrations

Migrations run automatically on first startup. Manual execution:

# Local
npm run db:migrate

# Docker
docker-compose exec mcp-gateway npm run db:migrate

Dev container (avoid rebuilding on code changes)

If you want to run the API in a container during development and avoid rebuilding the image every time you change code, use the provided docker-compose.dev.yml. It builds a small image that installs dependencies once and mounts the project directory into the container so code edits are visible immediately.

Example (PowerShell):

# build the dev image (installs deps once)
docker compose -f docker-compose.dev.yml build
# run the dev container with source mounted
docker compose -f docker-compose.dev.yml up

# Now edit files locally — the container runs `npm run dev` so changes are picked up.

Notes:

• The dev compose uses a dev build target that caches dependencies. You only need to rebuild the image if you change package.json or native dependencies.

• The container preserves the image's node_modules via an anonymous volume to avoid host/permission issues on Windows.

🤝 Contributing

Contributions welcome! Please:

1. Fork the repository

2. Create feature branch (git checkout -b feature/amazing)

3. Commit changes (git commit -m 'Add amazing feature')

4. Push to branch (git push origin feature/amazing)

5. Open Pull Request

📝 License

MIT License - see LICENSE for details

🆘 Troubleshooting

Container Won't Start

Check logs:

docker-compose logs mcp-gateway

Common issues:

• Missing CONFIG_ENCRYPTION_KEY in docker-compose.yml

• Database not ready - wait for postgres healthy status

• Port conflicts - check if 3000, 5173, 5432, 6379 are available

Database Connection Failed

Verify environment:

docker-compose exec mcp-gateway printenv | Select-String "DB_"

Should show:

DB_HOST=postgres
DB_PORT=5432
DB_NAME=ai_mcp_gateway
DB_USER=postgres
DB_PASSWORD=postgres

Settings Not Saving

Check ConfigService initialization:

docker-compose logs mcp-gateway | Select-String "Configuration service"

Should see:

Configuration service initialized from database

📞 Support

• Issues: GitHub Issues

• Discussions: GitHub Discussions

• Documentation: docs/

🙏 Acknowledgments

Built with:

• Model Context Protocol - Anthropic's MCP specification

• Express - Web framework

• React - UI library

• PostgreSQL - Database

• Redis - Cache

• TypeScript - Type safety

Made with ❤️ by the AI MCP Gateway team