·

Kubernetes MCP With OpenCode

Set up Kubernetes MCP in OpenCode so your AI agent can inspect and manage clusters, pods, and deployments right from your editor.

OpenCode's MCP support follows the same JSON-based server registration pattern as most agent CLIs, but its tool-calling loop is more conservative about chaining calls without an explicit next-step prompt — which actually works in your favor for cluster work, since it reduces the odds of an agent quietly running six calls you didn't ask for. This topic covers setup, day-to-day inspection workflows, a real rollout-failure walkthrough, and where OpenCode's current Kubernetes MCP integration falls short.

Installing and Connecting Kubernetes MCP to OpenCode

OpenCode reads MCP server definitions from opencode.json (project root) or ~/.config/opencode/opencode.json (global). Add the Kubernetes MCP server as a local stdio server:

{
  "mcp": {
    "kubernetes": {
      "type": "local",
      "command": ["kubernetes-mcp-server", "--kubeconfig", "/Users/you/.kube/config-staging"],
      "enabled": true
    }
  }
}

If you're using the Node package instead of the Go binary:

{
  "mcp": {
    "kubernetes": {
      "type": "local",
      "command": ["npx", "-y", "mcp-server-kubernetes"],
      "environment": {
        "KUBECONFIG": "/Users/you/.kube/config-staging"
      },
      "enabled": true
    }
  }
}

Start OpenCode and confirm the server loaded:

opencode
/mcp

This lists connected servers and their tool counts, same pattern as Claude Code. If the server doesn't appear, check opencode.json syntax first — a trailing comma or wrong key name (mcp vs mcpServers, which some older docs and other tools use) is the most common cause of a silent no-op, since OpenCode won't always error loudly on an unrecognized top-level key.

Scope the config to the project so teammates get the same server without manual setup, but keep the actual kubeconfig path out of committed config — reference an environment variable instead:

{
  "mcp": {
    "kubernetes": {
      "type": "local",
      "command": ["kubernetes-mcp-server", "--kubeconfig", "{env:KUBECONFIG}"],
      "enabled": true
    }
  }
}

Tips
- Double-check the top-level key name (mcp) in opencode.json — it differs from Claude Code's mcpServers, and copy-pasting a config between the two tools silently fails.
- Run /mcp immediately after any config change — OpenCode doesn't always hot-reload MCP registration mid-session, so a fresh session start is the reliable way to confirm.
- Keep kubeconfig paths in environment variables referenced via {env:VAR} syntax rather than hardcoded, so the same project config works across teammates' machines.

Inspecting Workloads, Services, and ConfigMaps from OpenCode

OpenCode handles single-purpose, explicit prompts more reliably than open-ended "investigate this" requests, so structure your asks accordingly:

List all Deployments in namespace inventory-prod and show their replica
counts (desired vs available).

Get the ConfigMap named inventory-api-config in namespace inventory-prod
and show me its data keys (not full values, just keys).

List Services in namespace inventory-prod and show which ones have no
matching endpoints (empty selector match).

That last prompt is a genuinely useful diagnostic pattern — a Service with zero endpoints is either a label-selector mismatch or every backing pod is unready, and it's a common cause of "service unreachable" tickets that don't show up as a pod-level problem at all. Have OpenCode cross-reference:

The inventory-api Service has no endpoints. Show its selector, then list
pods in the same namespace and compare their labels against that selector.

selector:
  app: inventory-api
  version: stable

labels:
  app: inventory-api
  version: canary

That's the entire bug, right there — a version label mismatch from a canary rollout that never got promoted, and the Service quietly stopped routing to anything. This class of issue is exactly where an MCP-driven agent earns its keep: cross-referencing two resources by hand takes a minute of kubectl get -o yaml and eyeballing; the agent does it in one turn.

Tips
- Keep OpenCode prompts scoped to one resource type or one specific comparison at a time — it's more reliable at precise multi-resource comparisons than at open-ended "figure out what's wrong" requests.
- Service-with-no-endpoints is a distinct and common failure mode from pod-level crashes — always compare selector against actual pod labels when a service reports unreachable but pods look healthy.
- Ask for ConfigMap/Secret keys, not values, in the first pass — you rarely need the actual value to diagnose a missing-key problem, and it keeps sensitive data out of the chat transcript by default.

Practical Example: Diagnosing a Failed Rollout in OpenCode

Scenario: a Deployment rollout for pricing-service has been stuck at "1 of 3 replicas updated" for ten minutes.

The pricing-service Deployment rollout in namespace pricing-prod looks
stuck — 1 of 3 replicas updated. Check rollout status, then get the new
ReplicaSet's pods and their status.

The agent's chain: get the Deployment (checking status.conditions for Progressing reason), list ReplicaSets owned by it, then get pods in the new ReplicaSet.

status:
  conditions:
    - type: Progressing
      status: "True"
      reason: ReplicaSetUpdated
      message: "ReplicaSet \"pricing-service-6f9b8d7c4\" is progressing."

That condition alone doesn't tell you why it's stuck — it just confirms a rollout is in progress. The actual cause is usually in the new pod's status:

containerStatuses:
  - name: pricing-service
    ready: false
    state:
      waiting:
        reason: CreateContainerConfigError
        message: "secret \"pricing-db-creds-v2\" not found"

This is a classic rollout-stuck cause: the new pod template references a Secret name that doesn't exist yet (a versioned secret rotation where the new secret wasn't created before the Deployment rolled out). The fix is either creating the missing secret or rolling back:

kubectl rollout undo deployment/pricing-service -n pricing-prod

Have OpenCode confirm the rollback stabilized before you consider the incident closed:

Confirm the rollback completed — show the Deployment's current
ReplicaSet and pod status after the undo.

Tips
- status.conditions[].reason on a Deployment tells you a rollout is stuck, not why — always follow up by inspecting the new ReplicaSet's actual pods.
- CreateContainerConfigError almost always means a missing ConfigMap/Secret reference — check that the referenced object exists in the same namespace before assuming an app bug.
- Always verify a rollback actually stabilized (new pods Ready, old ReplicaSet scaled back up) rather than assuming rollout undo succeeding means the incident is over.

Known Limitations for Kubernetes MCP in OpenCode

Be upfront with your team about where this integration currently falls short, so nobody's surprised mid-incident:

  • No native metrics tool. Like most Kubernetes MCP servers, live CPU/memory usage (kubectl top equivalent) isn't exposed as of the versions in common use through late 2025. You'll still shell out for that.
  • Multi-context switching requires a session restart. OpenCode doesn't re-read kubeconfig context changes mid-session; switching clusters means restarting the OpenCode process after kubectl config use-context.
  • Exec support varies by server build. pods_exec is present in mcp-server-kubernetes but has had intermittent stability issues with interactive/TTY-style commands in some released versions — test it against a non-critical pod before relying on it during an actual incident.
  • Watch-style tools are not push-based in the chat UI. A watch tool call returns a snapshot response, not a live stream into the conversation — for anything you'd normally kubectl get pods -w, you need to re-issue the tool call.
  • CRD support depends on server discovery. The generic resources_get/resources_list tools work against CRDs only if the server's discovery client picked up the CRD's API group correctly — verify with a throwaway list call before depending on it for a custom resource your team owns.

None of these are dealbreakers, but they shape what you should and shouldn't ask the agent to do unsupervised.

Tips
- Don't rely on OpenCode's Kubernetes MCP for live usage metrics or live-streaming watches — fall back to kubectl top / kubectl get -w directly for those.
- Test pods_exec against a disposable pod before your first real incident use — stability has varied across server releases.
- Verify CRD visibility with a quick resources_list call early in any session where you'll need to inspect custom resources — don't discover the gap mid-incident.

Tips

Tips
- Scope prompts narrowly in OpenCode — it handles precise, single-purpose asks (compare X against Y) more reliably than broad "investigate everything" requests.
- Service-with-no-endpoints and stuck-rollout-due-to-missing-secret are both patterns worth teaching your team to recognize by their event/status signatures, not just leaving to the agent to rediscover each time.
- Keep a running note of which Kubernetes MCP tools your specific server version supports (metrics, exec, watch, CRDs) — capability gaps between server versions and forks are real and worth checking after every upgrade.

Next Kubernetes MCP With Gemini CLI