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 clean then make setup

🤝 Contributing

1. Fork the repository
2. Run make dev to start backend services
3. Run frontend locally: cd apps/frontend && bun run dev
4. Make your changes
5. Run make test and make lint
6. 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