A flexible and extensible proxy gateway for MCP (Model Context Protocol) servers, providing enterprise-grade middleware capabilities including authentication, authorization, rate limiting, and observability.
- Multiple Auth Providers: Okta OAuth2/JWT
- Role-Based Permissions: Fine-grained tool access control
- attribute-to-Role Mapping: Flexible user permission assignment
- JWT Token Verification: Secure token validation
- Multiple Storage Backends: Memory (dev), PostgreSQL
- RESTful Admin API: Dynamic configuration management
- Prometheus Metrics: Built-in observability
- Structured Logging: JSON and text output formats
- Health Endpoints: Container orchestration support
- YAML Configuration: Environment variable substitution
- CLI Flags: Override any configuration option
- Hot Configuration: Runtime proxy/role management via API
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ AI Client │───▶│ MCP Gateway │───▶│ MCP Server │
│ (Claude, etc.) │ │ │ │ (n8n, etc.) │
└─────────────────┘ │ ┌───────────┐ │ └─────────────────┘
│ │ │ │
│ │Okta Auth │ │ ┌─────────────────┐
│ │ Roles │ │───▶│ Another Server │
│ │ Metrics │ │ └─────────────────┘
│ └───────────┘ │
└─────────────────┘
# Clone and run without authentication
git clone https://github.com/matthisholleville/mcp-gateway.git
cd mcp-gateway
# Run without authentication
go run main.go serve \
--log-format=text \
--log-level=debug # Pull the latest image
docker pull ghcr.io/matthisholleville/mcp-gateway:latest
# Run with environment variables
docker run -p 8082:8082 \
ghcr.io/matthisholleville/mcp-gateway:latest serve# Start PostgreSQL
docker-compose up -d postgres
# Run migrations
go run main.go migrate up \
--backend-engine=postgres \
--backend-uri='postgresql://mcp-gateway:changeme@localhost:5439/mcp-gateway?sslmode=disable'
# Start server with PostgreSQL backend
go run main.go serve \
--log-format=text \
--log-level=debug \
--backend-engine=postgres \
--backend-uri='postgresql://mcp-gateway:changeme@localhost:5439/mcp-gateway?sslmode=disable' \
--backend-encryption-key=0123456789abcdeffedcba9876543210cafebabefacefeeddeadbeef00112233helm repo add mcp-gateway https://matthisholleville.github.io/mcp-gateway
helm install mcp-gateway mcp-gateway/mcp-gateway- CLI Flags (highest priority)
- Environment Variables (
MCP_GATEWAY_*) - YAML Configuration File (
config/config.yaml) - Default Values (lowest priority)
# config/config.yaml
server:
url: "http://localhost:8082"
# Authentication
authProvider:
enabled: true
name: "okta"
okta:
issuer: "https://custom-xxx.okta.com/oauth2/default"
orgUrl: "https://custom-xxx.okta.com"
clientId: "xxx"
privateKey: "-----BEGIN PRIVATE KEY-----xxx-----END PRIVATE KEY-----"
privateKeyId: "xxx"
oauth:
enabled: true
provider: "okta"
authorizationServers:
- "https://custom-xxx.okta.com/oauth2/default"
bearerMethodsSupported: ["Bearer"]
scopesSupported: ["openid", "email", "profile"]
# Storage backend
backendConfig:
engine: "memory" # "postgres" coming soon
# uri: "postgres://user:pass@localhost/mcp_gateway"
# Proxy configuration
proxy:
cacheTTL: 300s
heartbeat:
enabled: true
intervalSeconds: 10sAll configuration options can be set via environment variables with MCP_GATEWAY_ prefix:
export MCP_GATEWAY_AUTH_PROVIDER_ENABLED=true
export MCP_GATEWAY_OAUTH_ENABLED=truego run main.go serve \
--auth-provider-name=okta \
--okta-issuer=https://your-domain.okta.com/oauth2/default \
--okta-org-url=https://your-domain.okta.com \
--okta-client-id=your-client-id
--okta-private-key="-----BEGIN RSA PRIVATE KEY-----\n..."
--okta-private-key-id="akXpH7Ha5VKCe2kNT3eCPn_YRaJ0..."- Usage: Development and testing
- Persistence: None (data lost on restart)
- Configuration:
--backend-engine=memory
- Usage: Production environments
- Persistence: Full durability
- Configuration:
--backend-engine=postgres --backend-uri=postgres://...
You can update the admin API Key with --http-admin-api-key flag
The gateway provides RESTful APIs for runtime configuration management:
Swagger is available at http://localhost:8082/swagger/index.html
# List all proxies
curl -H "X-API-Key: your-api-key" http://localhost:8082/v1/admin/proxies
# Add/Update proxy
curl -X PUT -H "X-API-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{"name":"n8n","type":"streamable-http","connection":{"url":"http://n8n:5678"}}' \
http://localhost:8082/v1/admin/proxies/n8nobjectTypecan be*ortoolsobjectNameis the tool name ifobjectTypeistools. Can be*or your object nameproxyis the proxy name. Can be*or your proxy name
# Create role
curl -X PUT -H "X-API-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{"name":"admin","permissions":[{"objectType":"*","proxy":"*","objectName":"*"}]}' \
http://localhost:8082/v1/admin/rolesattributeKeyis the key in your JWTattributesattributeValueis the attribute valuerolesis the list of roles. You must create the roles before creating the attribute-to-role mapping
# Map user attributes to roles
curl -X PUT -H "X-API-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{"attributeKey":"groups","attributeValue":"admins","roles":["admin"]}' \
http://localhost:8082/v1/admin/attribute-to-roles| Endpoint | Method | Description |
|---|---|---|
/mcp |
POST | MCP protocol endpoint |
/live |
GET | Liveness probe |
/ready |
GET | Readiness probe |
/metrics |
GET | Prometheus metrics |
/swagger/* |
GET | API Documentation |
/v1/admin/proxies |
GET, PUT, DELETE | Proxy management |
/v1/admin/roles |
GET, PUT, DELETE | Role management |
/v1/admin/attribute-to-roles |
GET, PUT, DELETE | attribute mapping |
- Go 1.24.3+
- Docker (optional)
- Make
# Install dependencies
make deps
# Run in development
make dev
# Build binary
make build
# Run tests
make test
# Generate coverage
make test-cover
# Build Docker image
make docker-buildThe gateway searches for config.yaml in:
/etc/mcp-gateway/$HOME/.mcp-gateway/./config/
--log-format # text, json
--log-level # debug, info, warn, error
--log-timestamp-format # Format for logging timestamps
--auth-provider-enabled # Enable authentication
--auth-provider-name # okta
--oauth-enabled # Enable OAuth2
--backend-engine # memory, postgres
--http-addr # Server address (default: :8082)
--http-admin-api-key # Admin API key for MCP Gateway configuration--proxy-cache-ttl # TTL for the proxy cache
--proxy-heartbeat-interval # Interval for the proxy heartbeat--backend-uri # URI for the auth backend
--backend-username # The username to use for the auth backend. It will override the username in the URI if provided.
--backend-password # The password to use for the auth backend. It will override the password in the URI if provided.
--backend-max-open-conns # Maximum number of open database connections
--backend-max-idle-conns # Maximum number of idle connections in pool
--backend-conn-max-idle-time # Maximum time a connection may be idle
--backend-conn-max-lifetime # Maximum time a connection may be reused--oauth-authorization-servers # OAuth authorization servers
--oauth-resource # OAuth resource (e.g. http://localhost:8082)
--oauth-bearer-methods-supported # Bearer methods supported for OAuth
--oauth-scopes-supported # OAuth scopes supported (e.g. openid,email,profile)--okta-issuer # Okta authorization server
--okta-org-url # Okta organization URL
--okta-client-id # Okta client ID
--okta-private-key # Private key for client auth
--okta-private-key-id # Private key IDWe welcome contributions! Please see CONTRIBUTING.md for guidelines.
Licensed under the Apache License 2.0 - see LICENSE for details.
Made with ❤️ by Matthis Holleville