# Release 1.24.0 - Local MCP Servers, Custom Headers, and Branding

**May 2026**

---

## Upgrading from 1.23.0

This section covers everything you need to know to upgrade from 1.23.0 to 1.24.0.

### Breaking Changes

There are no breaking changes in this release. All new functionality is additive and backwards compatible:

- The new `deployment` field on servers defaults to `remote`, preserving existing remote-server behavior.
- The new `UI_TITLE` env var defaults to the deployment-mode-aware string ("AI Gateway & Registry" for `with-gateway`, "AI Registry" for `registry-only`), so existing deployments see no change unless they explicitly set the variable.
- `APP_LOG_CONSOLE_FORMAT` flips its default from `text` to `json` for log-agent scraping. Operators who prefer human-readable stdout can set `APP_LOG_CONSOLE_FORMAT=text` to opt back in.
- Custom HTTP headers per server are entirely opt-in.

### New Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `UI_TITLE` | empty (deployment-mode-aware) | Override the UI header title shown in the top-left, login, logout, and browser tab. Empty defers to `AI Gateway & Registry` (with-gateway) or `AI Registry` (registry-only). |
| `APP_LOG_CONSOLE_FORMAT` | `json` | STDOUT/console format. `json` emits JSON Lines (default, ideal for log agents). `text` emits human-readable comma-separated. |
| `MCP_TOOLS_LIST_FILTER_ENABLED` | `true` | Enable per-user tool allowlist filtering on REST endpoints and the MCP `tools/list` JSON-RPC response (issue #1026). |
| `TOOL_FILTER_AUDIT_LOG_LEVEL` | `INFO` | Log level for tool-filter audit events. |
| `MCP_PROXY_MAX_BODY_BYTES` | `2097152` (2 MB) | Upper bound on request bodies the registry proxies upstream. |

### Upgrade Instructions

#### Docker Compose

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

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

#### Kubernetes / Helm (EKS)

**REQUIRED:** Subchart templates, values, and helpers changed in this release. The packaged `.tgz` subcharts inside `charts/mcp-gateway-registry-stack/charts/` must be rebuilt - a plain `git pull` is not sufficient, you will silently use the old subchart packages.

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

# REQUIRED: Rebuild subchart packages so the stack chart picks up the
# updated registry, mcpgw, and auth-server templates and values.
cd charts/mcp-gateway-registry-stack
helm dependency build
helm dependency update

# Update values.yaml if needed, then upgrade:
helm upgrade mcp-gateway . -f your-values.yaml
```

#### Terraform / ECS

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

# 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:1.24.0
docker pull mcpgateway/auth-server:1.24.0
docker pull mcpgateway/currenttime-server:1.24.0
docker pull mcpgateway/realserverfaketools-server:1.24.0
docker pull mcpgateway/mcpgw-server:1.24.0
docker pull mcpgateway/fininfo-server:1.24.0
docker pull mcpgateway/metrics-service:1.24.0
```

---

## Major Features

### Local (stdio) MCP Server Support

Register local MCP servers that run on developer machines via stdio (npx, uvx, docker, command) alongside remote HTTP-proxied servers. The registry stores a launch recipe and surfaces it as IDE-ready config (Claude Code, Cursor, Roo Code, Kiro, Goose) through the Connect modal. No health checks, no nginx proxy, no security scanning for local servers (they have no HTTP endpoint to probe).

Highlights:
- Heuristic secret-leak detection at registration time (rejects literal tokens in env values)
- Automatic `unpinned-version` tagging for packages without a version pin
- Admin-only registration; `security-pending-local` tag workflow for manual review
- Federation peers can opt in to syncing local recipes via a `sync_local_servers` flag (default off)

[PR #1038](https://github.com/agentic-community/mcp-gateway-registry/pull/1038), [FAQ](https://github.com/agentic-community/mcp-gateway-registry/blob/main/docs/faq/local-mcp-servers.md)

### Custom HTTP Headers per MCP Server

Attach up to 10 custom HTTP headers to any registered MCP server. Header values are Fernet-encrypted at rest (never exposed in listing APIs) and decrypted on demand for the Connect modal and proxied requests. Headers are injected into upstream health checks and tool-fetch requests before auth_scheme headers (defense-in-depth merge order).

Highlights:
- RFC 7230 token validation, reserved gateway headers blocklisted (Authorization, Host, etc.), CRLF injection prevention, max 10 per server
- Edit supports partial-update semantics (empty value preserves existing ciphertext)
- New `GET /api/servers/{path}/connect-config` endpoint for the Connect button
- CLI: `server-connect-config` subcommand and `--custom-header NAME=VALUE` on `server-update-credential`

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

### Configurable UI Title with Deployment-Mode-Aware Defaults

A new `UI_TITLE` parameter lets operators brand the deployment with their organization's product name (e.g., "Acme AI Portal") without forking the frontend. When unset, the title defaults based on `DEPLOYMENT_MODE` (`AI Gateway & Registry` for `with-gateway`, `AI Registry` for `registry-only`), fixing the misleading "Gateway" label in registry-only deployments.

The title is rendered in the top-left header, Login page, Logout footer, uptime tooltip, and browser tab. Plumbed through Docker, Terraform, and Helm; documented in the unified parameter reference.

[PR #1043](https://github.com/agentic-community/mcp-gateway-registry/pull/1043), [FAQ](https://github.com/agentic-community/mcp-gateway-registry/blob/main/docs/faq/local-mcp-servers.md)

### JSON Console Logging by Default

A new `APP_LOG_CONSOLE_FORMAT` env var switches stdout output between `json` (structured JSON Lines, the new default) and `text` (human-readable). Defaulting to JSON makes container logs immediately consumable by log agents and sidecars (Datadog, CloudWatch, Splunk) without parsing. The same parameter controls all three services (registry, auth-server, mcpgw).

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

### Tool-Level Access Control in List/Response APIs

The registry now enforces tool-level access control on `GET /api/servers`, `GET /api/server_details`, and the MCP `tools/list` JSON-RPC response. Users only see the tools they have execute scopes for. Includes an audit log of filtered-out tools at a configurable log level.

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

### Resource-Bound JWT Tokens

JWT tokens minted via the token-vending endpoint can now be bound to a specific resource (server path, agent path, or virtual server) so leaked tokens cannot be reused against other resources. Audit logs include the bound resource for forensic visibility.

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

### Multi-Replica `airegistry-tools` Support

The built-in `airegistry-tools` MCP server now runs correctly behind a load balancer with multiple replicas. Sticky-session handling and shared state are correctly configured.

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

### IPv6 Dual-Stack Server Bind Support

Server bind addresses now support IPv6 dual-stack (`::`), enabling deployment on IPv6-only Kubernetes clusters. `BIND_HOST` defaults to `0.0.0.0` for backwards compatibility; operators can opt in to `::` explicitly.

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

---

## What's New

### Frontend Improvements
- Add Skills (JSON array) field to Agent Quick Form registration ([#1046](https://github.com/agentic-community/mcp-gateway-registry/pull/1046)) - closes #1045
- Filter list of IDEs for MCP servers ([#912](https://github.com/agentic-community/mcp-gateway-registry/pull/912))
- Add Goose as a connection option from the UI ([#1018](https://github.com/agentic-community/mcp-gateway-registry/pull/1018))

### Helm and Deployment
- Make ALB ingress scheme configurable with 3-tier override ([#967](https://github.com/agentic-community/mcp-gateway-registry/pull/967))
- Extra-env surface parity for Docker Compose and Terraform ([#1019](https://github.com/agentic-community/mcp-gateway-registry/pull/1019)) - closes #1000
- `uv.lock` usage for Docker and mcpgw embeddings cleanup ([#1024](https://github.com/agentic-community/mcp-gateway-registry/pull/1024)) - closes #1022

### Skills and Documentation
- Add active-instances chart and LTV-spend generators to usage-report skill ([#1025](https://github.com/agentic-community/mcp-gateway-registry/pull/1025))
- Add debug skill for first-principles root-cause analysis (commit 7207c98d)
- Local MCP servers FAQ and What's New entry (commit 08dca185)

### Security and Audit
- Default `BIND_HOST` to `0.0.0.0`; keep `::` as opt-in ([#1016](https://github.com/agentic-community/mcp-gateway-registry/pull/1016))
- Log authenticated users by name on `/api/stats` and public reads ([#1014](https://github.com/agentic-community/mcp-gateway-registry/pull/1014))

---

## Bug Fixes

- Use `update_agent` instead of `register_agent` for security-pending tag application ([#1035](https://github.com/agentic-community/mcp-gateway-registry/pull/1035)) - closes #1032, #1033
- Remove missed mcpgw ingress cleanup ([#1017](https://github.com/agentic-community/mcp-gateway-registry/pull/1017))
- Fix GitHub helm workflow ([#1012](https://github.com/agentic-community/mcp-gateway-registry/pull/1012))

---

## Closed Issues

| Issue | Title | Closed By |
|-------|-------|-----------|
| #1045 | feat(ui): add Skills (JSON array) field to Agent Quick Form registration | PR #1046 |
| #1034 | Bump litellm 1.83.0 -> 1.83.14 in root pyproject.toml | PR #1035 |
| #1033 | Agent registration silently fails to apply security-pending tag (uses register_agent instead of update_agent) | PR #1035 |
| #1032 | Agent registration silently fails to apply security-pending tag (calls register_agent instead of update_agent) | PR #1035 |
| #1028 | Support user-defined custom HTTP headers per MCP server | PR #1041 |
| #1026 | Enforce tool-level access control in list/response APIs and MCP tools/list | PR #1027 |
| #1022 | uv.lock missing/not used in docker builds | PR #1024 |
| #1008 | Unable to register mcp-server/agents on the UI | manual |
| #1000 | feat(deploy): add extra_env surface parity for Docker Compose and Terraform | PR #1019 |
| #986 | Enhance cloud provider detection in registry telemetry to reduce the "unknown" bucket | manual |
| #984 | feat(ui): make top-left UI title configurable with deployment-mode-aware defaults | PR #1043 |
| #960 | Intermittent `Session not found` errors when `mcpgw` runs with multiple replicas behind load balancing | PR #1021 |
| #944 | Resource-Bound Tokens | PR #1010 |
| #939 | feat: unauthenticated endpoints can try getting the logged in user | manual |
| #937 | feat: Support local mcp servers in registry | PR #1038 |
| #863 | IPv6 support: server bind addresses prevent deployment on IPv6-only Kubernetes clusters | PR #864 |
| #399 | feat: Implement server-side token storage to resolve session cookie size limit | manual |

---

## Pull Requests Included

| PR | Title |
|----|-------|
| #1046 | feat(ui): add Skills (JSON array) field to Agent Quick Form |
| #1043 | feat(ui): make UI title configurable with deployment-mode-aware defaults (#984) |
| #1041 | feat(servers): add custom HTTP headers support (#1028) |
| #1040 | Support json logging to stdout |
| #1038 | Feat/local mcp servers |
| #1035 | fix(agents+deps): use update_agent for security-pending tag (#1033) + bump litellm 1.83.14 (#1034) |
| #1027 | feat(auth): enforce tool-level access control in list and response APIs (#1026) |
| #1025 | feat(skills): add active-instances chart and LTV-spend generators to usage-report skill |
| #1024 | feat: uv.lock usage for docker and mcpgw embeddings cleanup |
| #1021 | feat: multi-replica airegistry-tools support |
| #1019 | feat(extra-env): add extra_env surface parity for Docker Compose and Terraform |
| #1018 | add goose as a connection option from the UI |
| #1017 | remove missed mcpgw ingress cleanup |
| #1016 | fix(bind-host): default BIND_HOST to 0.0.0.0; keep :: as opt-in |
| #1014 | fix(audit): log authenticated users by name on /api/stats and public reads |
| #1013 | chore(deps): bump urllib3 from 2.6.3 to 2.7.0 in /agents/a2a |
| #1012 | fix github helm workflow |
| #1011 | chore(deps): bump urllib3 from 2.6.3 to 2.7.0 in /metrics-service |
| #1010 | feat(auth): resource-bound JWT tokens (#944) |
| #967 | feat(helm): make ALB ingress scheme configurable with 3-tier override |
| #912 | Filter list of IDEs for MCP servers |
| #864 | feat: IPv6 dual-stack support for server bind addresses |

---

## Security Dependency Updates

| Package | Previous | Updated | Scope |
|---------|----------|---------|-------|
| urllib3 | 2.6.3 | 2.7.0 | metrics-service |
| urllib3 | 2.6.3 | 2.7.0 | agents/a2a |
| litellm | 1.83.0 | 1.83.14 | root pyproject.toml |

---

## Contributors

Thank you to all contributors for this release:

- **omrishiv** ([@omrishiv](https://github.com/omrishiv))
- **Amit Arora** ([@aarora79](https://github.com/aarora79))
- **Prateek Sinha** ([@shekharprateek](https://github.com/shekharprateek))
- **Soheil Safari** ([@soheilsf](https://github.com/soheilsf))
- **Max Peshkov** ([@mpeshkov](https://github.com/mpeshkov))
- **dependabot[bot]** ([@dependabot](https://github.com/dependabot))

---

## 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:** [1.23.0...1.24.0](https://github.com/agentic-community/mcp-gateway-registry/compare/1.23.0...1.24.0)
