MCP Operator
⚠️ Alpha Software
This project is in early development. APIs may change, features may be incomplete, and bugs are expected. We'd appreciate your feedback via issues.
A Kubernetes operator for deploying MCP servers.
Why use this?
Protocol validation - The operator connects to your MCP server after deployment and verifies it actually speaks MCP. It detects which protocol your server uses (SSE or Streamable HTTP), what capabilities it advertises, and whether it requires authentication. This catches configuration mistakes early - wrong port, wrong path, server not actually running MCP, etc.
Correct transport configuration - SSE and Streamable HTTP have different requirements. The operator handles the transport-specific configuration (paths, session management, keep-alive settings) so you don't have to figure out the right Service annotations or health check paths for each protocol type.
Observability - If you have Prometheus Operator installed, the operator creates ServiceMonitors and Grafana dashboards for your MCP servers. There's also an optional metrics sidecar that can collect MCP-specific metrics (request counts, latencies, etc.)
Standard Kubernetes resources - Under the hood, it creates Deployments, Services, ServiceAccounts, and HPAs. Nothing proprietary.
What this doesn't do
- Ingress/external exposure - Creates a ClusterIP Service by default. You need to create your own Ingress, Gateway, or change the Service type to LoadBalancer if you want external access.
- Authentication - The operator detects if your server requires auth, but doesn't handle authentication itself. You need to configure auth at your server or ingress layer.
- stdio transport - Only supports HTTP-based transports (SSE and Streamable HTTP). If your MCP server uses stdio, you can wrap it with an adapter like supergateway that exposes it as SSE or Streamable HTTP, then deploy that container with this operator. See the containerizing guide for details.
- MCP client - This deploys servers, not clients. It doesn't help you connect to MCP servers from your applications.
- TLS termination - Doesn't configure TLS by default. You can enable TLS termination via the metrics sidecar (
spec.sidecar.tls) if you're using metrics, or use an ingress controller.
Quick Start
See the Getting Started Guide for a complete walkthrough.
Installation
Two options:
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
Helm is easier to configure. kubectl has fewer dependencies.
Your First MCPServer
Create my-server.yaml:
apiVersion: mcp.mcp-operator.io/v1
kind: MCPServer
metadata:
name: my-mcp-server
spec:
image: "your-registry/your-mcp-server:v1.0.0"
Apply it:
kubectl apply -f my-server.yaml
Watch the status:
kubectl get mcpservers -w
Output:
NAME PHASE REPLICAS READY PROTOCOL VALIDATION CAPABILITIES AGE
my-mcp-server Running 1 1 sse Validated ["tools","resources","prompts"] 109s
The operator created a Deployment and Service. It also connected to your server to validate it speaks MCP and detected its capabilities.
What Gets Created
When you create an MCPServer, the operator creates:
- Deployment - Runs your server container with configured health checks
- Service - ClusterIP service for in-cluster access (configurable to NodePort or LoadBalancer)
- ServiceAccount - For pod identity
- HPA - If
hpa.enabled: true, creates a HorizontalPodAutoscaler
The operator also runs validation against your server to check protocol compliance.
Examples
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
Requires Prometheus Operator to be installed in your cluster.
With Helm:
VERSION=$(curl -s https://api.github.com/repos/vitorbari/mcp-operator/releases | jq -r '.[0].tag_name' | sed 's/^v//')
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:
VERSION=$(curl -s https://api.github.com/repos/vitorbari/mcp-operator/releases | jq -r '.[0].tag_name')
kubectl apply -f https://github.com/vitorbari/mcp-operator/releases/download/${VERSION}/monitoring.yaml
This creates a ServiceMonitor (so Prometheus scrapes the operator metrics) and a ConfigMap with a Grafana dashboard.
See the Monitoring Guide for details.
MCP Server Metrics
Enable per-server metrics collection with a single line:
apiVersion: mcp.mcp-operator.io/v1
kind: MCPServer
metadata:
name: my-mcp-server
spec:
image: your-registry/your-mcp-server:latest
transport:
type: http
config:
http:
port: 3001
metrics:
enabled: true # That's it!
When enabled, the operator injects a metrics sidecar that automatically tracks:
- Request counts, latencies, and sizes
- Tool calls by tool name
- Resource reads by URI
- JSON-RPC errors by method and code
- SSE connection metrics
See the MCP Server Metrics Guide for available metrics, Grafana queries, and alerting examples.
Transport Configuration
MCP has two HTTP transport protocols: SSE (Server-Sent Events, older) and Streamable HTTP (newer). The operator can auto-detect which one your server uses, or you can specify it explicitly.
Auto-detection:
transport:
type: http
protocol: auto
Explicit SSE:
transport:
type: http
protocol: sse
Explicit Streamable HTTP:
transport:
type: http
protocol: streamable-http
Auto-detection works by trying to connect with each protocol. If you know which protocol your server uses, specifying it explicitly is faster.
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 - Operator metrics, dashboards, and alerts
- MCP Server Metrics - Per-server metrics with the sidecar proxy
- Sidecar Architecture - Technical deep-dive into the metrics sidecar
Advanced Topics
- Release Process - For maintainers
- Contributing - Development and contribution guidelines
Examples and Samples
Check out the config/samples/ directory for real-world examples:
Apply all samples:
kubectl apply -k config/samples/
Contributing
See CONTRIBUTING.md for guidelines on bug reports, feature requests, and code contributions.
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.
