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}")