Skip to content

1.25.0 - Agentic Registry Discovery (ARD), Lifecycle Webhooks, and Storage Simplification

Latest
Latest

Choose a tag to compare

View all tags
@aarora79 aarora79 released this 26 Jun 23:18
· 2 commits to main since this release
1.25.0
765f35c

Release 1.25.0 - Agentic Registry Discovery (ARD), Lifecycle Webhooks, and Storage Simplification

June 2026

Upgrading from 1.24.7

This section covers everything you need to know to upgrade from 1.24.7 to 1.25.0.

Breaking Changes

File storage backend, FAISS search, and scopes.yml removed (#1292, #1309)

If you are already using a MongoDB or DocumentDB storage backend, this breaking change does not apply to you and you can skip the rest of this section. It only affects deployments that used the legacy file-based backend.

The legacy file-based storage backend, the FAISS embeddings search path, and the scopes.yml configuration file have been removed. The registry now relies exclusively on the DocumentDB/MongoDB storage backend, and scopes/permissions are sourced from the database.

Remediation:

  • Ensure your deployment uses the mongodb-ce (self-managed) or DocumentDB storage backend. File storage is no longer available.
  • Remove any references to scopes.yml or load-scopes.py from your deployment scripts and task definitions. Group-to-scope mappings now live in the database (group_mappings).
  • The run-scopes-init-task.sh ECS task and related dangling calls have been removed (#1317). If your automation references it, delete those calls.

Authorization enforced on External API management endpoints (#1333)

The External API management endpoints now enforce authorization checks that previously were only applied on their legacy UI counterparts. Callers that relied on the unauthenticated/under-authorized behavior of these endpoints will now receive authorization errors. Ensure the calling identity has the appropriate permissions.

New Environment Variables

Variable Default Description
ARD_CATALOG_ENABLED true Set to false to disable the public ARD catalog endpoint (/.well-known/ai-catalog.json).
ARD_REGISTRY_ENABLED true Set to false to disable the ARD Registry adapter (POST /api/ard/search, GET /api/ard/agents) and the self ai-registry catalog entry.
ARD_PUBLISHER_DOMAIN (empty) FQDN used as the URN publisher (urn:air:<domain>:...). Empty derives it from the host of REGISTRY_URL (falls back to example.com).
ARD_CATALOG_DEFAULT_NAMESPACE (empty) Optional override for the URN namespace segment. Empty uses the entity type (server/agent/skill).
REGISTRATION_WEBHOOK_SIGNING_SECRET (empty) Shared secret for HMAC-SHA256 signing of outbound webhook payloads. When set, an X-Registry-Signature header (sha256=<hex>) is added over the exact transmitted body. Empty disables signing (current behavior).
REGISTRATION_ENFORCED_STATUS (empty) When set (e.g. draft), mandates the initial lifecycle status for all new asset registrations. A registration with no status is forced to this value; a registration with a different explicit status fails with 4xx. Empty preserves current behavior (default active).

Upgrade Instructions

Docker Compose

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

# Review new env vars in .env.example and update your .env if needed
# (ARD_* and REGISTRATION_WEBHOOK_SIGNING_SECRET / REGISTRATION_ENFORCED_STATUS)
# Then rebuild and restart:
./build_and_run.sh

Kubernetes / Helm (EKS)

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

# REQUIRED: subchart templates, values, helpers, and the mongodb-configure
# job changed in this release. Rebuild the packaged dependencies so the
# stack chart picks up the new subchart contents.
cd charts/mcp-gateway-registry-stack
helm dependency build
helm dependency update

# Update values.yaml if needed (new ard.*, registry.app.registrationWebhookSigningSecret,
# registry.app.registrationEnforcedStatus, and metrics.otelExporterOtlpEndpoint fields),
# then upgrade:
helm upgrade mcp-gateway . -f your-values.yaml

Terraform / ECS

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

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

DockerHub Images

Pre-built images are available:

docker pull mcpgateway/registry:1.25.0
docker pull mcpgateway/auth-server:1.25.0
docker pull mcpgateway/currenttime-server:1.25.0
docker pull mcpgateway/realserverfaketools-server:1.25.0
docker pull mcpgateway/mcpgw-server:1.25.0
docker pull mcpgateway/metrics-service:1.25.0

Major Features

Agentic Registry Discovery (ARD)

This release introduces a multi-part ARD implementation that lets the registry publish and consume agentic catalogs and federate with other registries:

  • ARD Catalog Publisher (#1299): publishes a conformant /.well-known/ai-catalog.json document so other registries and agents can discover the assets this registry exposes. Controlled by ARD_CATALOG_ENABLED, ARD_PUBLISHER_DOMAIN, and ARD_CATALOG_DEFAULT_NAMESPACE.
  • ARD Registry adapter (#1318): adds POST /api/ard/search and GET /api/ard/agents endpoints so the registry can serve as an ARD-compliant registry. Controlled by ARD_REGISTRY_ENABLED.
  • Catalog ingestion, federation modes, and domain-anchored trust (#1336): ingests external ai-catalog.json documents, adds federation modes (auto / referrals / none), and anchors trust to the publisher domain. The Helm mongodb-configure job now seeds a federation-service access record for federated read access to agents.

PR #1299, PR #1318, PR #1336

Lifecycle Workflow Webhooks

The registration webhook now drives the server lifecycle (draft -> beta -> active -> deprecated) from an external orchestrator:

  • Emits a scan_complete event so an external workflow can react to scan results.
  • Optional HMAC-SHA256 signing of outbound payloads via REGISTRATION_WEBHOOK_SIGNING_SECRET (adds an X-Registry-Signature: sha256=<hex> header over the exact transmitted body).
  • Optional enforced initial status via REGISTRATION_ENFORCED_STATUS (for example, force every new registration to draft).
  • Adds a status permission and a status filter.

PR #1331

Token-Mint Audit Event and Metric

Adds an audit event and an OpenTelemetry metric emitted at the token signing point, giving operators visibility into when and for whom internal tokens are minted. Includes follow-up test and coverage hardening.

PR #1304, PR #1310

What's New

Storage and Search

  • Removed the file storage backend, FAISS embeddings search, and the scopes.yml config file; the registry now standardizes on the database backend (#1292)
  • Follow-up: fixed the scopes_init build break, removed dangling calls, swept docs, and renamed metrics (#1309)

Infrastructure / ECS

  • Labeled registry/mcpgw metrics so they no longer land in AMP as job=unknown_service, and moved the ECS Grafana admin password to Secrets Manager (#1328)
  • Fixed Grafana dashboard label case, CLI toggle/rate payloads (HTTP 422), and cleaned up /validate logging (#1327)
  • Added the missing OTEL_EXPORTER_OTLP_ENDPOINT env var in the charts, kept distinct from the legacy metrics-service OTEL_OTLP_ENDPOINT (#1301)
  • Removed the dangling call to the deleted run-scopes-init-task.sh (#1317)

Frontend Improvements

  • Refactored frontend onto shared card primitives (#1275)
  • Deduped ServerCard and CustomEntityCard onto the shared primitives without changing the look (#1319)

Telemetry

  • UI cloud display now honors the MCP_CLOUD_PROVIDER override (fixes local Mac being misclassified as AWS) (#1307)

Connectivity

  • connect-config now omits the server auth header under OAuth login for all IDEs, since the gateway injects the egress credential (#1300)

Build and Dependencies

  • A2A Docker uv sync now honors the lockfile exclude-newer setting (#1314)
  • Updated the dependency-update workflow to use a GitHub token for push, run npm and uv in parallel, and skip failed modules; refreshed uv/npm locks (#1302)
  • Bumped the uv dependency group across 8 directories (#1290)
  • Bumped Python from 3.14.5-slim to 3.14.6-slim in the docker-images group (#1297)
  • Bumped the GitHub Actions group with 2 updates (#1298)

Cleanup

  • Removed the unused fininfo and example-server demo servers and a legacy observability doc (#1311)

Tooling

  • Updated the usage-report skill and template, and added a lifetime-by-compute chart script (#1332)
  • Extended API management (#1335)

Bug Fixes

  • Enforce authorization on External API management endpoints (#1333)
  • Grafana dashboard label case, CLI toggle/rate payloads, and /validate logging cleanup (#1327)
  • Registry/mcpgw metric labels and Grafana password handling on ECS (#1328)
  • UI cloud display honors MCP_CLOUD_PROVIDER override (#1307)
  • Honor lockfile exclude-newer in Docker uv sync (#1314)
  • Remove dangling call to deleted run-scopes-init-task.sh (#1317)
  • Omit server auth header under OAuth login for all IDEs (#1300)

Closed Issues

Issue Title Closed By
#1330 Lifecycle workflow webhooks: drive the server lifecycle from an external orchestrator PR #1331
#1326 ECS: registry/mcpgw metrics land in AMP as job=unknown_service PR #1328
#1325 Store ECS Grafana admin password in Secrets Manager PR #1328
#1323 registry_management.py: toggle and server-rate fail with HTTP 422 PR #1327
#1322 Grafana analytics dashboard panels show 'No data' (success label case mismatch) PR #1327
#1308 Follow-up to #1304: token-mint audit tests, coverage gap, and requires-python decision PR #1310
#1306 UI cloud-detection display ignores MCP_CLOUD_PROVIDER override PR #1307
#1296 feat(ard): ai-catalog.json ingestion + federation=auto/referrals/none + domain-anchored trust PR #1336
#1294 feat(ard): publish /.well-known/ai-catalog.json (ARD Catalog Publisher conformance) PR #1299
#1285 Remove file storage backend, FAISS embeddings search, and the scopes.yml config file PR #1292
#1215 Add an audit event and OTEL metric for token minting at the signing point PR #1304

Pull Requests Included

PR Title
#1336 feat(ard): ai-catalog.json ingestion + federation modes + domain-anchored trust
#1335 Extend API management PR
#1333 fix(security): enforce authorization on External API management endpoints
#1332 chore(usage-report): update skill, template, and add lifetime-by-compute chart script
#1331 feat: lifecycle workflow webhooks — scan_complete event, HMAC signing, enforced status, status permission/filter
#1328 fix(ecs): registry/mcpgw metric labels + Grafana password to Secrets Manager
#1327 fix: Grafana dashboard label case, CLI toggle/rate payloads, and /validate logging cleanup
#1319 Dedupe ServerCard + CustomEntityCard onto shared primitives without changing the look
#1318 feat(ard): ARD Registry adapter — POST /search + GET /agents
#1317 fix(ecs): remove dangling call to deleted run-scopes-init-task.sh
#1314 fix(a2a): honor lockfile exclude-newer in Docker uv sync
#1311 chore: remove unused fininfo and example-server demo servers, legacy observability doc
#1310 fix(audit): token-mint follow-up — tests, coverage gap, cleanups
#1309 Follow-up to #1285: fix scopes_init build break, dangling calls, docs sweep, metrics rename
#1307 fix(telemetry): UI cloud display honors MCP_CLOUD_PROVIDER override
#1304 feat(audit): token-mint audit event + metric
#1302 fix dependency workflow
#1301 Adds missing OTEL_EXPORTER_OTLP_ENDPOINT envvar in charts
#1300 fix(connect-config): omit server auth header under OAuth login for all IDEs
#1299 feat(ard): publish /.well-known/ai-catalog.json (ARD Catalog Publisher conformance)
#1298 build(deps): bump the actions group in /.github/workflows with 2 updates
#1297 build(deps): bump python from 3.14.5-slim to 3.14.6-slim in the docker-images group
#1292 Remove file storage backend, FAISS search, and scopes.yml
#1290 build(deps): bump the uv group across 8 directories with 4 updates
#1275 Refactor/frontend card primitives

Contributors

Thank you to all contributors for this release:

Support

Full Changelog: 1.24.7...1.25.0

What's Changed

  • build(deps): bump the actions group in /.github/workflows with 2 updates by @dependabot[bot] in #1298
  • build(deps): bump python from 3.14.5-slim to 3.14.6-slim in /docker in the docker-images group by @dependabot[bot] in #1297
  • build(deps): bump the uv group across 8 directories with 4 updates by @dependabot[bot] in #1290
  • feat(ard): publish /.well-known/ai-catalog.json (ARD Catalog Publisher conformance) by @aarora79 in #1299
  • fix dependency workflow by @omrishiv in #1302
  • Adds missing OTEL_EXPORTER_OTLP_ENDPOINT envvar in charts by @omrishiv in #1301
  • fix(connect-config): omit server auth header under OAuth login for all IDEs (gateway injects egress) by @go-faustino in #1300
  • fix(telemetry): UI cloud display honors MCP_CLOUD_PROVIDER override by @aarora79 in #1307
  • Remove file storage backend, FAISS search, and scopes.yml (#1285) by @ajmsra in #1292
  • feat(audit): token-mint audit event + metric by @shekharprateek in #1304
  • fix(audit): token-mint follow-up — tests, coverage gap, cleanups by @aarora79 in #1310
  • chore: remove unused fininfo and example-server demo servers, legacy observability doc by @aarora79 in #1311
  • fix(a2a): honor lockfile exclude-newer in Docker uv sync by @aarora79 in #1314
  • Follow-up to #1285: fix scopes_init build break, dangling calls, docs sweep, metrics rename by @aarora79 in #1309
  • fix(ecs): remove dangling call to deleted run-scopes-init-task.sh by @aarora79 in #1317
  • Refactor/frontend card primitives by @omrishiv in #1275
  • Dedupe ServerCard + CustomEntityCard onto shared primitives without changing the look by @aarora79 in #1319
  • feat(ard): ARD Registry adapter — POST /search + GET /agents (#1295) by @aarora79 in #1318
  • fix: Grafana dashboard label case, CLI toggle/rate payloads, and /validate logging cleanup by @aarora79 in #1327
  • fix(ecs): registry/mcpgw metric labels (#1326) + Grafana password to Secrets Manager (#1325) by @aarora79 in #1328
  • chore(usage-report): update skill, template, and add lifetime-by-compute chart script by @aarora79 in #1332
  • fix(security): enforce authorization on External API management endpoints by @aarora79 in #1333
  • feat: lifecycle workflow webhooks — scan_complete event, HMAC signing, enforced status, status permission/filter (#1330) by @aarora79 in #1331
  • Extend API management PR by @omrishiv in #1335
  • feat(ard): ai-catalog.json ingestion + federation modes + domain-anchored trust (#1296) by @aarora79 in #1336

Full Changelog: 1.24.7...1.25.0

Contributors

omrishiv, aarora79, and 4 other contributors
Assets 2
Loading