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

2. Edit .env.docker

Add your API keys:

3. Start Services

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

⚙️ 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

Edit .env

Build & Run

🎯 Architecture

N-Layer Routing

Requests automatically route through layers based on cost/capability:

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:

📊 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

Configuration API

Chat & Generation

📖 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

Environment Variables (Docker)

Required in docker-compose.yml:

🛠️ Development

Project Structure

Build Commands

Database Migrations

Migrations run automatically on first startup. Manual execution:

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):

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:

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:

Should show:

Settings Not Saving

Check ConfigService initialization:

Should see:

📞 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