https://github.com/plwp/mcprelay
Enterprise-grade MCP gateway for secure, scalable Model Context Protocol deployments
https://github.com/plwp/mcprelay
Last synced: 5 months ago
JSON representation
Enterprise-grade MCP gateway for secure, scalable Model Context Protocol deployments
- Host: GitHub
- URL: https://github.com/plwp/mcprelay
- Owner: plwp
- License: other
- Created: 2025-06-14T08:04:00.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-06-14T11:24:22.000Z (about 1 year ago)
- Last Synced: 2025-06-14T12:29:27.065Z (about 1 year ago)
- Language: Python
- Size: 32.2 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# MCPRelay
Enterprise-grade gateway for Model Context Protocol (MCP) servers. Secure, scalable, and production-ready.
## Overview
MCPRelay is an open-source API gateway designed specifically for MCP (Model Context Protocol) servers. It provides enterprise-grade security, authentication, rate limiting, and monitoring capabilities for production MCP deployments.
## Features
- **Security First**: MCP-aware request validation and response sanitization
- **Authentication**: API key and JWT-based authentication with role-based access control
- **Rate Limiting**: Token bucket rate limiting with per-user tiers
- **Load Balancing**: Intelligent load balancing with health checks and failover
- **Monitoring**: Prometheus metrics, structured logging, and real-time dashboard
- **Easy Deployment**: Docker-based deployment with YAML configuration
- **Web Interface**: Modern admin dashboard for configuration and monitoring
## Quick Start
### Using the Quick Start Script
```bash
git clone https://github.com/plwp/mcprelay.git
cd mcprelay
./quickstart.sh
```
### Manual Installation
```bash
# Install dependencies
pip install -e .
# Create configuration
cp config.example.yaml config.yaml
# Edit config.yaml to add your MCP servers
# Start the gateway
mcprelay serve
```
### Docker Deployment
```bash
# Using Docker Compose (recommended)
docker-compose up -d
# Or run directly
docker run -p 8080:8080 -v ./config.yaml:/app/config.yaml mcprelay/mcprelay
```
## Configuration
MCPRelay uses YAML configuration. Here's a minimal example:
```yaml
# Basic server settings
host: "0.0.0.0"
port: 8080
# MCP servers to proxy to
servers:
- name: "hue-server"
url: "http://localhost:3000"
weight: 1
timeout: 30
# Authentication
auth:
enabled: true
method: "api_key"
api_keys:
admin: "your-admin-key"
# Rate limiting
rate_limit:
enabled: true
default_requests_per_minute: 60
burst_size: 10
# Security
mcp_safeguards_enabled: true
```
## Architecture
```
AI Client → MCPRelay Gateway → MCP Server(s)
↓
[Auth, Rate Limit, Load Balance, Monitor]
```
MCPRelay sits between your AI clients and MCP servers, providing:
- **Request Authentication**: Validates API keys or JWT tokens
- **Rate Limiting**: Prevents abuse with configurable limits
- **Load Balancing**: Distributes requests across healthy backend servers
- **Request Validation**: MCP-aware filtering of dangerous operations
- **Response Sanitization**: Strips sensitive data from responses
- **Monitoring**: Comprehensive metrics and logging
## API Endpoints
- `GET /health` - Health check endpoint
- `GET /metrics` - Prometheus metrics
- `POST /mcp/{path}` - Main proxy endpoint for MCP requests
- `GET /admin/` - Web administration interface
## Web Dashboard
MCPRelay includes a modern web interface for administration:
- **Dashboard**: Real-time statistics and recent activity
- **Server Management**: Add, remove, and monitor backend servers
- **Configuration**: Edit settings through the web UI
- **Logs**: View and filter system logs
- **Metrics**: Performance analytics and visualizations
Access the dashboard at `http://localhost:8080/admin/` (requires admin authentication).
## CLI Usage
```bash
# Start the server
mcprelay serve
# Validate configuration
mcprelay validate
# Check backend health
mcprelay health
# Show version
mcprelay version
```
## Security
MCPRelay provides multiple layers of security:
### MCP Safeguards
- Validates JSON-RPC requests for proper MCP format
- Blocks dangerous operations (file system access, code execution)
- Sanitizes responses to prevent data leakage
### Authentication
- API key authentication with configurable keys
- JWT token validation with proper claims checking
- Role-based access control (admin vs user permissions)
### Rate Limiting
- Token bucket algorithm with configurable rates
- Per-user rate limits
- Burst capacity for handling traffic spikes
## Monitoring
### Metrics
MCPRelay exports Prometheus metrics including:
- Request count and rate
- Response times and percentiles
- Backend server health status
- Error rates and types
### Logging
Structured JSON logging with configurable levels:
- Request/response logging
- Security event logging
- Performance metrics
- Error tracking
## Contributing
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
## License
This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.
## Support
- **Issues**: [GitHub Issues](https://github.com/plwp/mcprelay/issues)
- **Discussions**: [GitHub Discussions](https://github.com/plwp/mcprelay/discussions)
- **Documentation**: [mcprelay.org](https://mcprelay.org)