Release 1.38.0 - MCP Apps, Tool Annotations, Tool List Refresh, and Credentials Through Secrets Manager
November 2026
Upgrading from 1.37.0
This section covers everything you need to know to upgrade from 1.37.0 to 1.38.0.
Breaking Changes
There are no breaking changes in this release.
Other upgrade notes
- Terraform: credentials move to Secrets Manager. The first
terraform applycreates one Secrets Manager secret for each non-empty operator credential (14 variables, fromREGISTRY_API_TOKENtoGITHUB_APP_PRIVATE_KEY) and rolls out new task definitions for the registry and auth-server. Yourterraform.tfvarsstays as it is. Each secret costs the standard Secrets Manager rate. (#2069) - CDK: eight credentials move to Secrets Manager.
cdk deploycreates a secret for each configuredCDK_*credential and injects it by reference. The CDK quickstart now needsCDK_GRAFANA_ADMIN_PASSWORDwhileenableObservabilityis true, and the auth-server container listens on 18888 behind the unchanged 8888 alias. The CDK stack ininfra/is not actively maintained; Terraform is the supported AWS deployment. See infra/README.md. (#2064, #2076) COGNITO_DOMAINtakes a prefix. Leaving it empty or set toautonow derives the prefix fromCOGNITO_USER_POOL_IDfor the browser login and the token endpoints alike. Before, an empty value broke the login URL. A full hostname such asmcp-gw.auth.us-east-1.amazoncognito.comhas never worked, because the auth server appends.auth.<region>.amazoncognito.com; setmcp-gwinstead. A deployment that already sets a prefix sees no change. (#2071)- The gateway refuses ambiguous JSON-RPC bodies. An MCP request whose body repeats a key, or whose envelope or
paramsholds two keys that differ only by case, now gets 403. Standard MCP clients do not send such bodies. Toolargumentsmay still hold keys that differ only by case, such asContent-Typeandcontent-type. (#2061) - Servers with annotations re-embed once. After the upgrade, the first health check stores each tool's annotations, title and
outputSchema, and the registry re-embeds the servers that declare annotations. Servers without them keep their embeddings. (#2047) - Re-run
add-to-groupsfor groups that cannot see a server. Earlier releases wrote the server's display name into the group'slist_service, so members could call the server's tools but the UI did not list it. Runningadd-to-groupsagain writes the path name.remove-from-groupsremoves both forms. (#2067) - A repointed
airegistry-toolsloses the caller's token. The auth server now relays the caller's bearer token only when/airegistry-tools/points at the built-inhttp://mcpgw-server:8003/. If you repointed it at another host, that host no longer receives the token. (#2062) HEALTH_CHECK_INTERVAL_SECONDSon Terraform and Helm. The setting now reaches the registry on every surface, with the code default of 300 seconds on Terraform and Helm and 30 seconds in the Docker Compose files, as before. (#2056)
nginx advisory (NGINX2Root)
nginx 1.31.9, released on November 18, 2026, fixes CVE-2026-123007, CVE-2026-123633, CVE-2026-121810, CVE-2026-123634 and CVE-2026-113425 (NGINX2Root). This release does not include those fixes: the registry image ships Debian's nginx 1.26.3-3+deb13u10, and Debian has not yet published a package that carries them. The shipped nginx configuration does not meet the conditions any of the five require, because no listener enables HTTP/2 or HTTP/3 (QUIC), no location uses mirror, and the image has no mail block. If you added any of these to your own nginx configuration, remove them until a release ships the patched package.
New Environment Variables
| Variable | Default | Description |
|---|---|---|
TOOL_REFRESH_ENABLED
| false
| Fetches tools again, on a schedule, from servers that stay healthy, so the stored list picks up description and schema changes. Each registry replica refreshes on its own. (#2056) |
TOOL_REFRESH_EVERY_CYCLES
| 3
| Fetches each healthy server once every this many health cycles (1 to 1000). 3 cycles is 90 seconds at the Compose interval of 30 seconds, and 15 minutes at 300. (#2056) |
TOOL_FETCH_MAX_CONCURRENCY
| 5
| Most background tool fetches one registry process runs at once (1 to 100). Raise it to 10 for about a thousand servers. (#2056) |
HEALTH_CHECK_INTERVAL_SECONDS
| 300 (30 in Compose)
| Existing setting, now wired on Terraform and Helm. One tool refresh cycle. (#2056) |
New Terraform variables: health_check_interval_seconds, tool_refresh_enabled, tool_refresh_every_cycles and tool_fetch_max_concurrency. New Helm values on the registry chart and the stack globals: healthCheckIntervalSeconds, toolRefreshEnabled, toolRefreshEveryCycles and toolFetchMaxConcurrency. See tool list refresh.
Upgrade Instructions
Deploy the 1.38.0 images for the registry, auth-server and mcpgw.
Docker Compose
cd mcp-gateway-registry
git pull origin main
git checkout 1.38.0
# Review .env.example for the TOOL_REFRESH_* variables, then:
./build_and_run.shKubernetes / Helm (EKS)
cd mcp-gateway-registry
git pull origin main
git checkout 1.38.0
# REQUIRED: the subcharts changed, so rebuild the packaged dependencies
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.yamlTerraform / ECS
cd mcp-gateway-registry
git pull origin main
git checkout 1.38.0
# The plan creates one Secrets Manager secret per non-empty credential and
# new task definitions for the registry and auth-server.
cd terraform/aws-ecs
terraform plan
terraform applyMajor Features
MCP Apps on direct routes
MCP Apps lets a tool open an interactive page that the chat client renders in the conversation. The registry now declares the io.modelcontextprotocol/ui extension when it discovers tools, so servers that follow the spec list their page-opening tools to it. It stores each tool's ui:// page address and visibility, and the server card shows an MCP APP badge. Semantic search returns ui_resource_uri on tool results. Tools that only the page may call stay out of the search index and out of virtual servers. The auth-server proxy rewrites a page's Claude ui.domain to match the gateway URL, so pages such as draw.io's render in Claude through the gateway. See MCP Apps. (#2033, #2037)
Tool annotations, title and output schema
The registry keeps each tool's MCP annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint), title and outputSchema from tools/list, and returns them from the server API, semantic search, the search_registry tool and virtual servers. The UI shows READ ONLY and DESTRUCTIVE badges for hints a server declares. The registry does not verify the hints and uses none of them for authorization. See tool annotations. (#2047, closes #2046)
Tool list change detection and scheduled refresh
The health check used to save a fetched tool list only when the tool count, the server version or the annotations changed, so an edited description or input schema never reached search or the UI. The registry now hashes the whole list and saves it whenever the hash changes, and logs which tools were added, removed or changed. With TOOL_REFRESH_ENABLED=true, it also fetches tools again from servers that stay healthy, each on its own staggered schedule. One limit, TOOL_FETCH_MAX_CONCURRENCY, now caps every background tool fetch. See tool list refresh. (#2056, closes #2050)
One reading of every JSON-RPC body
The gateway reads method and params.name from an MCP request to route and authorize it, then forwards the same bytes to the backend. Python keeps the last of a repeated key, and some backend decoders match keys without regard to case, so one body could name one tool to the gateway and another to the backend. The auth server now parses every body it authorizes with a strict parser and refuses a body with more than one reading. (#2061)
Credentials reach containers through Secrets Manager
Terraform passed 14 operator credentials, and CDK passed eight, to the registry and auth-server as plain environment entries in the ECS task definition, where anyone with ecs:DescribeTaskDefinition could read them. Both now store each value in its own Secrets Manager secret, encrypted with the stack's KMS key, and the task definition holds only the ARN. Each execution role can read only the secrets its containers receive. The security guidelines now require a secret reference for any container credential. (#2069, #2076, #2072)
What's New
Registry, health and discovery
- A server on
atlassian-rovocan now fill its tool list through a discovery identity, which reuses the egress client that dynamic client registration created. The UI offers "Atlassian Rovo (reuses the egress client)". (#2066) - A passing rescan removes the
security-pendingtag a failing scan added, for servers, agents and skills. A failed scan no longer suggests checking a credential the server does not have, and it says when the registry reached the server by adding/mcpto its URL. (#2035, closes #2032) - Updating a skill's source now refreshes its raw URL, resource manifest and integrity baseline. A skill can be pinned to a GitHub commit permalink, and keeps its companion files. (#2045, #2074)
Infrastructure
- The CDK stack reaches parity with Terraform on startup secrets, the auth-server port,
TRUSTED_REAL_IP_CIDRS, egress auth, Cognito, PingFederate and per-service metrics. Both services failed to start under CDK before, because it never setAUTH_SERVER_NGINX_MARKER_SECRET. (#2064) - The CDK docs and a new
infra/README.mdsay that the CDK stack is not actively maintained. (#2065, #2068) - A CI job imports the auth server with only its own dependencies, as the auth-server image does. (#2038)
Documentation
- A new FAQ walks through a group that can call a different subset of tools on each server. (#2073)
- A new FAQ walks through a read-only viewer group and a user in it. (#2075)
- Example configs for the draw.io and Budget Allocator MCP Apps. (#2037)
api/openapi.jsoncovers the MCP Apps fields. (#2036)- New entries in
ADOPTERS.md. (#2049, #2051, #2059)
Bug Fixes
- The built-in
search_registrytool works through a virtual server. It failed with "Bearer token not found" because the virtual route skipped the hop that relays the caller's token. (#2062, closes #2060) - The virtual router no longer forwards a 2026-07-28 client's protocol-version
_metakeys to a backend that uses theinitializehandshake, which rejected them with-32020. It also starts a new backend session after a 400 only when the error is about the session. (#2053, closes #2052) - The Cognito browser login and token endpoints resolve
COGNITO_DOMAINthe same way. (#2071) add-to-groupswrites the server's path name tolist_service, so the group's members see the server in the UI. (#2067)- A server enabled while its registration scan runs stays enabled when the scan tags it
security-pending. The tag write reads the stored server and writes onlytags, so edits made during the scan survive. (#2057, #2058) - The nginx config no longer changes, and reloads, each time an unhealthy server's status text changes. The status text no longer appears in the config. (#2055)
Closed Issues
| Issue | Title | Closed By |
|---|---|---|
| #2063 | CDK: nine secrets are embedded in the synthesized template | PR #2076 |
| #2060 | Built-in airegistry-tools loses authentication through virtual servers | PR #2062 |
| #2052 | Virtual router forwards 2026-07-28 _meta to handshake-era backends, which reject it with -32020 | PR #2053 |
| #2050 | Detect tool description and schema changes, and add an opt-in staggered tool refresh | PR #2056 |
| #2046 | feat(mcp): store tool annotations, title and outputSchema from tools/list and return them in tool and search APIs | PR #2047 |
| #2032 | Security scan: clear security-pending after a passing rescan, and name the real cause when a scan fails
| PR #2035 |
| #2017 | Frontend tests: suites that import react-router-dom fail with "ReferenceError: TextEncoder is not defined" | manual |
| #2016 | Frontend tests: IAMListStates and IAMM2M suites fail with "useAuth must be used within an AuthProvider" | manual |
| #1961 | CDK stack: bring infra/ up to parity with the Terraform ECS stack
| manual (after PR #2064) |
| #1897 | Feature Request: Support MCP Apps in Registry Discovery, Search and Resource Access | manual (after PR #2033) |
| #1793 | Feature request: x402 pay-per-call settlement on the gateway | manual (not planned) |
Pull Requests Included
| PR | Title |
|---|---|
| #2076 | fix(cdk): inject operator credentials through Secrets Manager |
| #2075 | docs(faq): add a read-only viewer group and user walkthrough |
| #2074 | fix(skills): support skills pinned to a GitHub commit |
| #2073 | docs(scopes): add a per-server tool subset example and FAQ |
| #2072 | docs(security): require secret references for container credentials |
| #2071 | fix(auth): resolve the Cognito domain the same way for login and tokens |
| #2069 | fix(terraform): inject operator credentials through Secrets Manager |
| #2068 | docs(cdk): add an infra/ README with the maintenance status up front |
| #2067 | fix(scopes): add-to-groups writes the server's path name to list_service |
| #2066 | feat(egress): let a discovery identity use atlassian-rovo |
| #2065 | docs(cdk): mark the CDK stack as not actively maintained |
| #2064 | fix(cdk): bring infra/ up to parity with the Terraform ECS stack (phases 1-5) |
| #2062 | fix(virtual): keep the caller's token for built-in airegistry-tools on virtual servers |
| #2061 | Parse JSON-RPC request bodies strictly so the gateway and backend read them the same way |
| #2059 | Add LSEG organization to ADOPTERS.md |
| #2058 | fix(security): build the security-pending tag write from the stored server |
| #2057 | fix(security): keep a server enabled when the registration scan tags it security-pending |
| #2056 | feat(health): detect tool definition changes and add an opt-in staggered tool refresh (#2050) |
| #2055 | fix(nginx): leave health status text out of unhealthy-server comments |
| #2053 | fix(virtual): keep 2026-07-28 _meta off handshake-era backends; narrow the 400 retry |
| #2051 | docs: link Expedia Group contact to GitHub profile in ADOPTERS.md |
| #2049 | docs: add Expedia Group to ADOPTERS.md |
| #2047 | feat(mcp): store tool annotations, title and outputSchema from tools/list |
| #2045 | fix(skills): refresh content when the source changes |
| #2043 | chore(deps): bump the actions group in /.github/workflows with 2 updates |
| #2041 | chore(deps): bump the uv group across 5 directories with 1 update |
| #2038 | ci: import the auth server with only its own dependencies |
| #2037 | docs: add example configs for the draw.io and Budget Allocator MCP Apps |
| #2036 | chore: refresh api/openapi.json after #2033 |
| #2035 | fix: clear security-pending after a passing rescan, and point scan errors at the cause |
| #2033 | feat: MCP Apps support on direct routes: detection, UI badge, search, and Claude ui.domain rewrite |
| #1990 | chore(deps): bump filelock from 3.32.7 to 4.2.1 in the uv group across 1 directory |
Security Dependency Updates
| Package | Previous | Updated | Scope |
|---|---|---|---|
| filelock | 3.32.7 | 4.2.1 | Root project (#1990) |
| dnspython | 2.9.1 | 2.9.2 | Root, auth_server, mcpgw, currenttime and realserverfaketools (#2041) |
| peter-evans/create-pull-request | 8.1.1 | 8.1.2 | GitHub Actions (#2043) |
| github/codeql-action/upload-sarif | 4.39.1 | 4.39.3 | GitHub Actions (#2043) |
Contributors
Thank you to all contributors for this release:
- Amit Arora (@aarora79)
- Gonçalo Faustino (@go-faustino)
- Prateek Sinha (@shekharprateek)
- Eugene Myasyshchev (@gemyago)
- Damian de Vega (@damiandevega)
- narao (@NatalieRaoEg)
Support
Full Changelog: 1.37.0...1.38.0