MCP Gateway
A production-ready API gateway for Model Context Protocol (MCP) servers, providing enterprise-grade infrastructure with authentication, logging, rate limiting, server discovery, and multi-protocol transport support.
🚀 Quick Start
Get the entire MCP Gateway stack running with a single command:
# Clone the repository
git clone https://github.com/mcp-gateway/mcp-gateway.git
cd mcp-gateway
# Copy env vars
cp .env.example .env
# Option 1: Using Docker Compose directly
docker compose up --build
# Option 2: Using Makefile (automatically detects docker compose vs docker-compose)
make setup
Access the application:
- Backend:
http://localhost:8080 - Frontend:
http://localhost:3000 - Admin user:
admin@admin.com/qwerty123
Architecture
The MCP Gateway is designed with a modular architecture for scalability and maintainability:
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Users │ │ AI Agents │ │ AI Agents │
│ (Web/Mobile) │ │ (External) │ │ (Internal) │
└─────────┬───────┘ └─────────┬───────┘ └─────────┬───────┘
│ │ │
└──────────────────────┼──────────────────────┘
│
┌─────────────▼─────────────┐
│ MCP Gateway │
│ │
│ ┌─────────────────────┐ │
│ │ Security Layer │ │
│ │ • JWT Auth │ │
│ │ • RBAC & Policies │ │
│ │ • API Key Mgmt │ │
│ │ • Rate Limiting │ │
│ └─────────────────────┘ │
│ │
│ ┌─────────────────────┐ │
│ │ Middleware │ │
│ │ • Content Filtering │ │
│ │ • Audit Logging │ │
│ │ • CORS & Headers │ │
│ │ • Request Tracking │ │
│ └─────────────────────┘ │
│ │
│ ┌─────────────────────┐ │
│ │ Core Services │ │
│ │ • Server Discovery │ │
│ │ • Namespace Manager │ │
│ │ • Transport Proxy │ │
│ │ • Virtual Servers │ │
│ │ • Logging & Metrics │ │
│ └─────────────────────┘ │
└─────────────┬─────────────┘
│
┌──────────────────────┼──────────────────────┐
│ │ │
┌──────▼──────┐ ┌──────▼──────┐ ┌──────▼──────┐
│ namespace-1 │ │ namespace-2 │ │ namespace-3 │
│ │ │ │ │ │
│┌───────────┐│ │┌───────────┐│ │┌───────────┐│
││MCP Server ││ ││MCP Server ││ ││Virtual ││
││ A ││ ││ C ││ ││Server A ││
│└───────────┘│ │└───────────┘│ │└───────────┘│
│┌───────────┐│ │┌───────────┐│ │┌───────────┐│
││MCP Server ││ ││MCP Server ││ ││Virtual ││
││ B ││ ││ D ││ ││Server B ││
│└───────────┘│ │└───────────┘│ │└───────────┘│
└─────────────┘ └─────────────┘ └─────────────┘
Features
🔐 Security & Authentication
- Authentication - Secure authentication (JWT, OAuth2, OIDC) with RBAC
- API Key Management - Role-based access control with fine-grained permissions
- Rate Limiting - IP-based limiting with Redis backing and memory fallback
- Content Filtering - PII detection, regex patterns, and custom filters
🏢 Server & Namespace Management
- Dynamic Discovery - Automatic MCP server discovery and registration
- Namespaces - Group servers with isolated namespaces for internal & external usage
- Health Monitoring - Server health checks with automated failover and recovery
- Public Endpoints - Auto-generated REST APIs for namespace access
🔌 Multi-Protocol Transport
- JSON-RPC 2.0 - Standard synchronous RPC over HTTP
- WebSocket - Full-duplex bidirectional communication
- Server-Sent Events - Real-time server-to-client streaming
- Streamable HTTP - Official MCP protocol implementation
- STDIO - Command-line interface bridge
🌐 Service Virtualization
- Protocol Support - REST APIs, GraphQL (coming soon), gRPC (coming soon)
- MCP Integration - Transform any HTTP service into MCP tools with schema validation
- Example Integrations - Internal API docs, microservers, etc.
📊 Logging, Auditing & Metrics
- Audit Trails - Complete request/response logging with security event tracking
- Performance Metrics - Real-time monitoring with health checks and alerting
- External Integration - AWS CloudWatch, file-based logging, and custom exporters
- Session Tracking - Live session management with detailed interaction logs
🛠️ Development
Quick Development Setup
Fast development with backend in Docker and frontend running locally:
# Terminal 1: Start backend services
make dev
# Terminal 2: Start frontend locally (much faster)
cd apps/frontend
bun install
bun run dev
Essential Commands
# Development
make dev # Start backend services (postgres, redis, backend)
make setup # Complete setup (DB + admin + orgs + namespaces)
make start # Production-ready local setup with services
make stop # Stop all services
make clean # Stop and remove all data
make logs # View service logs
make help # Show all available commands
# Database Operations
make migrate # Run database migrations
make migrate-down # Rollback migrations
make migrate-status # Show migration status
make db-shell # Open PostgreSQL shell
# Testing & Quality
make test # Run all tests
make lint # Run linters
# Build & Utilities
make build # Build containers
make rebuild # Rebuild and restart containers
make shell # Open shell in backend container
make bash # Open bash in backend container
Troubleshooting
Docker Compose Issues:
# The Makefile automatically detects your Docker Compose version
# Check what it's using:
make help # Will work with either docker-compose or docker compose
# Manual check:
docker compose version # Modern v2
docker-compose version # Legacy v1
# If you get "command not found":
# Install Docker Desktop (includes Compose v2) or standalone Compose
Common Issues:
- Port conflicts: Stop other services on ports 8080, 3000, 5432, 6379
- Permission denied: Ensure Docker daemon is running
- Build failures: Try
make cleanthenmake setup
🤝 Contributing
- Fork the repository
- Run
make devto start backend services - Run frontend locally:
cd apps/frontend && bun run dev - Make your changes
- Run
make testandmake lint - Submit a Pull Request
Please see our Contributing Guidelines for details.
Code of Conduct
This project follows the Contributor Covenant Code of Conduct.
📄 License
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.
🔒 Security
Security is a top priority. Please review our Security Policy and report vulnerabilities responsibly.
🙏 Acknowledgments
- Model Context Protocol for the core specification
- All our contributors
Built with ❤️ for the MCP community