ai-agent-readonly-context

ai-agent-readonly-context

The agent-integration loop. The user is wiring cub-scout into an AI agent — Claude Code, Codex, Cursor, Continue, a custom MCP-aware LLM — and needs the patterns that make cub-scout's output reliable for LLMs.

Three patterns matter here, plus the prompt shape that ties them together:

1. MCP gateway (mcp serve) — long-running tool surface the agent calls live
2. context-pack (context-pack --format json) — deterministic one-shot snapshot the agent reasons over
3. --presentation ai — output format with bracket notation + uppercase markers that LLMs parse reliably

Plus the read-only invariant: every cub-scout tool an agent can call is categorically non-mutating. cub-scout is the safest possible AI surface because the worst-case prompt-injection still can't apply / edit / delete anything.

When to use

Explicit phrasings:

• "Set up cub-scout as a Claude tool"
• "Expose cub-scout to my agent over MCP"
• "Give the LLM a deterministic snapshot of this cluster"
• "What cub-scout patterns work well for AI agents?"
• "MCP config for cub-scout in Claude Code / Codex / Cursor / Continue"
• "Best practices for wiring cub-scout into [agent framework]"
• "AI-ready cluster context for my LLM workflow"
• "Prompt template for cub-scout output"
• "How do I make cub-scout JSON parseable by an LLM?"

Implicit intents:

• The user is integrating, not running cub-scout interactively
• The user values determinism (same input → same bytes)
• The user values read-only safety (prompt injection can't escalate to cluster mutation)
• The user may be combining cub-scout with cub / kubectl / other tools in the agent's tool set

Do not load for

• A specific verb invocation — load the matching scout-* skill
• Authoring an MCP server in general (this is about wiring cub-scout specifically) — use the MCP-server-authoring docs from the agent host
• Mutating workflows. cub-scout never mutates; the read-only triad is the whole point of this skill.
• ConfigHub-side MCP integration — that's cub, a separate tool surface

The patterns

Pattern 1 — MCP gateway (live tool calls)

cub-scout mcp serve is a long-running MCP server exposing cub-scout's verbs as tools. Register it in your agent host's MCP config:

// .claude/mcp_servers.json (Claude Code) — STDIO transport (preferred)
{
  "mcpServers": {
    "cub-scout": {
      "command": "cub-scout",
      "args": ["mcp", "serve"],
      "env": {
        "KUBECONFIG": "${env:HOME}/.kube/config"
      }
    }
  }
}

The agent host calls tools/list to discover tools and tools/call to invoke them. cub-scout's mcp_test.go covers the exact catalog:

Standalone-mode tools (8, always available):

• doctor — cluster-level diagnostic with structured nextSteps
• map — resource inventory with ownership classification
• scan — risk + misconfiguration findings
• trace — ownership + source chain (one resource)
• explain — plain-English per-resource report
• gitops_status — GitOps/controller delivery status and coverage evidence
• gitops_settings — the delivery settings each Argo CD and Flux deployer declares (auto-sync, self-heal, prune, suspension); declared settings only, no verdict (preview)
• release_check — whether one exact, digest-pinned configuration release reached a target, stage by stage; no application-success claim

Connected-mode tools (13, added when the ConfigHub session check passes; since v2.14.0 that check and most of these reads go through the ConfigHub SDK, with no cub binary):

• compare_three_way — DRY/WET/LIVE with rolled-up agreement
• compare_source_truth — strategy-typed verdict (target + namespace + strategy required)
• confighub_attestations — attestations ConfigHub records directly against one exact revision (space, unit and revision required); recorded claims, not an approval verdict
• confighub_changeorder_get — exact-space reported ChangeOrder Stage/State and declarations; evaluated outcomes unknown, including Completed
• confighub_changesets — governed ChangeSet history from ConfigHub
• confighub_k8s_resources — ConfigHub Resource-backed intended Kubernetes resources
• confighub_k8s_types — ConfigHub Resource-backed intended Kubernetes type survey
• confighub_live_status — ConfigHub Space live-status writeback with freshness
• confighub_releases — bounded ConfigHub Release history
• confighub_resources — generic ConfigHub Resource entity queries
• confighub_unit_events — bounded ConfigHub UnitEvent history
• confighub_units — ConfigHub unit + fleet inventory
• confighub_unit_get — exact ConfigHub unit details + applied/live revision

Use the standard MCP tools/list request to dump the registered catalog from the running server. See references/mcp-tool-catalog.md for per-tool parameters, return shape, and the list of verbs intentionally NOT in the catalog.

Pattern 2 — context-pack (deterministic snapshot)

cub-scout context-pack --format json produces a one-shot deterministic JSON snapshot of the cluster. Same input → same bytes. Safe to feed an LLM with prompt caching; safe to diff in CI.

$ cub-scout context-pack --format json > cluster-ctx.json
$ wc -l cluster-ctx.json
2347 cluster-ctx.json

$ jq '.ownership | group_by(.type) | map({type: .[0].type, count: length})' cluster-ctx.json
[
  {"type": "argo",    "count": 47},
  {"type": "flux",    "count": 12},
  {"type": "helm",    "count": 8},
  {"type": "native",  "count": 23},
  {"type": "unknown", "count": 3}
]

The pack carries:

• version — cub-scout build tag + context-pack schema version
• capturedAt — RFC 3339 timestamp (the ONLY non-deterministic field; everything else is reproducible)
• cluster — kubeconfig context + server URL
• mode — standalone or connected
• resources[] — per-workload kind / name / namespace / ownership classification
• attribution[] — per-resource attribution evidence (cause, managerHint, gitSource, bindingSource)
• omissions[] — explicit non-claims (e.g., resources skipped due to CrashLoop, unsupported kinds)

For lower-level JSON artifacts outside context-pack, prefer the shared observation metadata when present. map list --format json, snapshot, summary list --format json, and watch/bot events expose observation.source, observation.mode, observation.observedAt, and observation.freshness so an agent can tell whether it is reasoning over a fresh live read, stored summary evidence, a point-in-time snapshot, or an event from a polling observer.

Feed it to the LLM as a system message context block:

You have read-only access to a Kubernetes cluster snapshot via the JSON below.
Cluster: <cluster name>
Mode: <standalone|connected>
Captured at: <RFC3339>

<cluster-ctx.json>

You can also call the following MCP tools for deeper reads: ...

Pattern 3 — --presentation ai

For agent prompts that consume ASCII output (not JSON), --presentation ai produces a structured form LLMs parse reliably. Uppercase markers; bracket notation; consistent label-value separators.

$ cub-scout explain deploy/api -n prod --presentation ai
[explain]
Resource: Deployment/api in prod
Owner: Argo CD application "payments-api" [label:argocd.argoproj.io/instance]
Drift: Detected
Mutation cause: manual-edit [manager: kubectl-edit; controller co-signal: argocd-controller]
Git source: https://github.com/org/platform-config @abc123 path=apps/prod/api
Events: ImagePullBackOff (5 mins ago, repeating)
Recommended actions:
  - [read-only] Image ghcr.io/org/api:v2.3.0 cannot be pulled; check ghcr.io status
  - [read-only] If image is correct, verify imagePullSecrets
[end explain]

vs. the default human form:

$ cub-scout explain deploy/api -n prod
Resource: Deployment/api in prod
  Owner: Argo CD application "payments-api"
    (label:argocd.argoproj.io/instance)
  ...

The AI form is denser, less ambiguous, and parseable with regex if needed.

Available on doctor / explain / trace (per #352 / #359). The --presentation paired flag emits both forms for human + AI dual-purpose output.

The read-only invariant

This is the value proposition for AI integration. cub-scout's MCP tool catalog is closed and read-only by construction:

• Every tool wraps a read-only cub-scout verb with --format json or a read-only cub list/get query
• Every verb is non-mutating
• The tool catalog is verified by cmd/cub-scout/mcp_test.go — adding a tool requires a code change + a passing test
• The receipt capability's FilterNextSteps (pkg/agent/receipt_predicates.go) strips mutating actionType / nextCommand from any structured next-step hint before emit
• TestReceiptPackageReadOnlyClient statically greps the receipt source for any mutating K8s client method

Consequence: even with a fully-compromised prompt, an LLM calling cub-scout's MCP tools cannot apply / edit / patch / delete anything. The blast radius is reads.

This is unusual — most operational tools mix read and write surfaces. cub-scout's #410 / #428 architectural-triad work made the read-only carve-out a code-enforced invariant, not a convention. That's what makes cub-scout the safest Kubernetes MCP surface for AI agents today.

Worked example: Claude Code integration

// .claude/mcp_servers.json
{
  "mcpServers": {
    "cub-scout": {
      "command": "cub-scout",
      "args": ["mcp", "serve"]
    }
  }
}

// .claude/skills.json — load the relevant scout-* skills
{
  "skills": [
    "scout-observe", "scout-diagnose", "scout-compare", "scout-attribute",
    "scout-verify", "scout-mcp",
    "triage-unhealthy-workload", "investigate-drift"
  ]
}

User prompt: "deploy/api in prod is broken, what's going on?"

Agent's likely loop:

1. Trigger triage-unhealthy-workload skill
2. Call MCP tool doctor (scope: namespace=prod)
3. Call MCP tool explain (deploy/api -n prod)
4. Call MCP tool trace (deploy/api -n prod)
5. Read structured nextSteps[] + events[] from the responses
6. Synthesize human-language explanation; route the mutation suggestion to the user

The agent NEVER calls a mutating MCP tool because there are none registered. The user drives kubectl rollout undo / argocd app rollback from a separate context if needed.

Configuration tips

• Prefer STDIO over HTTP for agent integration — lower latency, easier to sandbox, no port management.
• Set KUBECONFIG explicitly in the MCP env block so the server picks up the right cluster context. Don't rely on the agent host inheriting it.
• For multi-cluster contexts, run one mcp serve instance per cluster on different ports / paths, OR use the --context <name> flag to switch contexts in-process. cub-scout doesn't support multi-context-in-one-server today (a single mcp serve is one context).
• Cache context-pack aggressively. It's deterministic; an LLM with prompt caching benefits enormously from caching the snapshot across multiple queries.
• Use connected mode if the agent is doing source-truth / governance work. Check confighub_reads in cub-scout status --json first (cub auth status checks the same session when cub is installed); the agent should refuse to claim source-truth verdicts in standalone mode.

Tool boundary

• Allowed: mcp serve (long-running but no mutation), context-pack, status, version, plus the read-only verbs the agent will indirectly call through MCP.
• Not allowed: any mutating verb. The MCP gateway never registers one; the static guards in cub-scout enforce it.
• MCP and the triad: cub-scout (evidence) ↔ MCP (transport) ↔ Pilot or agent (judge / actor). The MCP layer is plumbing; it never decides.

References

• scout-mcp — the verb-group skill for mcp serve and context-pack
• MCP tool descriptions audit: #377
• --presentation flag: #352 (doctor / explain), #359 (trace)
• Connected MCP trust surface: docs/reference/json-contracts.md § "MCP connected trust guidance"
• Context-pack format: docs/howto/context-pack-v2.md
• Examples: examples/ai-integration/, examples/mcp-gateway/, examples/ai-agent-quest/
• Read-only triad: #410, #428

Constraints

• The MCP tool catalog is closed. Adding tools requires a code change + a passing mcp_test.go test. Don't claim cub-scout has a mutating MCP tool — it doesn't, by design.
• context-pack is deterministic (same input, same bytes) EXCEPT for the capturedAt timestamp. If you need byte-identical output across runs, set a fixed capturedAt in your wrapper.
• For agent hosts that don't speak MCP yet, fall back to invoking cub-scout verbs directly via shell tools with --format json --presentation ai. The structured output is the same.
• This skill's read-only invariant doesn't extend to cub. If the agent has BOTH cub-scout AND cub MCP tools registered, the cub side IS mutation-capable. Use a separate allowed-tools policy for that surface.