bedrock-agentcore-control update-gateway: supportedVersions cannot be expanded after creation
- 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
Assessment
This issue has not been assessed yet.