A production-ready Model Context Protocol (MCP) server that provides Claude Desktop with comprehensive access to Envoy Gateway configuration, monitoring, and complete traffic management capabilities with advanced traffic control features.
The EGMCP Server bridges Claude Desktop and Envoy Gateway, enabling natural language queries and complete management of your service mesh infrastructure. It provides real-time access to listeners, routes, clusters, full route lifecycle management, and sophisticated traffic engineering capabilities.
- 🔌 Real-time Configuration Access: Live connection to Envoy Gateway admin API
- 📊 Resource Discovery: Dynamic listing of listeners, routes, and clusters
- 🛠️ Interactive Tools: 11 specialized tools for complete Envoy Gateway management
- 🔒 Robust Error Handling: Graceful degradation and timeout protection
- 🛣️ HTTPRoute Creation: Create routes via natural language
- 🗑️ Route Deletion: Remove routes with safety validation
- 🔧 Gateway Listener Management: Add/remove ports and protocols
- ⚡ Generate-Apply-Verify Pattern: Reliable write operations
- 📊 Traffic Splitting: Canary deployments with percentage-based traffic distribution
- ⚖️ Load Balancing: Configure policies (Round Robin, Least Request, Random, Ring Hash, Maglev)
- 🏥 Health Checks: Backend service health monitoring configuration
- 🛡️ Traffic Policies: Rate limiting, authentication, CORS, and timeout policies
- 🔒 Read-Only Mode: Safe monitoring without modification risk
- 🧪 Dry-Run Mode: Generate YAML manifests without applying
- ✅ Comprehensive Validation: RFC 1123 compliant resource names, hostnames, ports
- 🚫 Conflict Prevention: Duplicate resource detection with intelligent checking
- 🔐 RBAC Error Handling: Clear permission error messages with troubleshooting guidance
- 🏷️ Resource Labeling: Track EGMCP-managed resources for audit trails
- ⚡ Input Sanitization: Real-time validation in both dry-run and live modes
- 🎛️ Multi-Environment Support: Production, staging, development configs
- 🧪 Edge Case Handling: Robust error handling for production use
- 📈 Performance Optimized: Tested for responsiveness with Claude Desktop
- 🔄 Kubernetes Integration: Full Gateway API resource CRUD operations
Check out this YouTube short for a quick demo of the EGMCP server in action:
Note: Demo shows Sprint 2 features. Current version includes comprehensive route management and advanced traffic control!
📚 Complete User Guide - Comprehensive installation, configuration, and usage documentation
# Test the server directly
npx @saptak/egmcp-server stdio-tools --envoy-url http://localhost:19001
# With Kubernetes support for write operations
npx @saptak/egmcp-server stdio-tools --envoy-url http://localhost:19001 --kubernetes.kubeconfig ~/.kube/configFor Claude Desktop, configure with:
{
"mcpServers": {
"egmcp-server": {
"command": "npx",
"args": [
"@saptak/egmcp-server",
"stdio-tools",
"--envoy-url",
"http://localhost:19001",
"--kubernetes.kubeconfig",
"/Users/yourname/.kube/config"
],
"env": {}
}
}
}{
"mcpServers": {
"egmcp-server": {
"command": "npx",
"args": [
"@saptak/egmcp-server",
"stdio-tools",
"--envoy-url",
"http://localhost:19001",
"--kubernetes.kubeconfig",
"/Users/yourname/.kube/config",
"--kubernetes.read_only"
],
"env": {}
}
}
}{
"mcpServers": {
"egmcp-server": {
"command": "npx",
"args": [
"@saptak/egmcp-server",
"stdio-tools",
"--envoy-url",
"http://localhost:19001",
"--kubernetes.dry_run"
],
"env": {}
}
}
}curl -sSL https://raw.githubusercontent.com/saptak/eg-mcp-server/main/install.sh | bash# Automated setup
curl -sSL https://raw.githubusercontent.com/saptak/eg-mcp-server/main/setup-envoy.sh | bash
# Manual setup
kubectl get pods -n envoy-gateway-system
kubectl port-forward -n envoy-gateway-system pod/YOUR_ENVOY_POD 19001:19000Claude Desktop will automatically load the EGMCP server and make all tools available.
The EGMCP Server provides 11 specialized tools for comprehensive Envoy Gateway management:
- Listeners: Discover all listeners with their configurations
- Routes: Analyze traffic routing and virtual hosts
- Clusters: List backend services and clusters
- Summary: Quick configuration overview and health status
- Route Creation: Create HTTPRoute resources via natural language
- Route Deletion: Remove existing routes with safety validation
- Listener Management: Add/remove Gateway listeners (ports/protocols)
- Traffic Splitting: Canary deployments with percentage-based distribution
- Load Balancing: Configure policies (Round Robin, Least Request, etc.)
- Health Checks: Backend service monitoring configuration
- Traffic Policies: Rate limiting, authentication, CORS, timeouts
📖 For detailed tool documentation, parameters, examples, and safety features, see the Complete User Guide.
Once installed, you can ask Claude Desktop:
- "What's the current status of my Envoy Gateway?"
- "Show me all the listeners in Envoy Gateway"
- "Analyze my traffic routing configuration"
- "List all backend services available"
- "Give me a summary of the gateway configuration"
- "Create a route for my API service on api.example.com that sends traffic to api-service port 8080"
- "Add a new route named user-api for users.example.com pointing to user-service:3000"
- "Delete the route named test-route"
- "Add HTTPS support to my gateway"
- "Remove the listener on port 8080 from my gateway"
- "Shift 20% of traffic from api-v1 to api-v2 for canary testing"
- "Configure round robin load balancing for the main gateway listener"
- "Set up health checks for the user-api route with 30 second intervals"
- "Apply rate limiting of 100 requests per second to the api route"
- "Enable CORS for the frontend route allowing example.com origin"
- "Add JWT authentication to the admin route"
- "Generate YAML manifest for a new route without applying it"
- "Show me what changes would be made for traffic splitting without applying them"
- "Preview the YAML for adding health checks to my route"
- "Run in dry-run mode to validate configurations before deployment"
- "Create a route in the production namespace for payments.app.com pointing to payment-svc:8080 with path /api/v1"
- "Add an HTTPS listener on port 443 to demo-gateway"
- "Show me all routes and then create a new one for my service"
- "Gradually shift 10% of user traffic to the new recommendation service"
- "Check if there are any listeners on port 8080"
- "Find routes that point to the product-service cluster"
- "What's the configuration for the https_listener?"
- "Why isn't traffic reaching my service?"
- Operating System: macOS, Linux, Windows
- Claude Desktop: Latest version with MCP support
- Envoy Gateway: Any version with admin API enabled
- Network Access: Port forwarding or direct access to Envoy Gateway admin API
- Kubernetes Access: kubectl configuration and permissions
- Gateway API: Kubernetes cluster with Gateway API CRDs installed
- RBAC Permissions: Access to create/modify HTTPRoute and Gateway resources
- Go: 1.21+ (for building from source)
--envoy-url: Envoy Gateway admin API URL--kubernetes.kubeconfig: Path to kubeconfig file--kubernetes.read_only: Enable read-only mode (safe for production)--kubernetes.dry_run: Enable dry-run mode (generate manifests without applying)--kubernetes.default_namespace: Default namespace for operations--log-level: Logging verbosity (debug, info, warn, error)
{
"args": [
"stdio-tools",
"--envoy-url", "http://prod-envoy:19001",
"--kubernetes.kubeconfig", "/etc/kubernetes/prod-config",
"--kubernetes.read_only"
]
}{
"args": [
"stdio-tools",
"--envoy-url", "http://localhost:19001",
"--kubernetes.dry_run"
]
}📖 For complete configuration options, environment variables, multi-environment setup, and detailed examples, see the Configuration Guide.
- ✅ Check binary path is absolute:
/usr/local/bin/egmcp-server - ✅ Restart Claude Desktop after configuration changes
- ✅ Verify kubeconfig path exists and is accessible
- ✅ Run automated setup:
curl -sSL https://raw.githubusercontent.com/saptak/eg-mcp-server/main/setup-envoy.sh | bash - ✅ Test connectivity:
curl http://localhost:19001/ready
- ✅ Use read-only mode for monitoring:
--kubernetes.read_only - ✅ Check kubectl access:
kubectl get httproutes
- ✅ Resource Names: Use lowercase, numbers, hyphens only (
api-service✅,Api_Service❌) - ✅ Hostnames: Valid DNS format (
api.example.com✅,invalid hostname❌) - ✅ Ports: Must be 1-65535 (8080 ✅, 70000 ❌)
# Health check
egmcp-server health --envoy-url http://localhost:19001
# Debug mode
egmcp-server stdio-tools --log-level debug --envoy-url http://localhost:19001
# Test read-only mode
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "create_http_route", "arguments": {"name": "test", "gateway_name": "demo", "hostname": "test.local", "service_name": "svc", "service_port": 8080}}}' | \
egmcp-server stdio-tools --kubernetes.read_only📖 For comprehensive troubleshooting, detailed error solutions, validation examples, and testing procedures, see the Complete Troubleshooting Guide.
We welcome contributions!
- Issues & Feature Requests: https://github.com/saptak/eg-mcp-server/issues
This project is licensed under the MIT License - see the LICENSE file for details.
- GitHub Issues: Report bugs and request features
- Complete Documentation: User Guide
Ready to supercharge your Envoy Gateway management with Claude Desktop? Get started with NPX and experience the power of advanced traffic control! 🚀
New to EGMCP Server? Check out the comprehensive User Guide for detailed examples and use cases.