mcp-lifecycle-operator

A Kubernetes operator that provides a declarative API to deploy, manage, and safely roll out MCP Servers, handling their full lifecycle with production-grade automation and ecosystem integrations.

Prerequisites

• Kubernetes cluster (v1.28+)
• kubectl configured to access your cluster
• Go 1.24+ (for building from source)

Testing on Your Cluster

1. Install the CRDs

First, install the Custom Resource Definitions:

make install

This creates the MCPServer CRD in your cluster.

2. Run the Controller

You have two options:

Option A: Run Locally (Recommended for Testing)

Run the controller on your local machine (it will connect to your cluster):

make run

Keep this terminal open. The controller logs will appear here.

Option B: Deploy to Cluster

Build and deploy the controller as a Deployment in your cluster:

# Build and push the container image for multiple platforms
make docker-buildx IMG=<your-registry>/mcp-lifecycle-operator:latest

# Deploy to cluster
make deploy IMG=<your-registry>/mcp-lifecycle-operator:latest

Note: docker-buildx builds for multiple architectures (amd64, arm64, s390x, ppc64le) and pushes automatically.

3. Create a Test MCPServer

In a new terminal, create a test MCPServer resource:

kubectl apply -f - <<EOF
apiVersion: mcp.x-k8s.io/v1alpha1
kind: MCPServer
metadata:
  name: test-server
  namespace: default
spec:
  source:
    type: ContainerImage
    containerImage:
      ref: aliok/mcp-server-streamable-http:latest
  config:
    port: 8081
EOF

4. Verify the Deployment

Check that the operator created the resources:

# View the MCPServer status
kubectl get mcpservers
kubectl get mcpserver test-server -o yaml

# Verify the Deployment was created
kubectl get deployment test-server

# Verify the Service was created
kubectl get service test-server

# Check the pod is running
kubectl get pods -l mcp-server=test-server

Expected output from kubectl get mcpservers:

NAME          PHASE     IMAGE                                      PORT   ADDRESS                                            AGE
test-server   Running   aliok/mcp-server-streamable-http:latest   8081   http://test-server.default.svc.cluster.local:8081/mcp  1m

The ADDRESS column shows the cluster-internal URL that can be used by other workloads to connect to the MCP server.

The status includes the service address for easy discovery:

status:
  phase: Running
  deploymentName: test-server
  serviceName: test-server
  address:
    url: http://test-server.default.svc.cluster.local:8081/mcp
  conditions:
    - type: Ready
      status: "True"

5. Test the Service

Port-forward to test connectivity:

kubectl port-forward service/test-server 8081:8081

Then in another terminal:

curl http://localhost:8081/mcp

You should see a response from the MCP server.

6. Uninstall (Optional)

To remove the CRDs and operator:

# If you deployed to cluster
make undeploy

# Remove the CRDs
make uninstall

Examples

For complete examples with ConfigMap support and detailed documentation, see the examples/ directory:

• kubernetes-mcp-server - Deploy the Kubernetes MCP Server with basic and ConfigMap-based configurations

Example MCPServer Resources

Streamable HTTP MCP Server

apiVersion: mcp.x-k8s.io/v1alpha1
kind: MCPServer
metadata:
  name: streamable-http-server
  namespace: default
spec:
  source:
    type: ContainerImage
    containerImage:
      ref: aliok/mcp-server-streamable-http:latest
  config:
    port: 8081

Custom MCP Server

apiVersion: mcp.x-k8s.io/v1alpha1
kind: MCPServer
metadata:
  name: custom-server
  namespace: default
spec:
  source:
    type: ContainerImage
    containerImage:
      ref: my-registry.io/custom-mcp-server:1.0.0
  config:
    port: 8000

Development

Building

# Generate code and manifests
make manifests generate

# Build binary
make build

# Run tests
make test

Community, discussion, contribution, and support

This project is part of Kubernetes SIG Apps.

Learn how to engage with the Kubernetes community on the community page.

You can reach the maintainers of this project at:

• Slack channel
• Mailing List

Code of conduct

Participation in the Kubernetes community is governed by the Kubernetes Code of Conduct.