Release 1.29.0 - Reusable Egress Hardening & IdP-Authenticated Embeddings

August 2026

Upgrading from 1.28.0

This section covers everything you need to know to upgrade from 1.28.0 to 1.29.0.

Breaking Changes

AWS EC2 IMDS credential fallback is now disabled by default on the auth-server and registry tasks.

To shrink the blast radius of a server-side request forgery (SSRF) or remote-code-execution bug, the auth-server and registry containers now set AWS_EC2_METADATA_DISABLED=true, which stops the AWS SDK (boto3) from falling back to the EC2 Instance Metadata Service for credentials or region. This is wired across Helm, Terraform/ECS, and CDK, and the variable is chart-managed (it cannot be overridden via extraEnv / *_extra_env).

• No action needed if your pods/tasks receive credentials out-of-band, which is the normal and recommended setup: EKS IRSA or Pod Identity, or an ECS task role. These are unaffected.
• Action required only if a deployment relies exclusively on the EC2 worker-node instance profile (reachable solely through IMDS) to supply application credentials. That configuration is an anti-pattern and is not supported with this default on. Migrate to IRSA / Pod Identity / a task role, or opt out explicitly:
  • Helm: set registry.app.disableEc2ImdsFallback=false (and/or auth-server.app.disableEc2ImdsFallback=false).
  • Terraform/ECS: the value is chart-managed; use a task role instead of node-instance-profile credentials.

There are no other breaking changes. The embeddings IdP-auth and Entra v1 scope features below are strictly opt-in and leave existing deployments unchanged.

New Environment Variables

All new variables are opt-in; leaving them unset preserves 1.28.0 behavior.

Upgrade Instructions

Docker Compose

cd mcp-gateway-registry
git pull origin main
git checkout 1.29.0

# Review new opt-in embeddings variables in .env.example and update your .env if needed.
# Then rebuild and restart:
./build_and_run.sh

Kubernetes / Helm (EKS)

Files under charts/ changed in this release (new embeddings values, deployment env, reserved-name lists, and Entra scope handling), so the packaged subcharts must be rebuilt before upgrading.

cd mcp-gateway-registry
git pull origin main
git checkout 1.29.0

# REQUIRED: rebuild the packaged subcharts (the .tgz files are gitignored and
# only repackage when these run -- a plain upgrade would use stale subcharts).
cd charts/mcp-gateway-registry-stack
helm dependency build
helm dependency update

# Update values.yaml if needed (e.g. registry.embeddings.*), then upgrade:
helm upgrade mcp-gateway . -f your-values.yaml

Terraform / ECS

cd mcp-gateway-registry
git pull origin main
git checkout 1.29.0

# New optional variables: embeddings_auth_mode, embeddings_idp_* , embeddings_response_format.
cd terraform/aws-ecs
terraform plan
terraform apply

Major Features

Reusable egress and header-boundary hardening

Hardens the registry's reusable outbound-egress and header-handling boundary against SSRF, credential exfiltration, and sensitive-data logging.

• One canonical, fail-closed SSRF/URL guard for every outbound fetch: a single IP classifier that understands obfuscated IPv4 literals (decimal/octal/hex/short-form/trailing-dot) and embedded-IPv4 IPv6 transports (IPv4-mapped, NAT64, 6to4, Teredo, with scope-id stripping), with cloud/workload metadata endpoints (AWS IMDS/ECS/EKS plus IPv6 fd00:ec2::*, and Alibaba 100.100.100.200) hard-denied even under an operator allowlist.
• DNS-rebinding defeated by pinning the resolved public IP at connect time and re-validating per redirect, with async resolution under a fixed deadline.
• A dedicated HTTPS-only, empty-allowlist profile for credential-bearing OAuth token endpoints so a token exchange can never inherit the proxy profile's internal-target bypass.
• Decrypted credentials are bound to the exact validated destination (the real /mcp/, /sse, and query-appended URLs) before any credential is decrypted; a missing/unsafe/identity-mismatched destination withholds all server-provided headers.
• Response projection is now a recursive, non-mutating token-free copy applied uniformly across reads, register/update responses, webhooks, and lifecycle events (covering nested egress_oauth.client_secret_encrypted, per-version credentials, and rating PII).
• The bundled airegistry-tools MCP server is admitted only through an exact (entity_type, path, normalized-target) identity match, including for security scans.
• AWS_EC2_METADATA_DISABLED=true on the auth-server and registry tasks (Terraform + CDK + Helm), closing boto3's own IMDS credential provider - a vector the egress guard structurally cannot see.

PR #1564

IdP-authenticated embedding endpoints

Semantic-search embeddings can now be served by an OpenAI-compatible endpoint (e.g. LiteLLM) protected by your identity provider. When EMBEDDINGS_AUTH_MODE=idp, the registry fetches an OAuth2 client-credentials bearer token from any standard IdP (Keycloak, Microsoft Entra ID, Okta, Auth0, PingFederate), caches it with an expiry buffer, and injects it on every embedding call instead of a static API key. First-class configuration is wired across Docker, Terraform/ECS, and Helm (registry.embeddings.* with an existing-secret reference for the client secret). Fully backwards compatible - the default is the existing static-key path.

PR #1611 (closes #1415)

raw_array embeddings response adapter

Some OpenAI-compatible endpoints accept the standard request but return a bare array of vectors ([[0.12, ...], ...]) instead of the {"data": [{"embedding": [...]}]} envelope, which LiteLLM cannot parse. Setting EMBEDDINGS_RESPONSE_FORMAT=raw_array makes the registry call the endpoint directly and extract the vectors (also accepting the array wrapped under an embeddings/data/vectors key). Opt-in; the default remains the OpenAI envelope.

PR #1624

Microsoft Entra v1 api:// scope pass-through

Entra applications that expose v1-style api://<app-id>/<scope> scopes are now supported end to end: the scope is passed through verbatim in the Protected Resource Metadata, with audience normalization, and surfaced in the System Config UI. This unblocks IDE/coding-assistant login for Entra tenants (issue #990).

PR #1618 (closes #990), PR #1622

What's New

Security & Egress Hardening

• Consolidated fail-closed SSRF/URL guard, credential binding, token-free response projection, credentialed-OAuth profile, and IMDS-disable parity across Terraform/CDK/Helm (#1564)

Embeddings

• IdP-authenticated (OAuth2 client-credentials) embedding endpoints with token caching and cross-surface config (#1611)
• raw_array response adapter for non-envelope OpenAI-compatible endpoints (#1624)

Authentication

• Microsoft Entra v1 api:// scope verbatim pass-through in PRM + audience normalization (#1618)
• Entra per-server-PRM predicate consolidated to a single source of truth; entra_scope_format and entra_application_id_uri surfaced in System Config (#1622)
• Relay X-Authorization to the internal registry-tools server and derive the connect-URL /mcp suffix from append_mcp_path (#1621)

CLI

• egress-configure --provider custom now forwards the custom authorize_url / token_url the server requires (#1602, closes #1601)

Observability

• Prevent a silent heartbeat drop in the usage-report telemetry export (#1592)

Documentation

• Roadmap shifted to the 1.29.0 cascade and slide deck refreshed (#1630)
• IdP embeddings FAQ and .env.example documentation for the new opt-in variables (#1611, #1624)

Dependency Updates

• Weekly lockfile updates and GitHub Actions group bumps (#1593, #1594, #1616, #1617)

Release Housekeeping

• Update image tags to 1.28.0 (#1591)

Bug Fixes

• Prevent silent heartbeat drop in the usage-report export, so telemetry exports no longer drop events under the mongosh timeout (#1592)
• egress-configure --provider custom was unusable because the CLI never forwarded the custom OIDC URLs; it now does (#1602)
• Relay X-Authorization to the internal registry-tools server and fix the connect-URL /mcp suffix derivation (#1621)
• Accept a per-server audience with egress off and reject an id_token used as an access token (part of #1618)

Closed Issues

Pull Requests Included

Contributors

Thank you to all contributors for this release:

• Amit Arora (@aarora79)
• omrishiv (@omrishiv)
• Prateek Sinha (@shekharprateek)
• Bill Tarr (@billtarr-aws)

Automated dependency updates were contributed by Dependabot and the repository's GitHub Actions workflows.

Support

• GitHub Issues
• GitHub Discussions
• Documentation

Full Changelog: 1.28.0...1.29.0

What's Changed

• chore: update image tags to 1.28.0 by @github-actions[bot] in #1591
• fix(telemetry): prevent silent heartbeat drop in usage-report export by @aarora79 in #1592
• chore(deps): bump the actions group in /.github/workflows with 3 updates by @dependabot[bot] in #1593
• chore(deps): weekly lockfile update (2026-08-03) by @github-actions[bot] in #1594
• fix(cli): forward the custom-OIDC fields so egress-configure --provider custom works by @billtarr-aws in #1602
• chore(deps): bump the actions group in /.github/workflows with 2 updates by @dependabot[bot] in #1616
• chore(deps): weekly lockfile update (2026-08-10) by @github-actions[bot] in #1617
• fix(auth,frontend): relay X-Authorization to internal registry-tools + align connect-URL /mcp with PRM resource by @aarora79 in #1621
• feat(entra): Microsoft Entra v1 scope pass-through by @omrishiv in #1618
• chore(entra): review follow-ups for #1618 (shared per-server-PRM predicate + config surface) by @aarora79 in #1622
• feat(embeddings): support IdP-authenticated embedding endpoints by @shekharprateek in #1611
• feat(embeddings): add raw_array response adapter for non-envelope endpoints by @aarora79 in #1624
• Harden reusable egress and header boundaries by @omrishiv in #1564
• docs: shift roadmap to 1.29.0 cascade and refresh slide deck by @aarora79 in #1630
• docs: Add 1.29.0 release notes by @aarora79 in #1631

Full Changelog: 1.28.0...1.29.0