Welcome to this KMCP controllers lesson. Here you’ll learn how to install the KMCP controller (bundled with KAgent), confirm CRDs and API resources, inspect controller components, and deploy a sample MCPServer to verify reconciliation behavior.
This guide assumes the KMCP CRDs and model config were already installed. We’ll begin by reviewing the Helm values file used to install KAgent.
1) Values file used for Helm install Inspect the values file located at /root/01-values-min.yaml:
# /root/01-values-min.yaml agents : argo-rollouts-agent : enabled : false cilium-debug-agent : enabled : false cilium-manager-agent : enabled : false cilium-policy-agent : enabled : false helm-agent : enabled : false istio-agent : enabled : false k8s-agent : enabled : true kgateway-agent : enabled : false observability-agent : enabled : false promql-agent : enabled : false kmcp : enabled : true kagent-tools : enabled : true tools : grafana-mcp : enabled : false querydoc : enabled : false
Summary: the kmcp controller is enabled (kmcp.enabled=true) and minimal agents are enabled. The kagent-tools are also enabled.
Key Purpose Example kmcp.enabledEnable KMCP controller functionality within KAgent truekagent-tools.enabledEnables utility containers included with KAgent trueagents.k8s-agent.enabledLocal k8s agent for cluster integrations true
2) Install KAgent (includes KMCP controller) Install the KAgent Helm chart using the values file:
helm install kagent oci://ghcr.io/kagent-dev/kagent/helm/kagent \ --namespace kagent \ -f /root/01-values-min.yaml
Helm should pull the chart and install the release. Example Helm output:
Pulled: ghcr.io/kagent-dev/kagent/helm/kagent:0.7.7 Digest: sha256:070edef55214da5c8a964c21ee58869bc887e23a2dad37bf2922f1685fc7514c
Expose the KAgent UI (local access) Patch the kagent-ui Service to NodePort for local access (adjust nodePort as required):
kubectl -n kagent patch svc kagent-ui -p '{"spec":{"type":"NodePort","ports":[{"name":"ui","port":8080,"targetPort":8080,"nodePort":30080}]}}'
Exposing services via NodePort opens them on each cluster node. For production clusters prefer LoadBalancer or Ingress solutions with proper authentication.
3) Verify pods and controller components Check pods in the kagent namespace:
kubectl get pods -n kagent
Example output:
NAME READY STATUS RESTARTS AGE k8s-agent-855bbb4fc4-x22vz 1/1 Running 0 5m59s kagent-controller-6886fc4f5c-xc4gq 1/1 Running 0 6m7s kagent-kmcp-controller-manager-76645f577f-zncp9 1/1 Running 0 6m7s kagent-tools-56c49d7d4d-bszs7 1/1 Running 0 6m7s kagent-ui-59d5bbd564-7p82q 1/1 Running 0 6m7s
Troubleshooting quick pointers:
Check pod status: kubectl -n kagent get pods
View recent events: kubectl -n kagent get events --sort-by='.lastTimestamp'
Tail controller logs: kubectl -n kagent logs -l app.kubernetes.io/component=controller -f
Primary docs: https://kagent.dev
4) Confirm CRDs and API resources List CRDs related to KAgent and KMCP:
kubectl get crd | grep -E "kagent|kmcp"
Example CRDs present:
agents.kagent.dev 2025-12-15T11:03:27Z mcpservers.kagent.dev 2025-12-15T11:03:27Z memories.kagent.dev 2025-12-15T11:03:27Z modelconfigs.kagent.dev 2025-12-15T11:03:27Z remotemcpservers.kagent.dev 2025-12-15T11:03:27Z toolservers.kagent.dev 2025-12-15T11:03:27Z
You can also confirm the MCP API resource registration:
kubectl api-resources | grep -i mcp
Example API resources:
mcpservers kagent.dev/v1alpha1 true MCPServer remotemcpservers rmcps kagent.dev/v1alpha1 true RemoteMCPServer
Table — typical MCP-related CRDs:
CRD Description mcpservers.kagent.devDefines an MCPServer deployment and transport settings remotemcpservers.kagent.devRemote MCPServer definitions for cross-cluster or remote hosts modelconfigs.kagent.devModel configuration artifacts used by tools and agents
5) Locate KMCP controller pod and deployment Filter pods for the KMCP controller:
kubectl get pods -n kagent | grep kmcp
Example:
kagent-kmcp-controller-manager-76645f577f-zncp9 1/1 Running 0 5m3s
Check deployments in the kagent namespace to confirm the controller deployment name and status:
kubectl get deployment -n kagent
Example:
NAME READY UP-TO-DATE AVAILABLE AGE k8s-agent 1/1 1 1 6m23s kagent-controller 1/1 1 1 6m31s kagent-kmcp-controller-manager 1/1 1 1 6m31s kagent-tools 1/1 1 1 6m31s kagent-ui 1/1 1 1 6m31s
Tail controller logs to verify the KMCP controller has started and is reconciling:
kubectl -n kagent logs -l app.kubernetes.io/name=kagent -f
Look for messages indicating the MCP controller has started, registered event sources, and is serving metrics.
Verify service accounts created by the KMCP controller:
kubectl get serviceaccount -n kagent | grep kmcp
Example:
kagent-kmcp-controller-manager 0 5m32s
6) What the KMCP controller manages
The KMCP controller watches MCPServer custom resources and reconciles them into concrete Kubernetes objects (Deployments, Services, RBAC, etc.).
Each MCPServer CR results in one or more pods running the defined MCP server image/configuration.
The controller also updates MCPServer status conditions (e.g., whether the underlying pods are Ready).
7) MCPServer CRD structure (example) Always verify CRD schema in your installed version. A high-level example of an MCPServer resource:
apiVersion : kagent.dev/v1alpha1 kind : MCPServer metadata : name : example-mcp-server namespace : kagent spec : deployment : image : ghcr.io/example/mcp-server:latest port : 3000 cmd : "python" args : [ "src/main.py" ] env : API_KEY : "your-api-key-here" transportType : "stdio"
Notes about the main fields:
spec.deployment.image: Container image for the MCP server.spec.deployment.port: Port the server listens on inside the container.spec.deployment.cmd / args: Command and arguments to start the server.spec.deployment.env: Environment variables (for example, LLM API keys).spec.transportType: Recommended transport for local KAgent servers is stdio. Some servers support http.
8) Lifecycle: what happens when you create an MCPServer When you create an MCPServer CR:
KMCP controller detects the new CR and begins reconciliation.
The controller creates required Kubernetes resources (Deployment, Service, ConfigMaps, Secrets, etc.).
A pod (or pods) start using the configured image and arguments.
The MCPServer CR status will progress from unready to True once the pod(s) reach Ready.
9) Deploy a sample AWS API MCP server and verify Apply the sample manifest (example file path):
kubectl apply -f /root/aws-api-mcp-server.yaml
Verify the MCPServer resource and status:
kubectl get mcpserver -n kagent kubectl describe mcpserver aws-api-mcp-server -n kagent
During initialization the MCPServer’s status may show False until the pod becomes Ready. Once the pod is Running and Ready, the MCPServer status will indicate success.
10) Common questions (FAQ) Question Answer Are KMCP CRDs automatically installed in recent KAgent releases? Yes. KMCP CRDs are bundled starting with KAgent v0.7+. Older versions may require manual CRD installation. What is the MCPServer API group/version? kagent.dev/v1alpha1 — always confirm using kubectl api-resources.How do I confirm the MCPServer CRD is accessible? Use `kubectl api-resources grep mcpandkubectl get crd mcpservers.kagent.dev`. What if kubectl get mcpserver -A returns “No resources found”? Either there are no MCPServer resources created, or the CRD is not installed. Verify CRDs and namespaces.
11) Next steps This lesson completed the KMCP installation and basic exploration. The next lesson will show deploying additional AWS MCP servers and demonstrating integrations with model configs and tool servers.
Links and references 
