eg-mcp-server

saptak/eg-mcp-server

3.3

If you are the rightful owner of eg-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The EGMCP Server is a production-ready Model Context Protocol server that integrates with Claude Desktop to manage Envoy Gateway configurations, offering advanced traffic control and monitoring capabilities.

Tools
11
Resources
0
Prompts
0

EGMCP Server - Envoy Gateway MCP Server

NPM Version GitHub Release License: MIT

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.

🎯 Overview

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.

✨ Key Features

🔍 Monitoring & Discovery

  • 🔌 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

🚀 Route Management

  • 🛣️ 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

🎯 Advanced Traffic Control

  • 📊 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

🛡️ Production Safety

  • 🔒 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

⚡ Enhanced Capabilities

  • 🎛️ 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

🎬 Watch the Demo

Check out this YouTube short for a quick demo of the EGMCP server in action:

EGMCP Server Demo

Note: Demo shows Sprint 2 features. Current version includes comprehensive route management and advanced traffic control!

📖 Documentation

- Comprehensive installation, configuration, and usage documentation

🚀 Quick Start

1. Install EGMCP Server

Option A: NPX Installation (Recommended - No Install Required)
# 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/config

For 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": {}
    }
  }
}
For Read-Only Monitoring:
{
  "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": {}
    }
  }
}
For GitOps Development (Dry-Run Mode):
{
  "mcpServers": {
    "egmcp-server": {
      "command": "npx",
      "args": [
        "@saptak/egmcp-server",
        "stdio-tools",
        "--envoy-url",
        "http://localhost:19001",
        "--kubernetes.dry_run"
      ],
      "env": {}
    }
  }
}
Option B: Binary Installation
curl -sSL https://raw.githubusercontent.com/saptak/eg-mcp-server/main/install.sh | bash

2. Set Up Envoy Gateway Access

# 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:19000

3. Restart Claude Desktop

Claude Desktop will automatically load the EGMCP server and make all tools available.

🛠️ Available Tools

Available Tools Overview

The EGMCP Server provides 11 specialized tools for comprehensive Envoy Gateway management:

Read-Only Monitoring Tools (4 tools)
  • 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
Write Operation Tools (3 tools)
  • Route Creation: Create HTTPRoute resources via natural language
  • Route Deletion: Remove existing routes with safety validation
  • Listener Management: Add/remove Gateway listeners (ports/protocols)
Advanced Traffic Control (4 tools)
  • 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 .

💬 Example Queries

Once installed, you can ask Claude Desktop:

Configuration Analysis & Monitoring

  • "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"

Route Management

  • "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"

Advanced Traffic Control

  • "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"

Dry-Run Mode & GitOps

  • "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"

Advanced Route Configuration

  • "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"

Troubleshooting

  • "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?"

📋 System Requirements

Basic Requirements

  • 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

For Write Operations

  • 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

Optional

  • Go: 1.21+ (for building from source)

🔧 Configuration

Key Configuration Options

  • --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)

Quick Configuration Examples

Production Monitoring (Read-Only)
{
  "args": [
    "stdio-tools", 
    "--envoy-url", "http://prod-envoy:19001",
    "--kubernetes.kubeconfig", "/etc/kubernetes/prod-config",
    "--kubernetes.read_only"
  ]
}
GitOps Development (Dry-Run Mode)
{
  "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 .

🚨 Troubleshooting

Quick Fixes

"Could not attach to MCP Server"
  • ✅ Check binary path is absolute: /usr/local/bin/egmcp-server
  • ✅ Restart Claude Desktop after configuration changes
  • ✅ Verify kubeconfig path exists and is accessible
"Connection refused" to Envoy Gateway
  • ✅ 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
"Permission denied" for write operations
  • ✅ Use read-only mode for monitoring: --kubernetes.read_only
  • ✅ Check kubectl access: kubectl get httproutes
"Route creation fails with validation errors"
  • ✅ 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 ❌)

Testing & Debug

# 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 .

🤝 Contributing

We welcome contributions!

📄 License

This project is licensed under the MIT License - see the file for details.

🆘 Support

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 for detailed examples and use cases.