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

[ggundal]

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:

aws bedrock-agentcore-control create-gateway \
  --name "test-gateway" \
  --role-arn "arn:aws:iam::<ACCOUNT_ID>:role/<ROLE_NAME>" \
  --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):

aws bedrock-agentcore-control update-gateway \
  --gateway-identifier <GATEWAY_ID> \
  --name "test-gateway" \
  --role-arn "arn:aws:iam::<ACCOUNT_ID>:role/<ROLE_NAME>" \
  --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):

aws bedrock-agentcore-control update-gateway \
  --gateway-identifier <GATEWAY_ID> \
  --name "test-gateway" \
  --role-arn "arn:aws:iam::<ACCOUNT_ID>:role/<ROLE_NAME>" \
  --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

[danyalahmed1995]

This looks service-side rather than CLI-specific. The CLI seems to be sending the modeled supportedVersions field, and the rejection comes back from UpdateGateway as a ValidationException.

The mismatch may be in the docs/resource behavior: CloudFormation marks this path as updatable without interruption, but adding a new MCP version appears to be rejected by the service.

[adev-code]

Thanks for reaching out @ggundal. I have reached out to the Service team and I will update you as soon as there are updates.

Internal Ref: P442430094