Release v1.0.22 - Group-Restricted Agents, OAuth2 Gate, MongoDB URI Override, Local-Only Group Fixes

May 2026

Upgrading from v1.0.21

This section covers everything you need to know to upgrade from v1.0.21 to v1.0.22.

Breaking Changes

There are no breaking changes in this release.

New Environment Variables

All new variables are backwards-compatible: default (empty) behavior matches v1.0.21 exactly.

Upgrade Instructions

Docker Compose

cd mcp-gateway-registry
git pull origin main
git checkout v1.0.22

# Review new env vars in .env.example and update your .env if needed
# Then rebuild and restart:
./build_and_run.sh

Kubernetes / Helm (EKS)

cd mcp-gateway-registry
git pull origin main
git checkout v1.0.22

# Update values.yaml if needed, then upgrade:
cd charts/mcp-gateway-registry-stack
helm upgrade mcp-gateway . -f your-values.yaml

No Helm chart dependency changes in this release; helm dependency build / update is not required.

Terraform / ECS

cd mcp-gateway-registry
git pull origin main
git checkout v1.0.22

# Update your .tfvars with any new variables (optional: MongoDB URI override
# via mongodb_connection_string / mongodb_connection_string_secret_arn).
cd terraform/aws-ecs
terraform plan
terraform apply

DockerHub Images

Pre-built images are available:

docker pull mcpgateway/registry:v1.0.22
docker pull mcpgateway/auth-server:v1.0.22
docker pull mcpgateway/currenttime-server:v1.0.22
docker pull mcpgateway/realserverfaketools-server:v1.0.22
docker pull mcpgateway/fininfo-server:v1.0.22
docker pull mcpgateway/mcpgw-server:v1.0.22
docker pull mcpgateway/metrics-service:v1.0.22

Major Features

Group-Restricted Agent Visibility

Agent publishers can now restrict which IdP groups see their agent by setting visibility: "group-restricted" and specifying allowedGroups at registration time, without needing an admin to change IAM scopes. Works as a second filter on top of the existing IAM group scope layer: users must pass both the IAM scope check and the allowed_groups check.

• Backend filtering in /api/agents list endpoint for non-admin users.
• Nginx forwards JWT group claims to the backend via X-Groups header.
• CLI supports --allowed-groups for both registration and filtering.
• Frontend registration and edit forms include a Visibility dropdown and Allowed Groups input.
• Compatible with all supported IdPs (Keycloak, Entra ID, Cognito, Okta, Auth0).

PR #923 | Issue #883 | Issue #922 | Full Guide | FAQ

OAuth2 Client Credentials Auth for Registration Gate

The admission-control registration gate added in v1.0.21 now supports OAuth2 Client Credentials as an authentication method in addition to Bearer tokens and API keys. Enables enterprise integrations that require short-lived, rotatable credentials fetched at runtime from Entra, Okta, Keycloak, or any RFC 6749 OAuth2 token endpoint. Includes in-memory token caching, automatic refresh on 401, and configurable scope. Wired through Docker Compose, Helm/EKS, and Terraform/ECS.

PR #924 | Issue #917

MongoDB Atlas and Replica-Set Support via Connection String Override

The storage layer now accepts a full MongoDB connection string via the new MONGODB_CONNECTION_STRING environment variable. When set, the URI takes precedence over the discrete DOCUMENTDB_* variables, enabling MongoDB Atlas (mongodb+srv://...), replica sets, and any URI-level tuning not expressible through the discrete variables. When empty, the registry falls back to the existing variables so current deployments keep working unchanged.

• Plumbed through the Python storage client, Docker entrypoint wait loops, ops scripts (init-documentdb-indexes.py, manage-documentdb.py, load-scopes.py), Helm chart (values.yaml and deployment templates), and the ECS Terraform module.
• ECS Terraform exposes both mongodb_connection_string (plain) and mongodb_connection_string_secret_arn (Secrets Manager ARN) variables; the Secrets Manager variant is preferred when the URI contains credentials, keeping them out of Terraform state.
• In addition to MongoDB CE and Amazon DocumentDB, MongoDB Atlas is now a supported backend.

PR #947 | PR #951 | FAQ: How do I configure MongoDB Atlas instead of MongoDB CE?

IAM: Local-Only Group Lifecycle Fixes

Groups created in the Registry UI with the Create in identity provider checkbox unchecked (local-only shadow groups) now have a complete lifecycle. Previously, PATCH and DELETE on these groups still called the IdP unconditionally and failed with HTTP 403 when the registry's IdP app lacked write scopes (e.g. Entra apps with only Group.Read.All).

• Scope documents now persist is_idp_managed at creation time; PATCH and DELETE gate their IdP calls on this flag.
• Typed IdPForbiddenError and IdPNotFoundError exceptions are raised by every provider manager (Keycloak, Entra, Okta, Auth0); route handlers treat 403/404 as non-fatal and fall through to the MongoDB mutation.
• GET /api/management/iam/groups now merges IdP groups with local-only MongoDB scopes so every UI picker (Groups page, M2M "Register existing client", Users > Edit Groups) can see them.
• New "Local-only" / "IdP-managed" badges in the Groups list; edit drawer locks the "Create in identity provider" checkbox (self-heal path is delete + recreate).
• Legacy scope documents that predate the flag are lazily backfilled on GET and eagerly on list.
• Audit records carry a structured idp_skip_reason field (local_only / forbidden / not_found).

PR #950 | Issue #946

What's New

IAM and Access Control

• Default "Create in identity provider" checkbox to unchecked on the Groups creation form, matching the recommended "read from IdP, manage authorization in the registry" operating model (#921, #916).
• IAM > M2M Accounts UI now lists clients registered via POST /api/iam/m2m-clients alongside legacy-created records. Adds Provider (manual / okta / auth0 / keycloak / entra) and Registered by columns; Edit and Delete on manual records route through /api/iam/m2m-clients/{client_id}; rows synced from the IdP show those actions as disabled with an explanatory tooltip (#949, #945).
• "Register existing client" button in IAM > M2M Accounts: register a client_id that already exists in your IdP without requiring an IdP Admin API token. UI equivalent of the registry_management.py m2m-client-create command (#949).
• Search box on the M2M Accounts group-selection checklist (Edit, Create, Register views) for easier group picking when many groups exist (#950).
• Users > Edit Groups now tolerates local-only groups in the payload without blocking saves; "group not found" on net additions maps to 400 with guidance pointing at the correct group_mappings workflow (#950).
• Python SDK: api/registry_client.py GroupSummary gains an optional is_idp_managed field, and create_keycloak_group accepts create_in_idp (#950).

Authentication

• Include ROOT_PATH in OAuth2 redirect URIs so path-routed deployments (routingMode = path) redirect correctly after login and logout (#926, #500).

Registration Gate

• OAuth2 Client Credentials authentication support with Entra / Okta / Keycloak examples (#924, #917).
• FAQ now includes Helm chart value references for OAuth2 gate configuration.

Telemetry and Observability

• Telemetry startup and heartbeat payloads now include embeddings_backend_kind, and embeddings_provider has moved from heartbeat to startup so it's captured reliably even for short-lived instances (#935, #934).
• Usage report: "Most Active Instances" section gets a new column showing the embeddings provider per instance (#928).

Deployment and Infrastructure

• Terraform module: aws-ecs deployment now supports the MONGODB_CONNECTION_STRING override via two variables (mongodb_connection_string plain or mongodb_connection_string_secret_arn via Secrets Manager). Defaults preserve current behavior (#951).
• Allow overriding the deployment container registry and image pull policies via Helm values and Terraform variables for air-gapped or mirror-registry deployments (#948).
• Helm chart image tags bumped to 1.0.21 (baseline for this release cycle).

Documentation

• New FAQ: How do I configure MongoDB Atlas instead of MongoDB CE? covering all three deployment types (Docker Compose, ECS Terraform with Secrets Manager variant, Kubernetes/EKS with envFrom secretRef). Linked from the README "What's New".
• Slide deck refreshed with the latest features, roadmap, and metrics.

Bug Fixes

• Fix a number of issues related to URL paths and missing env vars, especially in path-routed Helm deployments (#931).
• Handle null description in virtual server documents without raising 500 on GET (#932, follow-up cleanup and tests in #940).
• PATCH and DELETE on local-only (create_in_idp=False) groups no longer fail with IdP 403 when the registry's IdP app lacks admin write scopes (#950, #946).

Issues Fixed

Pull Requests Included

Contributors

Thank you to all contributors for this release:

• Amit Arora (@aarora79)
• omrishiv (@omrishiv)
• Alejandro Nuñez Cabello (@alejandronunezcabello)

Support

• GitHub Issues
• GitHub Discussions
• Documentation

Full Changelog: v1.0.21...v1.0.22

What's Changed

• fix(iam): default 'Create in identity provider' checkbox to unchecked by @aarora79 in #921
• feat(agents): end-to-end group-restricted agent visibility by @aarora79 in #923
• feat(gate): add OAuth2 Client Credentials auth for registration gate by @aarora79 in #924
• feat(usage-report): add embeddings provider column to Most Active Instances by @aarora79 in #928
• fix: multiple path-routing, logout, and OAuth redirect bugs on Helm deployments by @omrishiv in #931
• fix(auth): include ROOT_PATH in OAuth2 redirect URIs by @aarora79 in #926
• feat(telemetry): add embeddings_backend_kind field; move embeddings_provider to startup (#934) by @aarora79 in #935
• fix: handle null description in virtual server documents by @alejandronunezcabello in #932
• chore: follow-up cleanup and tests for #932 null-description fix by @aarora79 in #940
• allow overriding deployment registry and pull policies by @omrishiv in #948
• fix(iam): surface /api/iam/m2m-clients records in IAM > M2M Accounts UI (#945) by @aarora79 in #949
• fix(iam): skip IdP admin calls for local-only groups (#946) by @aarora79 in #950
• Feat/extended mongo connection string support by @omrishiv in #947
• feat(terraform,docs): MONGODB_CONNECTION_STRING follow-up to #947 by @aarora79 in #951
• update Kubernetes FAQ for MongoDB Atlas by @omrishiv in #952
• chore: update Helm chart image tags to 1.0.22 by @aarora79 in #953

Full Changelog: v1.0.21...v1.0.22