This page describes compatibility for the current tagged release, mcpgw v0.8.1. Read the release notes for every version between your installed build and the target build before upgrading.

Supported release artifacts

The v0.8.1 release publishes Linux binaries and a multi-architecture container for linux/amd64 and linux/arm64. The Helm chart at helm/mcpgw targets app version 0.8.1. Verify checksums and the release signature before replacing an existing binary.

MCP protocol dialects

mcpgw resolves the MCP dialect per request. Stateful protocol revisions through 2025-06-18 continue to use the legacy behavior; the stateless 2026-07-28 revision is also supported. A client migration is not required merely because the gateway is upgraded.

Use top-level allowed_protocol_versions when you need an explicit deployment allowlist. This setting requires a restart. Requests outside the allowlist return -32022 unsupported_protocol_version.

For 2026-07-28, account for these behaviors when writing policy:

server/discover replaces initialize in the stateless handshake path.
tasks/* and subscriptions/listen remain fail-closed unless policy permits them.
when.result_type: input_required governs MRTR results; retain legacy method rules while legacy clients remain in service.
task handles are pinned to the upstream that minted them. Configure this with top-level task_affinity. The earlier tasks.affinity spelling existed only before the v0.7.0 tag, so no tagged-version migration accepts that spelling.

v0.7.0: omitted policy default became deny

Starting in v0.7.0, an omitted policy.default_action means deny. Older configurations that relied on implicit allow must add this explicitly before upgrading:

policy:
  default_action: allow
  rules: []

That setting preserves the old behavior only as an upgrade bridge. For production, prefer default_action: deny plus narrow allow rules.

v0.8.1: guardrail request-body cap

Each guardrail endpoint now defaults max_body_bytes to 1 MiB. An oversized JSON-RPC envelope is refused rather than truncated, the webhook is not contacted, and the endpoint’s configured fail posture is applied. Fail-closed returns a denial with guardrail_body_too_large; fail_open: true allows the request and records error_failopen.

Deployments that intentionally sent larger envelopes in v0.8.0 can set a higher limit or 0 to restore uncapped behavior. Make that choice deliberately: guardrails receive the full matched envelope, and synchronous transfer still consumes the endpoint timeout budget.

Reload versus restart

SIGHUP re-reads and validates the complete config, then applies reloadable sections atomically. It also re-reads the license file at the existing path. Invalid replacements are rejected and the previous live state is preserved.

Common reloadable sections include policy, guardrails, upstream routing, audit sinks, telemetry, authentication, identity, and tool search. A restart is required for listener changes, license.path, trusted_proxies, enabling or disabling TLS, rate-limit store type, shutdown timing, allowed_protocol_versions, task_affinity, and subscription lifetime limits. /readyz reports accepted config differences that remain restart_pending. The configuration reference is authoritative for each key.

License and rollback constraints

Licenses are Ed25519-signed JWTs verified offline against the public key embedded in the binary. A token must have audience mcpgw, valid time claims, and a signature matching that build’s embedded key. Grace is a signed grace_days claim, not a YAML setting.

Before rollback, confirm that the older binary embeds the key that signed the deployed license and understands every configured key. Keep a copy of the last-known-good binary, config, chart values, and license outside the mutable deployment path. If a rollback target predates a newly used config key, restore its matching config rather than asking the older binary to parse the newer file.

For a rolling upgrade:

Validate the new config with the target binary.
Upgrade one replica and confirm /healthz, /readyz, policy decisions, audit output, and telemetry.
Continue the rollout only after the canary serves both protocol dialects used by your clients.
Stop and restore the last-known-good binary and matching config on a material regression.

See CHANGELOG.md for the complete release history and license rotation for a no-downtime token replacement.

Compatibility and upgrades