MCP Operator

⚠️ Alpha Software - Not Production Ready

This project is in early development and should be considered experimental. While we encourage you to try it out and provide feedback, please don't use it in production environments yet. APIs may change, features may be incomplete, and bugs are expected.

We'd love your feedback! Please open issues for bugs, feature requests, or questions.

Deploy your MCP servers on Kubernetes with automatic protocol validation, horizontal scaling, and built-in observability.

What is this?

MCP Operator makes it easy to run MCP servers in Kubernetes. Just define your server using a simple YAML file, and the operator handles the deployment, scaling, monitoring, and protocol validation for you.

Key Features:

• Auto-detection - Automatically detects transport type and MCP protocol version
• Protocol Validation - Ensures your servers are MCP-compliant
• Horizontal Scaling - Built-in autoscaling based on CPU and memory
• Observability - Prometheus metrics and Grafana dashboards out of the box
• Production Ready - Pod security standards and health checks

Quick Start

📖 New to MCP Operator? Check out the Getting Started Guide for a complete walkthrough.

Installation Options

Choose your preferred installation method:

Option 1: Install via Helm (Recommended)

# Get latest version
VERSION=$(curl -s https://api.github.com/repos/vitorbari/mcp-operator/releases | jq -r '.[0].tag_name' | sed 's/^v//')

# Install
helm install mcp-operator oci://ghcr.io/vitorbari/mcp-operator \
  --version ${VERSION} \
  --namespace mcp-operator-system \
  --create-namespace

Option 2: Install via kubectl

# Get latest version
VERSION=$(curl -s https://api.github.com/repos/vitorbari/mcp-operator/releases | jq -r '.[0].tag_name')

# Install from release assets
kubectl apply -f https://github.com/vitorbari/mcp-operator/releases/download/${VERSION}/install.yaml

Use Helm for easier configuration and upgrades. Use kubectl for minimal dependencies.

Your First MCP Server

Create a file called my-server.yaml:

apiVersion: mcp.mcp-operator.io/v1
kind: MCPServer
metadata:
  name: customer-data-mcp
spec:
  image: "your-registry.company.com/customer-data-mcp:v1.2.0"
  # Operator handles validation, scaling, monitoring

Apply it:

kubectl apply -f my-server.yaml

The operator needs a minute to start the server and validate it. Watch it in real-time:

kubectl get mcpservers -w

You should see something like:

NAME              PHASE     REPLICAS   READY   PROTOCOL   VALIDATION   CAPABILITIES                      AGE
customer-data-mcp Running   1          1       sse        Validated    ["tools","resources","prompts"]   109s

That's it! Your MCP server is running, validated, and ready to use.

What Gets Created

When you create an MCPServer, the operator automatically sets up:

• Deployment - Manages your server pods with health checks
• Service - Exposes your server inside the cluster
• HPA (optional) - Scales pods based on traffic
• Validation - Checks protocol compliance and reports capabilities

Examples

Production Setup with Auto-Scaling

apiVersion: mcp.mcp-operator.io/v1
kind: MCPServer
metadata:
  name: my-mcp-server
spec:
  image: "tzolov/mcp-everything-server:v3"
  command: ["node", "dist/index.js", "sse"]

  transport:
    type: http
    protocol: auto  # Let the operator detect the protocol
    config:
      http:
        port: 3001
        path: "/sse"
        sessionManagement: true

  # Scale between 2-10 pods based on CPU
  hpa:
    enabled: true
    minReplicas: 2
    maxReplicas: 10
    targetCPUUtilizationPercentage: 70

  # Pod security
  security:
    runAsUser: 1000
    runAsGroup: 1000
    runAsNonRoot: true

  resources:
    requests:
      cpu: "200m"
      memory: "256Mi"
    limits:
      cpu: "1000m"
      memory: "1Gi"

Protocol Validation

The operator automatically validates your MCP servers to ensure they're protocol-compliant. It checks transport connectivity, protocol version, authentication requirements, and available capabilities.

Enable strict mode to fail deployments that don't pass validation:

spec:
  validation:
    strictMode: true

For detailed validation behavior, see the Validation Behavior Guide.

Monitoring

Enable Prometheus metrics and Grafana dashboards:

With Helm:

# Get latest version
VERSION=$(curl -s https://api.github.com/repos/vitorbari/mcp-operator/releases | jq -r '.[0].tag_name' | sed 's/^v//')

# Install with monitoring
helm install mcp-operator oci://ghcr.io/vitorbari/mcp-operator \
  --version ${VERSION} \
  --namespace mcp-operator-system \
  --create-namespace \
  --set prometheus.enable=true \
  --set grafana.enabled=true

With kubectl:

# Get latest version
VERSION=$(curl -s https://api.github.com/repos/vitorbari/mcp-operator/releases | jq -r '.[0].tag_name')

# Install monitoring from release assets
kubectl apply -f https://github.com/vitorbari/mcp-operator/releases/download/${VERSION}/monitoring.yaml

Requires Prometheus Operator. See the Monitoring Guide for details on available metrics, dashboards, and alerting.

Transport Configuration

The operator supports both modern and legacy MCP protocols:

Auto-detection (recommended):

transport:
  type: http
  protocol: auto  # Automatically chooses the best protocol

Force Streamable HTTP (modern):

transport:
  type: http
  protocol: streamable-http

Force SSE (legacy):

transport:
  type: http
  protocol: sse

Most of the time, auto works great and saves you from having to figure out which protocol your server uses.

Documentation

Getting Started

• Getting Started Guide - 5-minute walkthrough
• Installation Guide - Detailed installation options

Configuration

• Configuration Guide - Complete configuration patterns and examples
• Environment Variables - Configuring environment variables
• Configuration Examples - Real-world YAML examples

Reference

• API Reference - Complete CRD field documentation
• Validation Behavior - Protocol validation deep dive

Operations

• Troubleshooting Guide - Common issues and solutions
• Monitoring Guide - Metrics, dashboards, and alerts

Advanced Topics

• Release Process - For maintainers
• Contributing - Development and contribution guidelines

Examples and Samples

Check out the config/samples/ directory for real-world examples:

• wikipedia-http.yaml - Simple example using the Wikipedia MCP server
• mcp-basic-example.yaml - Production setup with HPA and monitoring
• mcp-complete-example.yaml - Shows all available configuration options

Apply all samples:

kubectl apply -k config/samples/

Contributing

We welcome contributions! Whether it's:

• 🐛 Bug reports
• 💡 Feature requests
• 📝 Documentation improvements
• 🔧 Code contributions

Please see CONTRIBUTING.md for guidelines.

Support

• Found a bug? Open an issue
• Have questions? Start a discussion

License

Copyright 2025 Vitor Bari.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.