Skip to content

portainer/portainer-mcp

v2.42.1 Breaking

This release includes 1 breaking change for platform teams planning a safe upgrade.

Published 9d MCP SaaS Integrations
✓ No known CVEs patched
Read the diff → Tool health → What is this tool? →

✓ No known CVEs patched in this version

Topics

ai containerization llm mcp mcp-server portainer

Affected surfaces

auth breaking_upgrade

ReleasePort's take

Moderate signal
editorial:auto 8d

Portainer MCP 2.42.1 adds several security‑focused features (auth token, allowlist, audit logging) and changes the development workflow to require PORTAINER_MCP_AUTH_TOKEN for local HTTP requests.

Why it matters: Required bearer auth via PORTAINER_MCP_AUTH_TOKEN now triggers on every HTTP transport request; developers must set this env var for `make dev` or fail authentication.

Summary

AI summary

HTTP transport now mandates bearer-token authentication.

Changes in this release

Breaking High

Breaks `make dev` to now require PORTAINER_MCP_AUTH_TOKEN for local HTTP loop.

Breaks `make dev` to now require PORTAINER_MCP_AUTH_TOKEN for local HTTP loop.

Source: llm_adapter@2026-05-26

Confidence: high

 —
Feature High

Adds required HTTP bearer auth via PORTAINER_MCP_AUTH_TOKEN for http transport.

Adds required HTTP bearer auth via PORTAINER_MCP_AUTH_TOKEN for http transport.

Source: llm_adapter@2026-05-26

Confidence: high

 —
Feature Medium

Adds container image docker.io/portainer/portainer-mcp for every release tag.

Adds container image docker.io/portainer/portainer-mcp for every release tag.

Source: llm_adapter@2026-05-26

Confidence: high

 —
Feature Medium

Adds DNS‑rebinding allowlist via PORTAINER_MCP_ALLOWED_HOSTS for HTTP transport.

Adds DNS‑rebinding allowlist via PORTAINER_MCP_ALLOWED_HOSTS for HTTP transport.

Source: llm_adapter@2026-05-26

Confidence: high

 —
Feature Medium

Adds auth audit log under portainer_mcp.audit for every HTTP auth attempt.

Adds auth audit log under portainer_mcp.audit for every HTTP auth attempt.

Source: llm_adapter@2026-05-26

Confidence: high

 —
Feature Medium

Adds selectable log format via PORTAINER_MCP_LOG_FORMAT (text|json).

Adds selectable log format via PORTAINER_MCP_LOG_FORMAT (text|json).

Source: llm_adapter@2026-05-26

Confidence: high

 —
Feature Low

Consolidates operator config reference into docs/configuration.md.

Consolidates operator config reference into docs/configuration.md.

Source: llm_adapter@2026-05-26

Confidence: high

 —
Full changelog

PyPI: https://pypi.org/project/mcp-portainer/2.42.1/
Docker Hub: https://hub.docker.com/r/portainer/portainer-mcp/tags?name=2.42.1

Targets Portainer 2.42.x. First build to ship a container image alongside the PyPI wheel, and the first release with a bearer-gated HTTP transport.

Added

  • Container image at docker.io/portainer/portainer-mcp, published on every X.Y.Z tag push from .github/workflows/release-docker.yml. Tagged X.Y.Z and X.Y per release; no latest. See docs/docker.md.
  • HTTP bearer auth. New PORTAINER_MCP_AUTH_TOKEN env, required when PORTAINER_MCP_TRANSPORT=http and ignored for stdio. Strict validation at startup (min 32 chars, ASCII printable, no whitespace — loud-fail on any defect); constant-time comparison via hmac.compare_digest; masked fingerprint in the startup log, full value never logged. Wired through FastMCP's TokenVerifier protocol — FastMCP renders the 401 + WWW-Authenticate response on failure.
  • DNS-rebinding allowlist for the HTTP transport. PORTAINER_MCP_ALLOWED_HOSTS (default 127.0.0.1:*,localhost:*,[::1]:*) validates the Host header on every request; mismatches return 421 with a body that names the env var. The Origin allowlist is hardcoded to localhost — programmatic MCP clients omit Origin and pass through. A startup WARNING fires when the bind host is non-loopback while the allowlist is still the localhost defaults, so the "deployed-then-it-421s" case self-diagnoses.
  • Auth audit log. Every HTTP auth attempt emits a structured record under the portainer_mcp.audit sub-logger with outcome, client_ip, user_agent, and the MCP session_id — joinable against the FastMCP-layer request_start / request_success records by session_id. The attempted token is never written.
  • Selectable log shape. PORTAINER_MCP_LOG_FORMAT=text|json (default text; container image overrides to json). In json mode, records whose message is itself a JSON object are merged into the envelope, so audit and request records become first-class fields rather than nested strings.
  • Consolidated operator config reference at docs/configuration.md, grouped by concern (transport, hardening, profiles, behaviour, logging) with the audit and traceability story documented end-to-end.

Changed

  • make dev now requires PORTAINER_MCP_AUTH_TOKEN. Local HTTP dev loop is no longer auth-less — add the token to .env and pass it via claude mcp add … --header "Authorization: Bearer <token>".

Full Changelog: https://github.com/portainer/portainer-mcp/compare/2.42.0...2.42.1

Breaking Changes

  • When `PORTAINER_MCP_TRANSPORT=http`, the new env var `PORTAINER_MCP_AUTH_TOKEN` is required; missing or invalid token causes startup failure.
View diff on GitHub

Weekly OSS security release digest.

The CVE patches and breaking changes that affected production tools this week. One email, every Sunday.

No spam, unsubscribe anytime.

Share this release

Share on X Share on Bluesky

Track portainer/portainer-mcp

Get notified when new releases ship.

Sign up free

About portainer/portainer-mcp

Portainer MCP server

All releases →

Related context

Beta — feedback welcome: [email protected]