# Release v1.0.20 - Registration Gate, Multi-Key API Auth, Webhooks, M2M Direct Registration, and Metadata Search

**April 2026**

---

## Upgrading from v1.0.19

This section covers everything you need to know to upgrade from v1.0.19 to v1.0.20.

### Breaking Changes

There are no breaking changes in this release. All new features are disabled by default or additive.

### New Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `REGISTRY_API_KEYS` | `""` | JSON map of static API keys with per-key group assignments. Each key gets only the scopes its groups resolve to. |
| `REGISTRATION_WEBHOOK_URL` | `""` | Webhook URL for registration/deletion notifications. Disabled when empty. |
| `REGISTRATION_WEBHOOK_AUTH_HEADER` | `Authorization` | Header name for webhook auth. If `Authorization`, Bearer is auto-prepended. |
| `REGISTRATION_WEBHOOK_AUTH_TOKEN` | `""` | Webhook auth token. Leave empty for unauthenticated webhooks. |
| `REGISTRATION_WEBHOOK_TIMEOUT_SECONDS` | `10` | HTTP timeout per webhook request in seconds. |
| `REGISTRATION_GATE_ENABLED` | `false` | Enable registration gate admission control. |
| `REGISTRATION_GATE_URL` | `""` | Gate endpoint URL. Must be set when enabled. |
| `REGISTRATION_GATE_AUTH_TYPE` | `none` | Gate auth type: `none`, `api_key`, or `bearer`. |
| `REGISTRATION_GATE_AUTH_CREDENTIAL` | `""` | Credential for `api_key` or `bearer` gate auth. |
| `REGISTRATION_GATE_AUTH_HEADER_NAME` | `X-Api-Key` | Header name for `api_key` gate auth type. |
| `REGISTRATION_GATE_TIMEOUT_SECONDS` | `5` | HTTP timeout per gate attempt in seconds. |
| `REGISTRATION_GATE_MAX_RETRIES` | `2` | Retry attempts after first gate failure (exponential backoff). |
| `M2M_DIRECT_REGISTRATION_ENABLED` | `true` | Enable `/api/iam/m2m-clients` admin API for direct M2M client registration. |

### Upgrade Instructions

#### Docker Compose

```bash
cd mcp-gateway-registry
git pull origin main
git checkout v1.0.20

# 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.20

# Update values.yaml with any new variables, then upgrade:
helm upgrade mcp-gateway . -f your-values.yaml
```

#### Terraform / ECS

```bash
cd mcp-gateway-registry
git pull origin main
git checkout v1.0.20

# Update your .tfvars with any new variables
cd terraform/aws-ecs
terraform plan
terraform apply
```

#### DockerHub Images

Pre-built images are available:

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

---

## Major Features

### Registration Webhooks and Gate

Two external integration points for registration lifecycle events, documented in the [Webhooks and Gate Guide](../docs/registration-webhooks.md):

**Registration Gate (Admission Control)** - Call an external endpoint to approve or deny registration and update requests before they are persisted. Supports all asset types (servers, agents, skills) for both register and update operations. Fail-closed design: if the gate endpoint is unreachable after configurable retries with exponential backoff, the registration is blocked. Sensitive fields (credentials, tokens, passwords) are automatically stripped from the payload sent to the gate. Supports Bearer token, API key, or unauthenticated access. Gate returns 200 to allow, 403 to deny with a custom error message. Configured across Docker Compose, Terraform/ECS, and Helm/EKS. ([#809](https://github.com/agentic-community/mcp-gateway-registry/issues/809), [PR #881](https://github.com/agentic-community/mcp-gateway-registry/pull/881))

**Registration Webhooks** - Send HTTP POST notifications to an external URL when servers, agents, or skills are registered or deleted. Enables real-time integration with CMDBs, CI/CD pipelines, Slack, or any external system. Fire-and-forget delivery (failures are logged, never block the caller). Supports Bearer token and custom API key authentication with configurable headers and timeouts. Configured across Docker Compose, Terraform/ECS, and Helm/EKS. ([#742](https://github.com/agentic-community/mcp-gateway-registry/issues/742), [PR #878](https://github.com/agentic-community/mcp-gateway-registry/pull/878))

### Multi-Key Static API Tokens with Per-Key Groups

Replace the single `REGISTRY_API_TOKEN` with `REGISTRY_API_KEYS`, a JSON map of named API keys each scoped to specific groups. Each key resolves to only the permissions its groups grant, enabling least-privilege access for CI/CD pipelines, monitoring scripts, and service accounts. When a static token does not match any configured key, the request falls through to JWT validation instead of returning 401.

[PR #876](https://github.com/agentic-community/mcp-gateway-registry/pull/876), [PR #875](https://github.com/agentic-community/mcp-gateway-registry/pull/875)

### Direct M2M Client Registration API

A new `/api/iam/m2m-clients` admin API for registering machine-to-machine client IDs and their group mappings directly, without requiring an IdP Admin API token. Works with any IdP (Entra ID, Cognito, Keycloak, Okta) because it stores mappings locally in MongoDB. Enables self-service M2M onboarding without granting IdP admin access.

[PR #866](https://github.com/agentic-community/mcp-gateway-registry/pull/866)

### Metadata Keyword Search for Agents, Servers, and Skills

The REST API list endpoints (`GET /api/agents?query=`, `GET /api/servers?query=`, `GET /api/skills/search?q=`) now include custom metadata key-value pairs in their keyword search. Previously only name, description, tags, and skill names were searchable. The shared `flatten_metadata_to_text()` utility flattens nested metadata (lists, dicts) into a searchable string.

[PR #884](https://github.com/agentic-community/mcp-gateway-registry/pull/884)

---

## What's New

### Authentication
- Multi-key static API tokens with per-key group scoping (#876)
- Static token auth falls through to JWT validation when token does not match (#875)

### Registration Lifecycle
- Registration webhooks and gate (admission control) for all asset types (#878, #881)
- Direct M2M client registration API without IdP admin access (#866)

### Search
- Custom metadata included in keyword search for agents, servers, and skills (#884)
- OpenAPI spec updated to clarify list endpoints use lexical substring search (#884)

### Frontend
- Auto-extract repository URL from SKILL.md URL, show separate View Skill / View Repo links (#857)

### Infrastructure
- Python runtime upgraded from 3.12 to 3.14 (#850)
- Container base images patched to resolve openssl/zlib/musl CVEs (#861)
- Post-merge fixes for Python 3.14 compatibility (#852)
- Helm chart duplicate auth section fixed (#848)
- M2M_DIRECT_REGISTRATION_ENABLED added to all docker-compose files (#884)

### Documentation
- Group-restricted agent visibility FAQ added (#883)
- Hybrid search architecture doc updated with REST API lexical search clarification (#884)

---

## Bug Fixes

- Fix Helm chart duplicate auth section in values (#848)
- Fix post-merge issues from Python 3.14 upgrade (#852)
- Patch container base images to resolve openssl/zlib/musl CVEs (#861)

---

## Pull Requests Included

| PR | Title |
|----|-------|
| #884 | feat(search): include custom metadata in keyword search for agents, servers, and skills |
| #882 | chore(deps): bump fast-xml-parser and @aws-sdk/xml-builder in /cli |
| #881 | feat(gate): add registration gate admission control webhook (#809) |
| #878 | feat(webhook): registration webhook notifications for add and delete events (#742) |
| #877 | chore(skill): apply ruff formatting to usage-report skill |
| #876 | feat(auth): add multi-key static tokens with per-key groups (#779) |
| #875 | feat(auth): fall through to JWT validation when static token does not match (#871) |
| #872 | chore(skill): add testing plan step to new-feature-design skill (v1.5) |
| #870 | chore(deps): bump python-dotenv from 1.2.1 to 1.2.2 in /metrics-service |
| #869 | chore(deps): bump python-dotenv from 1.2.1 to 1.2.2 |
| #868 | chore(deps): bump python-dotenv from 1.2.1 to 1.2.2 in /agents/a2a |
| #866 | feat: add direct M2M client registration API (#851) |
| #861 | fix: patch container base images to resolve openssl/zlib/musl CVEs |
| #857 | feat: auto-extract repository URL from SKILL.md URL and add View Skill/View Repo links (#846) |
| #854 | chore: add internal instance tracking and fix metrics comparison in usage-report skill |
| #853 | chore: update usage-report skill and telemetry scripts |
| #852 | fix: post-merge fixes for Python 3.14 upgrade |
| #850 | update to Python 3.14 |
| #848 | fix Helm chart update duplicate auth |
| #843 | chore(deps): bump authlib from 1.6.9 to 1.6.11 in /servers/mcpgw |
| #842 | chore(deps): bump authlib from 1.6.9 to 1.6.11 in /servers/currenttime |

---

## Security Dependency Updates

| Package | Previous | Updated | Scope |
|---------|----------|---------|-------|
| authlib | 1.6.9 | 1.6.11 | servers/mcpgw, servers/currenttime |
| python-dotenv | 1.2.1 | 1.2.2 | root, agents/a2a, metrics-service |
| fast-xml-parser / @aws-sdk/xml-builder | - | latest | cli |
| Container base images | - | patched | openssl/zlib/musl CVEs |

---

## Contributors

Thank you to all contributors for this release:

- **Amit Arora** ([@amitarora](https://github.com/amitarora))
- **Omri Shiv** ([@omrishiv](https://github.com/omrishiv))

---

## 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.19...v1.0.20](https://github.com/agentic-community/mcp-gateway-registry/compare/v1.0.19...v1.0.20)
