portainer-mcp Updates & Release Notes

2.43.3 — Targets Portainer 2.43.x

Added

Configurable upstream timeout (PORTAINER_TIMEOUT, seconds) — #80. The upstream Portainer HTTP timeout was hardcoded at 30s, routinely too short for stack creation (Portainer deploys synchronously — the request holds open through image pull and compose up). The default rises to 120s, the connect phase stays capped at 10s so an unreachable Portainer still fails fast, and the knob applies to both transports. Non-numeric or non-positive values refuse to boot; the resolved posture is logged at startup.

Changed

Post-send timeouts now say the write may have succeeded (#80). A request that times out after reaching Portainer is ambiguous, not failed — Portainer keeps processing, which is how two timed-out stack creates left two stack records behind in #80. FastMCP's stock error ("please retry") invites exactly the duplicate-creating reflex, so ReadTimeout/WriteTimeout errors are rewritten to name the ambiguity, instruct the model to verify current state (e.g. StackList) before retrying, and point at PORTAINER_TIMEOUT. Connect-phase timeouts are left untouched — the request never reached Portainer.

Full changelog: https://github.com/portainer/portainer-mcp/blob/2.43.3/CHANGELOG.md

2.43.2 — Targets Portainer 2.43.x

Fixed

Guidance gate no longer keys on Mcp-Session-Id — clients behind session-churning bridges are never locked out (#75). The gate is now a toll booth: the first tool call from a caller whose idle window has lapsed is answered with the operating guide itself (plus a retry instruction) instead of a "call get_guidance and retry" bounce, and the caller is marked guided immediately — delivery is the proof, so nothing needs to be correlated across requests and there is no lockout state. Callers are identified by the authenticated principal (the per-user API-key digest over HTTP, the process over stdio), the scoping SEP-2567 recommends now that major clients mint a fresh session id per tool call. The window slides with activity (PORTAINER_MCP_GUIDANCE_TTL, default 1800s), so re-delivery happens on the next conversation, not mid-task — including over stdio, where the old gate fired only once per process lifetime. PORTAINER_MCP_DISABLE_GUIDANCE_GATE=1 disables enforcement entirely (install the hygiene skill manually on clients in that case); get_guidance remains available on demand.

Added

Trust-proxy auth posture (PORTAINER_MCP_TRUST_PROXY_AUTH=1) for deployments behind an identity-aware proxy that owns the Authorization header (e.g. Pomerium in MCP server mode) — #76. The gate-token compare is replaced by per-request proxy attestation: inherited from the PORTAINER_MCP_TRUST_PROXY_TLS + PORTAINER_MCP_FORWARDED_ALLOW_IPS declaration behind a TLS-terminating proxy, or an explicit PORTAINER_MCP_TRUSTED_PROXY_AUTH_IPS socket-peer allowlist when the server terminates TLS itself. Exactly one auth posture must be declared (gate token XOR trust-proxy); every degenerate combination — both, neither, trust + plaintext opt-out, wildcard allowlists (* or zero-prefix CIDRs), a server-held cert alongside the inherited shape, a peer allowlist without the trust flag — refuses to boot, and the per-user X-Portainer-API-Key validation floor is unchanged. New audit outcomes untrusted_scheme / untrusted_peer; audit records under this posture carry auth_posture: "trust_proxy".

Full changelog: https://github.com/portainer/portainer-mcp/blob/2.43.2/CHANGELOG.md

2.43.1 — Targets Portainer 2.43.x

Added

New GITOPS profile (#74) bundling the gitops tag — register/list/test git sources and browse refs (the GitOps source management surface).

JMESPath errors now diagnose double-escaped quotes. When a select expression fails to parse and contains literal " (the JSON-in-JSON double-escaping models fall into), the error names the cause and suggests plain double quotes or a contains(...) filter instead of the lexer's opaque Unknown token message.

Hygiene guide: four field-tested additions from agent usage reports — the backslash-escaping trap and its contains() workaround; the 400 … EOF rejection when a write call sends zero body fields (e.g. a bare StackGitRedeploy — pass Prune: false); verifying a K8s deploy end-to-end via the service-proxy path; and which StackCreateKubernetesGit fields are the blessed path (SourceID) vs the still-functional deprecated inline Repository* fields.

Changed

gitops is now in the default profile set (#74). A registered GitOps source is required to deploy a git-backed stack, so gitops now rides along inside both DOCKER and KUBERNETES (next to stacks) and the default PORTAINER_PROFILES becomes BASE,DOCKER,KUBERNETES,GITOPS. Without it, git-based stack deploys fail for lack of a source.

Full changelog: https://github.com/portainer/portainer-mcp/blob/2.43.1/CHANGELOG.md

2.43.0 — Targets Portainer 2.43.x

Changed

Embedded spec bumped to Portainer EE 2.43.0 (#73) (was 2.42.0). Total operations 409 → 412; default BASE,DOCKER,KUBERNETES profile coverage 193 → 190, five-profile union 334 → 329. Upstream resolved a long-standing tagging defect by moving the Edge-agent callbacks (heartbeat/status, async poll, alert + chart status, edge stack/job sync) off the endpoints tag onto a new dedicated edge_agent tag, so they no longer leak into the DOCKER profile as tools that can never succeed for a non-agent caller. New allowlist orphan tag (2 ops, URL allow list).

Edge-agent callback exclusion is now tag-based (#73). spec/patch_spec.py drops every operation carrying the new edge_agent tag (eight callbacks that 403 for any caller without X-PortainerAgent-EdgeID), replacing the previous four-op (method, path) matcher — possible because 2.43.0 also gave 15 of 16 previously-unnamed operations an operationId. Pruned patcher entries that no longer match anything in 2.43.0 (SharedGit{Get,Update,Delete}, the os.FileMode / v1.Duration enum strips).

Full changelog: https://github.com/portainer/portainer-mcp/blob/2.43.0/CHANGELOG.md

2.42.6 — Targets Portainer 2.42.x

Added

Claude Desktop one-click .mcpb bundles (#72). The server now ships as a self-contained PyInstaller binary bundle (no Python/uv/Node needed on the client), built per-platform (darwin-arm64, win32-x64, linux-x64) and attached to this release.

Bundled hygiene guidance, served on demand via a get_guidance tool (#72). The full portainer-mcp-hygiene skill now ships with every install method (uvx, container, .mcpb) from the same SKILL.md, so it can't drift. A one-time-per-session gate requires get_guidance so the guide reliably lands in context rather than relying on the truncatable instructions field. A missing guide is now a hard startup failure.

Changed

Hygiene skill guidance expanded (#71) to cover mutations and typed Kubernetes field shapes, and to report its own gaps (failing select examples, redaction/truncation mismatches, missing tools) as scrubbed, consent-gated issues against portainer/portainer-mcp.

Removed

Manual hygiene-skill curl install instructions (README, docs/distribution/claude-desktop.md). The guide is now bundled and served via get_guidance, so the curl snippets were redundant and drift-prone.

Full changelog: https://github.com/portainer/portainer-mcp/blob/2.42.6/CHANGELOG.md

2.42.5 — Targets Portainer 2.42.x

Warning

Breaking change for HTTP-transport deployments.

The HTTP credential model is now per-user passthrough. The bearer token is only an access gate; each caller must send their own Portainer API key in the X-Portainer-API-Key header.

PORTAINER_API_KEY now hard-fails at startup under PORTAINER_MCP_TRANSPORT=http — it is a stdio-only credential.

Migration: remove PORTAINER_API_KEY from your HTTP deployment and have each client send X-Portainer-API-Key alongside the existing Authorization: Bearer <gate-token>. stdio transport is unaffected.

Added

TLS posture enforcement on non-loopback HTTP binds (#67). The server won't boot on a non-loopback bind unless you declare a cert (PORTAINER_MCP_TLS_CERT/_TLS_KEY), proxy TLS attestation (PORTAINER_MCP_TRUST_PROXY_TLS=1 + ..._FORWARDED_ALLOW_IPS), or the loud plaintext opt-out (PORTAINER_MCP_DANGEROUSLY_ALLOW_PLAINTEXT_HTTP=1). Loopback exempt; self-signed certs warn but don't block.

Changed

Per-user Portainer API-key passthrough over HTTP (#66) — see the warning above. Validation is cached positive-only (PORTAINER_MCP_AUTH_CACHE_TTL, default 60s); the per-user key is never logged.

Bumped fastmcp to >=3.4.2, dropped the direct starlette pin (CVE floor now carried transitively).

Documentation

Hygiene skill: an edge agent's health comes from its heartbeat, not its Status field (#70).

Full changelog: https://github.com/portainer/portainer-mcp/blob/2.42.5/CHANGELOG.md