# Release 1.23.0 - Cloud Detection, IAM Hardening, and Splunk-Ready Logging

**May 2026**

---

> ## Versioning Change: Strict Semantic Versioning (No `v` Prefix)
>
> Starting with this release, **all tags, DockerHub images, Helm chart versions, and release notes filenames use strict semantic versioning without the `v` prefix**. The previous convention used `v`-prefixed tags (e.g. `v1.0.22`). Going forward:
>
> - Tags: `1.23.0` (not `v1.23.0`)
> - Release notes: `release-notes/1.23.0.md` (not `release-notes/v1.23.0.md`)
> - DockerHub: `mcpgateway/registry:1.23.0`
> - Helm chart `appVersion` and `version` fields: `1.23.0`
>
> Prior tags (`v1.0.22-p1`, `v1.0.22`, `v1.0.21`, ...) remain as-is for history. No action needed to upgrade from a `v`-prefixed release; simply pull this tag and update your image references.

---

## Upgrading from v1.0.22-p1

This section covers everything you need to know to upgrade from v1.0.22-p1 to 1.23.0.

### Breaking Changes

There are no breaking code changes in this release. The versioning convention change above is a naming convention only and does not affect API behavior, deployment topology, or data compatibility. Operators using Helm or Terraform deployments should update their image tag references to drop the `v` prefix (e.g. `1.23.0`).

### New Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `APP_LOG_DIR` | `/var/log/containers/ai-registry` | Directory for service log files. Must be an absolute path with `uid=1000` ownership. Created automatically by `build_and_run.sh` via `scripts/prepare-log-dirs.sh`. Issue [#987](https://github.com/agentic-community/mcp-gateway-registry/issues/987). |
| `APP_LOG_FILE_FORMAT` | `json` | On-disk log format: `json` (JSON Lines per `docs/logging-standard.md`, Splunk-friendly) or `text` (legacy comma-separated). Console output is always human-readable regardless of this setting. Issue [#987](https://github.com/agentic-community/mcp-gateway-registry/issues/987). |
| `MCP_TELEMETRY_IMDS_PROBE_DISABLED` | _(not set, probes enabled)_ | When set to `1`, disables live IMDS probes in cloud detection. Env-var, DMI, ECS-metadata, and Kubernetes heuristics still run. Issue [#986](https://github.com/agentic-community/mcp-gateway-registry/issues/986). |

### Upgrade Instructions

#### Docker Compose

```bash
cd mcp-gateway-registry
git pull origin main
git checkout 1.23.0

# Review new env vars in .env.example and update your .env if needed.
# If you want to opt out of telemetry IMDS probing:
#   echo 'MCP_TELEMETRY_IMDS_PROBE_DISABLED=1' >> .env
#
# Rebuild and restart:
./build_and_run.sh
```

#### Kubernetes / Helm (EKS)

```bash
cd mcp-gateway-registry
git pull origin main
git checkout 1.23.0

# Update values.yaml if needed (new optional key: registry.app.mcpTelemetryImdsProbeDisabled).
cd charts/mcp-gateway-registry-stack
helm upgrade mcp-gateway . -f your-values.yaml
```

#### Terraform / ECS

```bash
cd mcp-gateway-registry
git pull origin main
git checkout 1.23.0

# Update your .tfvars with any new variables (mcp_telemetry_imds_probe_disabled is optional).
cd terraform/aws-ecs
terraform plan
terraform apply
```

#### DockerHub Images

Pre-built images are available (note the strict semver tag format):

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

---

## Major Features

### Cloud Provider Detection: ECS Metadata, Kubernetes Heuristics, IMDS Fallback

Registry telemetry now correctly classifies AWS EKS/ECS, GKE, and AKS deployments even when cloud-specific env vars are not auto-injected and DMI files are unreadable from inside containers. A five-tier cascade (env vars -> DMI files -> `ECS_CONTAINER_METADATA_URI` -> Kubernetes `NODE_NAME` patterns like `*.compute.internal`/`gke-*`/`aks-*` -> live IMDS probe at 169.254.169.254 with a 300 ms per-provider timeout) shrinks the `cloud=unknown` bucket in telemetry rollups.

Payloads carry a new `cloud_detection_method` field (bumped to `schema_version=3`) so rollups can diagnose why any instance still classifies as `unknown`. The IMDS tier is fail-silent, uses `trust_env=False` to bypass corporate proxies, discards IMDSv2 tokens immediately, and opts out via `MCP_TELEMETRY_IMDS_PROBE_DISABLED=1`. A new `mcp_registry_cloud_detection_total` Prometheus counter and a CloudWatch alarm (fires when `method=unknown` exceeds 10% of startup events over a 24 h window) surface regressions. Operators can verify classification for their instance via the System Health hover panel or `GET /api/system/telemetry-detection`.

See the [Cloud Provider Detection](https://github.com/agentic-community/mcp-gateway-registry/blob/main/docs/TELEMETRY.md#cloud-provider-detection) docs for the full cascade, the EKS IMDS hop-limit gotcha (the #1 operator trap), and zero-cost opt-in env vars.

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

### Centralized Container Logging in JSONL Format for Splunk Ingestion

All service logs now land under `/var/log/containers/ai-registry/` (each service writes its own `.log` file: `registry.log`, `auth-server.log`, `ai-registry-tools.log`, plus nginx access/error logs). Default on-disk format is JSON Lines matching `docs/logging-standard.md`, which is Splunk-friendly and enables downstream ingestion without custom parsers. Console/stdout output remains human-readable. The host directory is prepared automatically by `build_and_run.sh` via `scripts/prepare-log-dirs.sh`.

Two new env vars control behavior: `APP_LOG_DIR` (absolute path) and `APP_LOG_FILE_FORMAT` (`json` or `text`).

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

### Helm: `extraEnv` and `extraEnvFrom` in Subcharts and Stack

Helm operators can now inject arbitrary environment variables into the registry, auth-server, mcpgw, and stack-level deployments via `extraEnv` / `extraEnvFrom` values, without forking the chart. A reserved-name allowlist in `_helpers.tpl` prevents operators from overriding chart-managed variables and breaking the deployment. Positional test assertions guard the ordering contract between chart-managed and operator-supplied entries.

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

### Unified Cross-Surface Configuration Parameter Reference

A single index at [`docs/unified-parameter-reference.md`](https://github.com/agentic-community/mcp-gateway-registry/blob/main/docs/unified-parameter-reference.md) maps every configuration parameter across the three deployment surfaces (Docker `.env`, Terraform `.tfvars`, Helm `values.yaml`). Operators and reviewers can find the right variable name for their deployment without grepping across three surfaces. Parameters are grouped logically, secrets are flagged, and the new-feature-design and pr-review skills require this index to be updated on every parameter change so the surfaces stay in sync.

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

---

## What's New

### Authentication / Security

- **Signed internal JWT on `/internal/tokens`** — Service-to-service internal JWT is now required, tightened leeway from 30 s to 5 s, header-helper unit tests added ([#974](https://github.com/agentic-community/mcp-gateway-registry/pull/974), [#999](https://github.com/agentic-community/mcp-gateway-registry/pull/999)).
- **IAM orphan-delete hardening** — M2M user list dedup and orphan-delete path get case-insensitive MongoDB filters, audit events on orphan cleanup, Prometheus counter, and full unit-test coverage ([#942](https://github.com/agentic-community/mcp-gateway-registry/pull/942), [#1005](https://github.com/agentic-community/mcp-gateway-registry/pull/1005)).

### Helm / Deployment

- **Respect `mongodb.host`/`replicas`/`version` values** — MongoDBCommunity template stops hard-coding these ([#968](https://github.com/agentic-community/mcp-gateway-registry/pull/968)).
- **Fix image tag override from Helm variables** — Image tags set via `global.image.tag` are no longer overridden by hard-coded defaults ([#965](https://github.com/agentic-community/mcp-gateway-registry/pull/965)).
- **Per-platform compute snapshot in usage-report** — Usage-report skill emits a markdown table with compute platform distribution ([#1004](https://github.com/agentic-community/mcp-gateway-registry/pull/1004)).
- **Registry reverse-proxy fix** — Removed stray double-slash in one frontend request path and tightened route-aware logic ([#1001](https://github.com/agentic-community/mcp-gateway-registry/pull/1001)).

### Frontend

- System Health hover panel shows detected cloud + method (`Cloud: aws (via imds)`).
- Version indicator uses the `BUILD_VERSION` build-arg so DockerHub images carry the correct display string ([#965](https://github.com/agentic-community/mcp-gateway-registry/pull/965)).

### Documentation

- `docs/TELEMETRY.md` adds the Cloud Provider Detection section with cascade table, zero-cost opt-in env vars, EKS IMDS hop-limit gotcha, and security note.
- README Telemetry section describes `cloud_detection_method` and the IMDS opt-out.
- `docs/unified-parameter-reference.md` is now the canonical cross-surface parameter index.

---

## Bug Fixes

- Deduplicate IAM user list and handle orphaned M2M deletes ([#942](https://github.com/agentic-community/mcp-gateway-registry/pull/942)).
- Harden M2M orphan delete with case-insensitive regex filter, audit event, Prometheus counter, enriched warning log ([#1005](https://github.com/agentic-community/mcp-gateway-registry/pull/1005)).
- Fix `ServerCard.tsx` double-slash 404 in registry reverse-proxy path ([#1001](https://github.com/agentic-community/mcp-gateway-registry/pull/1001)).
- Respect operator-provided `mongodb.*` Helm values ([#968](https://github.com/agentic-community/mcp-gateway-registry/pull/968)).
- Image tag override from Helm variables now works as documented ([#965](https://github.com/agentic-community/mcp-gateway-registry/pull/965)).

---

## Issues Fixed

| Issue | Title | Shipped in |
|-------|-------|------------|
| [#1002](https://github.com/agentic-community/mcp-gateway-registry/issues/1002) | Add unified cross-surface configuration parameter reference | [#1003](https://github.com/agentic-community/mcp-gateway-registry/pull/1003) |
| [#998](https://github.com/agentic-community/mcp-gateway-registry/issues/998) | chore(auth): tighten internal JWT leeway + add header-helper unit tests (post-merge from #974) | [#999](https://github.com/agentic-community/mcp-gateway-registry/pull/999) |
| [#987](https://github.com/agentic-community/mcp-gateway-registry/issues/987) | feat(logging): migrate container logs to /var/log/containers/ai-registry/ with JSONL format for Splunk ingestion | [#996](https://github.com/agentic-community/mcp-gateway-registry/pull/996) |
| [#986](https://github.com/agentic-community/mcp-gateway-registry/issues/986) | Enhance cloud provider detection in registry telemetry to reduce the "unknown" bucket | [#1006](https://github.com/agentic-community/mcp-gateway-registry/pull/1006) |
| [#985](https://github.com/agentic-community/mcp-gateway-registry/issues/985) | feat(helm): support extraEnv and extraEnvFrom in subcharts and stack | [#977](https://github.com/agentic-community/mcp-gateway-registry/pull/977) |

---

## Pull Requests Included

| PR | Title |
|----|-------|
| [#1006](https://github.com/agentic-community/mcp-gateway-registry/pull/1006) | feat(telemetry): reduce cloud=unknown bucket via ECS meta, k8s, IMDS probes (#986) |
| [#1005](https://github.com/agentic-community/mcp-gateway-registry/pull/1005) | fix(iam): harden M2M orphan delete and add test coverage |
| [#1004](https://github.com/agentic-community/mcp-gateway-registry/pull/1004) | feat(usage-report): emit per-platform compute snapshot markdown table |
| [#1003](https://github.com/agentic-community/mcp-gateway-registry/pull/1003) | docs: unified cross-surface configuration parameter reference (#1002) |
| [#1001](https://github.com/agentic-community/mcp-gateway-registry/pull/1001) | Fix/use registry reverse proxy |
| [#999](https://github.com/agentic-community/mcp-gateway-registry/pull/999) | chore(auth): tighten internal JWT leeway + add header-helper unit tests (#998) |
| [#996](https://github.com/agentic-community/mcp-gateway-registry/pull/996) | feat(logging): migrate container logs to /var/log/containers/ai-registry/ with JSONL format (#987) |
| [#983](https://github.com/agentic-community/mcp-gateway-registry/pull/983) | chore(deps): bump langchain-core from 1.2.28 to 1.3.3 |
| [#982](https://github.com/agentic-community/mcp-gateway-registry/pull/982) | chore(deps): bump @babel/plugin-transform-modules-systemjs in /frontend |
| [#981](https://github.com/agentic-community/mcp-gateway-registry/pull/981) | chore(deps): bump fast-uri from 3.1.0 to 3.1.2 in /frontend |
| [#980](https://github.com/agentic-community/mcp-gateway-registry/pull/980) | chore(deps): bump gitpython from 3.1.47 to 3.1.50 |
| [#979](https://github.com/agentic-community/mcp-gateway-registry/pull/979) | chore(deps): bump fast-xml-builder from 1.1.5 to 1.2.0 in /cli |
| [#978](https://github.com/agentic-community/mcp-gateway-registry/pull/978) | chore(deps): bump python-multipart from 0.0.26 to 0.0.27 |
| [#977](https://github.com/agentic-community/mcp-gateway-registry/pull/977) | feat(helm): support extraEnv and extraEnvFrom in subcharts and stack |
| [#976](https://github.com/agentic-community/mcp-gateway-registry/pull/976) | chore(deps): bump python-multipart from 0.0.26 to 0.0.27 in /agents/a2a |
| [#975](https://github.com/agentic-community/mcp-gateway-registry/pull/975) | chore(deps): bump python-multipart in /servers/currenttime |
| [#974](https://github.com/agentic-community/mcp-gateway-registry/pull/974) | fix(auth): require signed internal JWT on /internal/tokens |
| [#973](https://github.com/agentic-community/mcp-gateway-registry/pull/973) | chore(deps): bump python-multipart in /metrics-service |
| [#970](https://github.com/agentic-community/mcp-gateway-registry/pull/970) | chore(deps): bump python-multipart in /servers/mcpgw |
| [#969](https://github.com/agentic-community/mcp-gateway-registry/pull/969) | chore(deps): bump axios from 1.15.0 to 1.15.2 in /frontend |
| [#968](https://github.com/agentic-community/mcp-gateway-registry/pull/968) | fix(helm): respect mongodb.host, mongodb.replicas, mongodb.version values |
| [#965](https://github.com/agentic-community/mcp-gateway-registry/pull/965) | fix overriding the image tag from helm variables |
| [#964](https://github.com/agentic-community/mcp-gateway-registry/pull/964) | chore: update Helm chart image tags to 1.0.22-p1 |
| [#942](https://github.com/agentic-community/mcp-gateway-registry/pull/942) | fix: deduplicate IAM user list and handle orphaned M2M deletes |

---

## Security Dependency Updates

| Package | Previous | Updated | Scope |
|---------|----------|---------|-------|
| `axios` | 1.15.0 | 1.15.2 | `/frontend` |
| `@babel/plugin-transform-modules-systemjs` | 7.27.1 | 7.29.4 | `/frontend` |
| `fast-uri` | 3.1.0 | 3.1.2 | `/frontend` |
| `fast-xml-builder` | 1.1.5 | 1.2.0 | `/cli` |
| `gitpython` | 3.1.47 | 3.1.50 | root |
| `langchain-core` | 1.2.28 | 1.3.3 | root |
| `python-multipart` | 0.0.26 | 0.0.27 | root, `/agents/a2a`, `/metrics-service`, `/servers/currenttime`, `/servers/mcpgw` |

---

## Contributors

Thank you to all contributors for this release:

- **Amit Arora** ([@aarora79](https://github.com/aarora79))
- **omrishiv** ([@omrishiv](https://github.com/omrishiv))
- **Max Peshkov** ([@maxpeshkov](https://github.com/maxpeshkov))
- **Alejandro Nuñez Cabello** ([@alefnc](https://github.com/alefnc))
- **dependabot[bot]**
- **github-actions[bot]**

---

## 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.22-p1...1.23.0](https://github.com/agentic-community/mcp-gateway-registry/compare/v1.0.22-p1...1.23.0)
