portainer/portainer-mcp/portainer-mcp-hygiene

Portainer MCP hygiene

The Portainer MCP server returns large JSON payloads by default — a list of environments with snapshots, a list of K8s pods with full status blocks, a stack with its complete manifest. Every tool the server exposes accepts an optional select (JMESPath) parameter applied server-side before the response reaches you. Responses are capped at ~50,000 chars; if you exceed the cap you get a truncation hint that names select and shows an example.

The cost of not projecting is real: 50K chars of dense JSON eats roughly 20K tokens out of your context for a question that usually needed a few hundred. Once truncation fires, you've wasted a round trip and the data past the cap is gone for that call. The default move on any list-shaped Portainer call is to pass select from the start.

Resolve the environment first

Both proxy tools take an environment_id, and the IDs aren't predictable — they're assigned in creation order, not "local = 1". So for any environment-scoped question, resolve the target first with one call:

EndpointList(select="[].{id:Id,name:Name,type:Type,status:Status}")

and use the ID whose name matches what the user means. Guessing the environment is a hard failure, not a silent one: a wrong ID makes the proxy raise an API request failed (HTTP 404) error rather than returning empty data — so a wrong environment is not a source of null projections. Two other things are, though: an unquoted dotted key (see the JMESPath notes below) and a field-name mismatch on the typed GetAllKubernetes* tools (see their note under Where the noise lives). So read an all-null result as a wrong-keys signal to investigate, not as proof the data is absent.

The default pattern

For any call that returns a list of objects, ship a JMESPath that keeps only the fields the user's question actually needs:

EndpointList(select="[].{id:Id,name:Name,type:Type,status:Status}")
docker_proxy(environment_id=N, path="/containers/json", select="[].{id:Id,name:Names[0],state:State,image:Image}")
kubernetes_proxy(environment_id=N, path="/api/v1/pods", select="items[].{name:metadata.name,ns:metadata.namespace,phase:status.phase,node:spec.nodeName}")

JMESPath syntax notes that matter for these surfaces:

• List shape: start with [] to map over array elements.
• Wrapped list (Kubernetes {items: [...]}): start with items[].
• Single object: {field1:path.to.value,field2:other.path} — no leading [].
• Nested paths use dots: Snapshots[0].RunningContainerCount. But a key that

itself contains a dot or hyphen — compose labels, K8s annotations — collides with that syntax, so quote it as an identifier: Labels."com.docker.compose.project", or in a filter [?Labels."com.docker.compose.project"=='myproj']. Unquoted, JMESPath reads the dots as nested keys and silently returns null — which looks like a missing field rather than a broken expression. Quote with double quotes, not backslashes (\"…\" fails to parse) and not backticks (those denote JSON literals).

• The backslash trap is easy to fall into by accident: the select string is

itself an argument inside a JSON tool call, and escaping the inner quotes a second time sends literal \" to the server. The failure signature is a parse error mentioning Unknown token \. When you hit it, either resend with plain double quotes (encode the tool-call JSON once, not twice), or sidestep quoting entirely with a function filter — [?contains(metadata.name, 'ingress-nginx')] uses only single quotes and survives any transport.

Where the noise lives

These are the fields/sections that dominate Portainer payloads. Either project them out (when you don't need them) or project specifically into them (when they are the answer):

`EndpointList` — `.Snapshots[0]` carries the heavy payload. Each environment includes a full Docker or Kubernetes snapshot — container list, image list, network list, etc. For counts and status questions you almost always want to project into specific snapshot fields rather than fetch them whole:

# Container counts per environment
EndpointList(select="[].{name:Name,running:Snapshots[0].RunningContainerCount,total:Snapshots[0].ContainerCount}")
 
# Just identity + status field
EndpointList(select="[].{id:Id,name:Name,type:Type,status:Status}")

Status is a reachability signal only for direct agents. For edge environments it doesn't track reachability at all — see Interpreting results, not just shrinking them below before reading it as up/down.

Two EndpointList query params don't surface over MCP: updateInformation (agent-update availability) and k8sEnvAdmin (K8s admin flag). Portainer returns their answer in HTTP response headers (X-Update-Available, X-K8S-Env-Admin), and this server only ever returns the response body — so passing them changes nothing you can read. Don't rely on them through the MCP.

Kubernetes via `kubernetes_proxy` — `metadata.managedFields` and `status` are huge. metadata.managedFields alone is routinely 30-70% of an object. The status block on Deployments, StatefulSets, Pods, and Nodes is similarly verbose. Project them out unless the user is asking about reconciliation state or controller history:

# Pod summary
kubernetes_proxy(environment_id=N, path="/api/v1/pods", select="items[].{name:metadata.name,ns:metadata.namespace,phase:status.phase,restarts:status.containerStatuses[0].restartCount,node:spec.nodeName}")
 
# Deployment readiness
kubernetes_proxy(environment_id=N, path="/apis/apps/v1/deployments", select="items[].{name:metadata.name,ns:metadata.namespace,replicas:spec.replicas,ready:status.readyReplicas}")

A caveat on that pod projection: status.containerStatuses[0].restartCount — and status.containerStatuses[0].state.waiting.reason — comes back null for pods that never started a container, because Pending and many Failed pods have an empty containerStatuses. That's exactly the unhealthy set you're usually chasing, so don't read a null restart count as "zero restarts, healthy." Lead with status.phase and the pod-level status.reason (e.g. Evicted), and treat restartCount as extra detail that only exists once a container has actually run:

# Pod health, robust for not-yet-running pods
kubernetes_proxy(environment_id=N, path="/api/v1/pods", select="items[].{name:metadata.name,ns:metadata.namespace,phase:status.phase,reason:status.reason,restarts:status.containerStatuses[0].restartCount,node:spec.nodeName}")

`GetAllKubernetes*` tools — full object body per element, in a Portainer-specific shape. The OpenAPI-generated GetAllKubernetesApplications, GetAllKubernetesPersistentVolumes, GetAllKubernetesConfigMaps, etc. return arrays where each element carries its full body — so project to the fields you need. But mind the field names: these typed tools do not use the raw-K8s paths the proxy uses (metadata.name, status.phase, spec.…), and they don't reliably match the PascalCase of EndpointList (Id, Name) either. They tend to be flattened camelCase, and some fields collapse — e.g. GetAllKubernetesPersistentVolumes returns identity as a top-level name (not metadata.name) and status as a bare string "Bound" (not status.phase):

# Actual shape — camelCase, flattened, status-as-string
GetAllKubernetesPersistentVolumes(select="[].{name:name,status:status,claimNs:claimRef.namespace,sc:storageClassName,reclaim:persistentVolumeReclaimPolicy}")

Because the convention varies by tool, an all-null projection here almost always means you guessed the wrong keys — reusing the proxy's metadata.name or EndpointList's Name — not that the data is absent. When unsure, fetch one element with no `select` first to read the real field names, then project. If you'd rather work in raw-K8s field names, use kubernetes_proxy instead.

`StackList` and `StackInspect` — config and env vars. Stacks carry the full compose/manifest content plus environment variable dictionaries. If the user asked "which stacks exist?", project to {id, name, type, status}. If they asked about a specific stack's config, fetch it directly and only then look at the body. Env values come back redacted by default — see Env values are redacted by default below.

Snapshot inspects (`snapshotInspect`, `snapshotContainersList`, etc.) — entire snapshots. These return the whole snapshot blob by design. Always project.

Helm endpoints — full chart values and manifests. HelmList carries release status + chart metadata; HelmGet returns the rendered manifest. Project to release names and status when listing; only fetch the manifest when the user asked to see it.

`EndpointGetCharts`, `dockerDashboard`, `EndpointSummaryCounts` — already aggregated. These are the lightweight "summary" tools. Prefer them over EndpointList + projection when the user's question is purely a count or rollup — fewer characters, less work, more accurate (server-side aggregation).

Env values are redacted by default. Stack, container, and Kubernetes env values come back as [REDACTED]. The response also carries a one-line summary: [N env value(s) redacted; set PORTAINER_EXPOSE_ENV_VALUES=1 on the MCP server to disclose].

• Don't waste a tool call fishing for them via select — the projection runs after redaction, so any field path lands on the sentinel.
• If the user genuinely needs an env value (troubleshooting a deploy), tell them to set PORTAINER_EXPOSE_ENV_VALUES=1 on the MCP server and reconnect. Don't invoke the toggle yourself.
• The sentinel [REDACTED] is a literal placeholder — never quote it back to the user as if it were the real value.
• Redaction covers Env / EnvVars shapes (stack Env pairs, Docker KEY=VAL strings, K8s env[].value). K8s valueFrom references are preserved — they're references to a Secret/ConfigMap, not the secret material itself.

Interpreting results, not just shrinking them

Projecting the right fields only helps if you read them correctly. The highest-frequency misread on this surface:

Edge environments — `Status` is not the health signal; `Heartbeat` is. The endpoint Status field means up/down only for direct agents (1 = up, 2 = down). For edge agents (Type 4 = EdgeAgentOnDocker, 7 = EdgeAgentOnKubernetes) Status is not a reachability signal in either direction: Portainer sets it to 1 when the edge environment is created and again on every check-in, and never flips it to 2 (down) on its own. So a dead edge agent that last checked in an hour ago still reads Status: 1, and you may also see Status: 0 on an edge env that was provisioned but never completed a normal create/check-in path — neither value reflects current health. Don't read edge Status as up or down. Portainer judges an edge agent by its heartbeat: up if it checked in within 2 × interval + 20 seconds (the interval is EdgeCheckinInterval, falling back to the global Edge check-in setting, for standard agents; the smallest of the ping/command/snapshot intervals for async agents). The server exposes this as a computed Heartbeat boolean — which is exactly what the dashboard's environment badge renders ("Heartbeat" vs "Down").

For a reachability check that's correct across both kinds, project the heartbeat inputs, not just Status:

EndpointList(select="[].{id:Id,name:Name,type:Type,status:Status,heartbeat:Heartbeat,lastCheckIn:LastCheckInDate}")

Read it as: direct agent → trust `status` (1 = up); edge agent (`type` 4/7) → trust `heartbeat` (true = up) and ignore status.

Patterns for common questions

A few high-frequency questions and the projection that gets them in one call: