# 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

| Variable | Default | Description |
|----------|---------|-------------|
| `REGISTRATION_GATE_OAUTH2_TOKEN_URL` | *(empty)* | OAuth2 token endpoint for client credentials flow. Required when `REGISTRATION_GATE_AUTH_TYPE=oauth2_client_credentials`. Examples: Entra `https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token`, Okta `https://{domain}/oauth2/default/v1/token`, Keycloak `https://{host}/realms/{realm}/protocol/openid-connect/token`. |
| `REGISTRATION_GATE_OAUTH2_CLIENT_ID` | *(empty)* | Client ID for the client credentials flow. |
| `REGISTRATION_GATE_OAUTH2_CLIENT_SECRET` | *(empty)* | Client secret for the client credentials flow. |
| `REGISTRATION_GATE_OAUTH2_SCOPE` | *(empty)* | OAuth2 scope parameter (optional). Example (Entra): `api://your-app-id/.default`. |
| `MONGODB_CONNECTION_STRING` | *(empty)* | Optional full MongoDB connection string override. When set, takes precedence over the discrete `DOCUMENTDB_*` variables. Use for MongoDB Atlas (`mongodb+srv://...`), replica sets, or any URI-level tuning not expressible via the discrete variables. Leave empty to keep using the existing `DOCUMENTDB_*` variables. |

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

### Upgrade Instructions

#### Docker Compose

```bash
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)

```bash
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

```bash
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:

```bash
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](https://github.com/agentic-community/mcp-gateway-registry/pull/923) | [Issue #883](https://github.com/agentic-community/mcp-gateway-registry/issues/883) | [Issue #922](https://github.com/agentic-community/mcp-gateway-registry/issues/922) | [Full Guide](https://github.com/agentic-community/mcp-gateway-registry/blob/main/docs/agent-visibility-and-group-access.md) | [FAQ](https://github.com/agentic-community/mcp-gateway-registry/blob/main/docs/faq/group-restricted-agent-visibility.md)

### 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](https://github.com/agentic-community/mcp-gateway-registry/pull/924) | [Issue #917](https://github.com/agentic-community/mcp-gateway-registry/issues/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](https://github.com/agentic-community/mcp-gateway-registry/pull/947) | [PR #951](https://github.com/agentic-community/mcp-gateway-registry/pull/951) | [FAQ: How do I configure MongoDB Atlas instead of MongoDB CE?](https://github.com/agentic-community/mcp-gateway-registry/blob/main/docs/faq/configuring-mongodb-atlas-backend.md)

### 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](https://github.com/agentic-community/mcp-gateway-registry/pull/950) | [Issue #946](https://github.com/agentic-community/mcp-gateway-registry/issues/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](https://github.com/agentic-community/mcp-gateway-registry/pull/921), [#916](https://github.com/agentic-community/mcp-gateway-registry/issues/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](https://github.com/agentic-community/mcp-gateway-registry/pull/949), [#945](https://github.com/agentic-community/mcp-gateway-registry/issues/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](https://github.com/agentic-community/mcp-gateway-registry/pull/949)).
- Search box on the M2M Accounts group-selection checklist (Edit, Create, Register views) for easier group picking when many groups exist ([#950](https://github.com/agentic-community/mcp-gateway-registry/pull/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](https://github.com/agentic-community/mcp-gateway-registry/pull/950)).
- Python SDK: `api/registry_client.py` `GroupSummary` gains an optional `is_idp_managed` field, and `create_keycloak_group` accepts `create_in_idp` ([#950](https://github.com/agentic-community/mcp-gateway-registry/pull/950)).

### Authentication

- Include `ROOT_PATH` in OAuth2 redirect URIs so path-routed deployments (`routingMode = path`) redirect correctly after login and logout ([#926](https://github.com/agentic-community/mcp-gateway-registry/pull/926), [#500](https://github.com/agentic-community/mcp-gateway-registry/issues/500)).

### Registration Gate

- OAuth2 Client Credentials authentication support with Entra / Okta / Keycloak examples ([#924](https://github.com/agentic-community/mcp-gateway-registry/pull/924), [#917](https://github.com/agentic-community/mcp-gateway-registry/issues/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](https://github.com/agentic-community/mcp-gateway-registry/pull/935), [#934](https://github.com/agentic-community/mcp-gateway-registry/issues/934)).
- Usage report: "Most Active Instances" section gets a new column showing the embeddings provider per instance ([#928](https://github.com/agentic-community/mcp-gateway-registry/pull/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](https://github.com/agentic-community/mcp-gateway-registry/pull/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](https://github.com/agentic-community/mcp-gateway-registry/pull/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?](https://github.com/agentic-community/mcp-gateway-registry/blob/main/docs/faq/configuring-mongodb-atlas-backend.md) 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](https://github.com/agentic-community/mcp-gateway-registry/pull/931)).
- Handle null `description` in virtual server documents without raising 500 on GET ([#932](https://github.com/agentic-community/mcp-gateway-registry/pull/932), follow-up cleanup and tests in [#940](https://github.com/agentic-community/mcp-gateway-registry/pull/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](https://github.com/agentic-community/mcp-gateway-registry/pull/950), [#946](https://github.com/agentic-community/mcp-gateway-registry/issues/946)).

---

## Issues Fixed

| Issue | Title |
|-------|-------|
| [#946](https://github.com/agentic-community/mcp-gateway-registry/issues/946) | PATCH and DELETE on local-only (`create_in_idp=False`) groups still call the IdP and fail with 403 when admin scopes are absent |
| [#945](https://github.com/agentic-community/mcp-gateway-registry/issues/945) | IAM > M2M Accounts UI does not list records created via `/api/iam/m2m-clients` |
| [#934](https://github.com/agentic-community/mcp-gateway-registry/issues/934) | telemetry: include `embeddings_backend_kind` in startup and heartbeat events; move `embeddings_provider` to startup |
| [#922](https://github.com/agentic-community/mcp-gateway-registry/issues/922) | feat: end-to-end group-restricted agent access control (backend, nginx, CLI, docs) |
| [#917](https://github.com/agentic-community/mcp-gateway-registry/issues/917) | Feature Request: Dynamic Access Token Injection for Webhook Invocation |
| [#916](https://github.com/agentic-community/mcp-gateway-registry/issues/916) | Set the default value unchecked for 'Create in identity provider' under IAM > Group creation |
| [#883](https://github.com/agentic-community/mcp-gateway-registry/issues/883) | feat: add `allowed_groups` input to agent edit form for group-restricted visibility |
| [#500](https://github.com/agentic-community/mcp-gateway-registry/issues/500) | Registry: UI Logout function does not redirect correctly when using `routingMode = path` |

---

## Pull Requests Included

| PR | Title |
|----|-------|
| [#951](https://github.com/agentic-community/mcp-gateway-registry/pull/951) | `feat(terraform,docs): MONGODB_CONNECTION_STRING follow-up to #947` |
| [#950](https://github.com/agentic-community/mcp-gateway-registry/pull/950) | `fix(iam): skip IdP admin calls for local-only groups (#946)` |
| [#949](https://github.com/agentic-community/mcp-gateway-registry/pull/949) | `fix(iam): surface /api/iam/m2m-clients records in IAM > M2M Accounts UI (#945)` |
| [#948](https://github.com/agentic-community/mcp-gateway-registry/pull/948) | Allow overriding deployment registry and pull policies |
| [#947](https://github.com/agentic-community/mcp-gateway-registry/pull/947) | Feat/extended mongo connection string support |
| [#940](https://github.com/agentic-community/mcp-gateway-registry/pull/940) | `chore`: follow-up cleanup and tests for #932 null-description fix |
| [#935](https://github.com/agentic-community/mcp-gateway-registry/pull/935) | `feat(telemetry)`: add `embeddings_backend_kind` field; move `embeddings_provider` to startup (#934) |
| [#932](https://github.com/agentic-community/mcp-gateway-registry/pull/932) | `fix`: handle null description in virtual server documents |
| [#931](https://github.com/agentic-community/mcp-gateway-registry/pull/931) | Fix a number of issues related to URL paths and missing env vars |
| [#928](https://github.com/agentic-community/mcp-gateway-registry/pull/928) | `feat(usage-report)`: add embeddings provider column to Most Active Instances |
| [#926](https://github.com/agentic-community/mcp-gateway-registry/pull/926) | `fix(auth)`: include ROOT_PATH in OAuth2 redirect URIs |
| [#924](https://github.com/agentic-community/mcp-gateway-registry/pull/924) | `feat(gate)`: add OAuth2 Client Credentials auth for registration gate |
| [#923](https://github.com/agentic-community/mcp-gateway-registry/pull/923) | `feat(agents)`: end-to-end group-restricted agent visibility |
| [#921](https://github.com/agentic-community/mcp-gateway-registry/pull/921) | `fix(iam)`: default 'Create in identity provider' checkbox to unchecked |

---

## Contributors

Thank you to all contributors for this release:

- **Amit Arora** ([@aarora79](https://github.com/aarora79))
- **omrishiv** ([@omrishiv](https://github.com/omrishiv))
- **Alejandro Nuñez Cabello** ([@alejandronunezcabello](https://github.com/alejandronunezcabello))

---

## Support

- [GitHub Issues](https://github.com/agentic-community/mcp-gateway-registry/issues)
- [GitHub Discussions](https://github.com/agentic-community/mcp-gateway-registry/discussions)
- [Documentation](https://github.com/agentic-community/mcp-gateway-registry/tree/main/docs)

---

**Full Changelog:** [v1.0.21...v1.0.22](https://github.com/agentic-community/mcp-gateway-registry/compare/v1.0.21...v1.0.22)
