Content
# MCP Gateway
[](https://github.com/mcp-gateway/mcp-gateway/actions)
[](https://golang.org)
[](LICENSE)
[](https://goreportcard.com/report/github.com/mcp-gateway/mcp-gateway)
[](https://codecov.io/gh/mcp-gateway/mcp-gateway)
[](SECURITY.md)
[](CONTRIBUTING.md)
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:
```bash
# 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:
```bash
# Terminal 1: Start backend services
make dev
# Terminal 2: Start frontend locally (much faster)
cd apps/frontend
bun install
bun run dev
```
### Essential Commands
```bash
# 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:**
```bash
# 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](CONTRIBUTING.md) for details.
### Code of Conduct
This project follows the [Contributor Covenant Code of Conduct](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
## 📄 License
This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.
## 🔒 Security
Security is a top priority. Please review our [Security Policy](SECURITY.md) and report vulnerabilities responsibly.
## 🙏 Acknowledgments
- [Model Context Protocol](https://modelcontextprotocol.io/) for the core specification
- All our [contributors](https://github.com/mcp-gateway/mcp-gateway/contributors)
---
<div align="center">
<p>Built with ❤️ for the MCP community</p>
<p>
<a href="https://github.com/mcp-gateway/mcp-gateway">⭐ Star us on GitHub</a> •
<a href="https://github.com/mcp-gateway/mcp-gateway/issues">🐛 Report Bug</a> •
<a href="https://github.com/mcp-gateway/mcp-gateway/issues">💡 Request Feature</a>
</p>
</div>
Connection Info
You Might Also Like
MarkItDown MCP
Converting files and office documents to Markdown.
Time
Obtaining current time information and converting time between different...
Filesystem
Model Context Protocol Servers
Sequential Thinking
Offers a structured approach to dynamic and reflective problem-solving,...
Git
Model Context Protocol Servers
Context 7
Context7 MCP Server -- Up-to-date code documentation for LLMs and AI code editors