aws / aws/aws-cli

bedrock-agentcore-control update-gateway: supportedVersions cannot be expanded after creation

Open
#10,346 6 comments 0 reactions 1 assignee Claimed by @RyanFitzSimmonsAK View on GitHub
bedrock bug closing-soon p3 response-requested service-api
Dominant language
Python
Stars
17.3k
Forks
4.6k
Avg merge
1d 2h
Merged PRs (30d)
13

Description

## Description

The `protocolConfiguration.mcp.supportedVersions` property on a BedrockAgentCore Gateway behaves as a one-way ratchet: versions can be removed from the list, but **cannot be added back** (or new versions added). This applies to both the `update-gateway` CLI/API and CloudFormation updates.

The CloudFormation documentation states that `ProtocolConfiguration` has "Update requires: No interruption", implying it is fully mutable. The actual behavior contradicts this.

## Reproduction Steps

**Step 1 — Create a gateway with two supported versions:**

```bash
aws bedrock-agentcore-control create-gateway \
--name "test-gateway" \
--role-arn "arn:aws:iam:::role/" \
--protocol-configuration '{
"mcp": {
"supportedVersions": ["2025-03-26", "2025-11-25"],
"instructions": "test"
}
}' \
--authorizer-type "CUSTOM_JWT" \
--authorizer-configuration '{"customJWTAuthorizer": {...}}' \
--region us-east-1
# ✅ Success
```

**Step 2 — Update to remove a version (works):**

```bash
aws bedrock-agentcore-control update-gateway \
--gateway-identifier \
--name "test-gateway" \
--role-arn "arn:aws:iam:::role/" \
--authorizer-type "CUSTOM_JWT" \
--authorizer-configuration '{"customJWTAuthorizer": {...}}' \
--protocol-configuration '{
"mcp": {
"supportedVersions": ["2025-03-26"],
"instructions": "test"
}
}' \
--region us-east-1
# ✅ Success — version removed
```

**Step 3 — Update to add the version back (fails):**

```bash
aws bedrock-agentcore-control update-gateway \
--gateway-identifier \
--name "test-gateway" \
--role-arn "arn:aws:iam:::role/" \
--authorizer-type "CUSTOM_JWT" \
--authorizer-configuration '{"customJWTAuthorizer": {...}}' \
--protocol-configuration '{
"mcp": {
"supportedVersions": ["2025-03-26", "2025-11-25"],
"instructions": "test"
}
}' \
--region us-east-1
# ❌ FAILS
```

## Error Message

```
An error occurred (ValidationException) when calling the UpdateGateway operation:
New MCP Version(s) cannot be added to existing gateway.
Update request to use the same version(s): [2025-03-26] or create a new gateway
```

## Expected Behavior

Adding a supported MCP version to an existing gateway should succeed. The `supportedVersions` property should be fully mutable (add and remove) as implied by the CloudFormation documentation stating "Update requires: No interruption".

## Actual Behavior

- Removing versions: **works**
- Adding versions (including re-adding previously removed versions): **fails**
- The only workaround is to **destroy and recreate the gateway**, which generates a new gateway ID and URL, requiring all clients to update their endpoint configuration.

## Impact

This makes `supportedVersions` effectively immutable in the "grow" direction. Users who need to add MCP version support to an existing gateway must destroy and recreate it, causing downtime and requiring all connected clients to reconfigure.

## Context: Why the version change was needed

The latest MCP protocol version (2025-11-25), which adheres to RFC 8707 (Resource Indicators), was failing
because the authentication layer was not compliant with RFC 8707. Due to this incompatibility, we had to fall
back to the older version (2025-03-26).

We performed this version change via CLI, which succeeded. However, this created drift between the actual
resource state and CloudFormation's tracked state. When we attempted to resolve the drift by redeploying via
CDK (matching the CLI-updated state), the deployment failed — the service rejected it stating the protocol
cannot be updated.

## In summary:
The supportedVersions property can only be updated once after creation. Any subsequent attempt to
modify it — even to align CloudFormation with the actual resource state — fails. The only recovery path is
destroying and recreating the gateway.

## Additional Context

- This same behavior occurs via CloudFormation/CDK — the root cause is the service API, not the CloudFormation resource provider.
- When combined with CloudFormation, CLI-based updates to this field create **unrecoverable drift** where subsequent CloudFormation deployments permanently fail with: `"Protocol type cannot be updated for an existing gateway"`.
- The CloudFormation documentation should be updated to reflect the actual mutability constraints.

## Suggested Fix

1. **Primary:** Allow adding new `supportedVersions` entries to existing gateways via the `UpdateGateway` API.
2. **Secondary:** If immutability is intentional, update the CloudFormation docs to mark `supportedVersions` as "Update requires: Replacement" so CloudFormation triggers a resource replacement instead of returning an error.

## Environment

- AWS CLI Version: 2.34.45
- Service: `bedrock-agentcore-control`
- API Action: `UpdateGateway`
- Region: us-east-1

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.