Quickstart

Deploy the echo-server example

The echo-server is the “hello world” of kube-mcp. It demonstrates all four CRD types together.

kubectl apply -k "github.com/atippey/kube-mcp//examples/echo-server/manifests?ref=fdd289260a135ac2944be6814b0d80ff2e6a899e"

This creates:

Resource	Name	What it does
Namespace	`mcp-test`	Isolated namespace for the example
Deployment + Service	`echo-backend`	Simple HTTP echo backend
MCPServer	`echo`	Aggregates tools/prompts/resources via label selector
MCPTool	`echo-tool`	Echoes back input — points to the echo-backend Service
MCPTool	`calculator-tool`	Basic math operations
MCPPrompt	`greeting-prompt`	Template with `{{name}}`, `{{date}}`, `{{topic}}` variables
MCPPrompt	`code-review-prompt`	Code review template
MCPResource	`sample-config`	Inline JSON configuration
MCPResource	`readme`	Inline Markdown documentation

Verify

Check the operator reconciled everything:

# CRDs
kubectl get mcpservers -n mcp-test
kubectl get mcptools -n mcp-test
kubectl get mcpprompts -n mcp-test
kubectl get mcpresources -n mcp-test

# Operator-generated resources
kubectl get deployment,service,configmap -n mcp-test -l app.kubernetes.io/instance=echo

# Pods should be Running
kubectl get pods -n mcp-test

The operator creates a Deployment, Service, and ConfigMap for the echo MCPServer. The ConfigMap contains the aggregated tool/prompt/resource configuration, mounted into the MCP server pod.

Check the MCPServer status conditions to confirm the operator discovered everything:

kubectl describe mcpserver echo -n mcp-test

Look for the Conditions section in the output:

Status:
  Conditions:
    Type:    ToolsDiscovered
    Status:  True
    Reason:  ResourcesFound
    Message: Found 2 tool(s), 2 prompt(s), 2 resource(s) matching selector ...
    Type:    ConfigReady
    Status:  True
    Reason:  ConfigMapCreated
    Message: ConfigMap created with 2 tool(s), 2 prompt(s), 2 resource(s)
    Type:    Ready
    Status:  True
    Reason:  DeploymentReady
    Message: Deployment has 1 ready replica(s)

If ToolsDiscovered is False, check that your MCPTool labels match the MCPServer’s toolSelector.

Direct Pattern: third-party MCP servers

Some MCP servers are self-contained — no separate backend needed. Use image, args, and env on the MCPServer to run them directly:

apiVersion: kubemcp.io/v1alpha1
kind: MCPServer
metadata:
  name: aws-diagram
  namespace: mcp-system
spec:
  replicas: 1
  image: mcp/aws-diagram:latest
  args:
    - "--transport"
    - "sse"
    - "--port"
    - "8080"
    - "--host"
    - "0.0.0.0"
  env:
    - name: FASTMCP_LOG_LEVEL
      value: "ERROR"
  redis:
    serviceName: mcp-redis
  ingress:
    host: aws-diagram.kubemcp.io
    pathPrefix: /sse
  toolSelector:
    matchLabels:
      mcp-server: aws-diagram

The env field also supports valueFrom for Secrets and ConfigMaps:

env:
  - name: API_KEY
    valueFrom:
      secretKeyRef:
        name: my-secret
        key: api-key

More examples

Example	Description
echo-server	Simple echo backend — the “hello world” of kube-mcp
hash-tool	Cryptographic hash generation (md5, sha1, sha256, sha512)
time-tool	Timezone-aware time formatting
weather-tool	Weather information via external API
dns-tool	DNS lookup tool
kubectl-explain	Kubernetes resource explanation
kube-info-tool	Kubernetes cluster information
act-tool	GitHub Actions local runner (nektos/act)
crane-tool	Container image registry tool
compliance-tool	FIPS, STIG, FedRAMP compliance checking
aws-diagram-tool	AWS architecture diagram generator (Direct Pattern)

Cleanup

kubectl delete -k "github.com/atippey/kube-mcp//examples/echo-server/manifests?ref=fdd289260a135ac2944be6814b0d80ff2e6a899e"