AgentCore Gateway 如何支持 MCP 2026-07-28 规范

今天，Model Context Protocol（MCP）发布了其 2026-07-28 规范，这是该协议自推出以来规模最大、最重要的一次修订。借助此次发布，MCP 成为可在普通 HTTP 基础设施上扩展的无状态协议。除传输层变更外，新版本还引入了受治理的扩展系统；通过更贴近 OAuth 2.0 和 OpenID Connect 企业实践的方式强化授权；并建立生命周期保障机制，以限制未来的兼容性破坏。

从今天起，您可以在 AgentCore Gateway 上使用最新协议。AgentCore Gateway 是 Amazon Bedrock AgentCore 的一项能力；只需调用 UpdateGateway，并提供希望 Gateway 支持的版本列表即可。现有客户端会像以前一样继续工作，且无需针对每个目标分别操作。本文将介绍协议发生了哪些变化、变更原因、这些变化对您的 Agent 和工具意味着什么，以及如何在 Gateway 上启用新版本。

已经熟悉规范变更？可直接跳至“更新您的 AgentCore Gateway”。

新规范有哪些变化，以及为何重要

本次发布包含对 MCP 协议的向后不兼容变更。转向无状态是一项基础性变革，协议维护者认为这是解决企业部署扩展挑战的必要措施。不过，在新版本中引入破坏性变更预计不会成为常态。为了帮助未来版本实现向后兼容的更新，维护者为协议规范引入了新的治理增强机制（功能生命周期政策、扩展框架和一致性测试套件要求）。这些增强旨在支持协议演进，同时不破坏核心能力。

升级也是**自愿选择加入（opt-in）**的；在您和客户端都采取行动前，不会发生任何变化。AgentCore Gateway 通过单一配置字段声明其支持的协议版本。客户端会在每个请求中选择一个版本。向同时声明支持 2025-11-25 的 Gateway 添加 2026-07-28，并不会改变请求旧版本的客户端行为。只有请求 2026-07-28 的客户端才会获得新行为。7 月 28 日不会有任何东西突然中断。

1. MCP 现在是无状态的

在先前版本的协议中，与 MCP 服务器进行的每次 Streamable HTTP 交互都以 initialize/initialized 握手开始，客户端和服务器在此过程中交换协议版本和能力。随后，服务器会签发一个 Mcp-Session-Id 标头，之后的每个请求都必须携带该标头：

POST /mcp HTTP/1.1
Mcp-Session-Id: 1868a90c-3a3f-4f5b
Content-Type: application/json
Accept: application/json

{"jsonrpc":"2.0","id":2,"method":"tools/call",
"params":{"name":"search","arguments":{"q":"otters"}}}

该会话会将客户端固定到签发它的服务器。因此，要对 MCP 服务器进行水平扩展，运营人员需要在负载均衡器上配置粘性会话、在服务器集群后部署共享会话存储，或者同时采用两者。

通过移除会话，远程 MCP 服务器实际上成为标准 HTTPS 端点，从而能够针对企业工作负载进行清晰扩展。随着协议转为无状态，握手和协议级会话均不再需要（SEP-2575 和 SEP-2567 从新协议版本中移除了这些要求）。在 2026-07-28 版本中，每个请求现在都会在其 _meta 参数内携带协议版本、客户端信息和客户端能力，从而消除一次性初始化握手的必要。需要了解服务器支持内容的客户端，可随时调用新的 server/discover 方法。最终效果是：单次工具调用完全自包含，不需要任何先前会话上下文，也可以被路由至任意服务器实例。移除协议会话并不意味着不能支持有状态应用。当服务器需要跨调用保持连续性时，您可以遵循既有 HTTP 请求模式，通过工具参数传递显式 ID；该 ID 应来自您自己的某个工具。

POST /mcp HTTP/1.1
MCP-Protocol-Version: 2026-07-28
Mcp-Method: tools/call
Mcp-Name: create_basket
Content-Type: application/json
Accept: application/json,text/event-stream

{"jsonrpc":"2.0","id":1,"method":"tools/call",
"params":{"name":"create_basket","arguments":{},
"_meta":{"io.modelcontextprotocol/clientInfo":{"name":"my-app","version":"1.0"}}}}

响应：

{"jsonrpc":"2.0","id":1,
"result":{"resultType":"complete","content":[{"type":"text","text":"Created basket bsk_a1b2c3"}],"structuredContent":{"basket_id":"bsk_a1b2c3"},"isError": false}}

随后，您可以利用 Agent 自身的能力，在后续请求中传递此状态句柄：

POST /mcp HTTP/1.1
MCP-Protocol-Version: 2026-07-28
Mcp-Method: tools/call
Mcp-Name: add_item
Content-Type: application/json
Accept: application/json,text/event-stream

{"jsonrpc":"2.0","id":1,"method":"tools/call",
"params":{"name":"add_item","arguments":{"basket_id": "bsk_a1b2c3", "sku": "shoes"},
"_meta":{"io.modelcontextprotocol/clientInfo":{"name":"my-app","version":"1.0"}}}}

AgentCore Gateway 一直以来都让 Agent 免于处理 MCP 会话机制中的大部分复杂性。它将您的 AWS Lambda 函数、API 和 MCP 服务器汇集到单个 MCP 端点之后，并代表您管理与每个目标进行的协议交互。使用 2026-07-28 后，双方都将变得更简单：Agent 的首次工具调用将是一个自包含请求，而不再是先握手再调用。每个请求都携带 Mcp-Protocol-Version 标头。当该版本出现在 supportedVersions 中时，Gateway 会按该版本处理请求；如果未出现，则会以 HTTP 400（代码 -32022）拒绝请求，并返回受支持版本列表。未携带该标头的请求默认使用 2025-03-26。

2. 无需解析请求体即可实现路由、缓存和追踪

在早期协议版本中，请求所执行的操作对于客户端与服务器之间的任何组件都是不透明的。负载均衡器、API Gateway 和限流器都必须解析 JSON-RPC 请求体，才能确定调用了哪个方法。检测服务器工具目录的变更，意味着必须保持一个长期存活的 SSE 流，并等待推送通知。简而言之，MCP 流量并不能很好地适配标准 HTTP 基础设施。

2026-07-28 通过三种方式弥合了这一差距。首先，每个 Streamable HTTP 请求现在都会在标准标头中暴露其意图：Mcp-Method 和 Mcp-Name（SEP-2243）位于请求体之外，使中间件仅在 HTTP 层就能获得足够的信息来进行路由、限流和计量。若服务器收到的请求中，声明的标头与请求体相互矛盾，服务器将直接拒绝该请求。其次，列表和资源读取操作的响应现在包含明确的新鲜度元数据 ttlMs 和 cacheScope，其语义借鉴自 HTTP Cache-Control（SEP-2549）。客户端可以在已知时长和作用域内缓存 tools/list 响应，而无需维持持久连接，仅仅为了监听失效通知。第三，规范现在在 _meta 内保留 W3C Trace Context 键（traceparent、tracestate、baggage）（SEP-414），将多个 SDK 实际上已经采用的实践正式规范化。源自您的应用程序的分布式追踪，现在可以贯穿完整调用链：从 Agent 到 MCP 客户端、Gateway，再到下游服务，并在任何兼容 OpenTelemetry 的采集器中呈现为统一的 span 树。

在 2026-07-28 路径上，AgentCore Gateway 会直接提供这些原语。Gateway 返回的每个工具结果都携带新的结构化结果封装；可缓存结果则会包含面向符合规范的客户端 SDK 的 TTL 和作用域提示。Gateway 还会强制执行自定义标头绑定：当工具的输入模式将某个字段标记为绑定到标头时，Gateway 会拒绝任何缺失该标头或其标头值与请求体不一致的请求（HTTP 400，代码 -32020）。

3. 无需持久连接的服务器到客户端交互

无状态协议仍然需要一种机制，让服务器能在调用过程中向客户端发起交互。MCP 有三类此类交互：征询（elicitation），即服务器向最终用户请求输入（“此工具即将删除三个文件。确认吗？”）；Roots，即服务器请求文件系统中可用的目录和文件；以及采样（sampling），即服务器请求客户端的模型生成响应。在以前的版本中，传递这些请求意味着服务器需要向客户端保持一个 SSE 流。

在最新协议版本中，服务器发起的请求现在仅允许在服务器正在主动处理客户端请求时进行（SEP-2260）。用户看到的每个提示都可追溯到其本人或其 Agent 发起的操作。多轮往返请求（Multi Round-Trip Requests，SEP-2322）取代了此前的长期存活流。在该模式下，服务器将问题嵌入 InputRequiredResult 中，并通过不透明的 requestState 令牌外部化状态，而不是通过 SSE 推送问题。只有声明征询或采样输入的工具才会触发多轮往返交互，而且仅在客户端声明支持该能力时才会触发。

{
  "resultType": "input_required",
  "inputRequests": {
    "confirm": {
      "method": "elicitation/create",
      "params": {
        "mode": "form",
        "message": "Delete 3 files?",
        "requestedSchema": {
          "type": "object",
          "properties": {
            "confirm": {
              "type": "boolean"
            },
            "required": ["confirm"]
          }
        }
      }
    },
    "requestState": "eyJzdGVwIjoxLCJmaWxlcyI6WyJhIiwiYiIsImMiXX0="
  }
}

客户端收集用户回答后，会携带回答内容和 requestState 重新发起原始调用。服务器所需的一切都在负载中，因此任意服务器实例都可以接手这次重试。

此外，进度通知和日志传递现在都以请求为作用域。仅当客户端在原始请求中提供进度令牌时，Gateway 才会转发进度更新；仅当客户端在每请求元数据中设置 io.modelcontextprotocol/logLevel 时，才会传递日志消息。

4. 将扩展与核心规范解耦

截至目前，MCP 扩展一直是一种缺乏治理机制的非正式概念。SEP-2133 引入了治理框架。每个扩展均带有反向 DNS ID，通过客户端和服务器能力中的 extensions 映射协商，在由受委托维护者管理的独立代码库中维护，并遵循独立于核心规范的自身发布节奏。SEP 流程中新设立的 Extensions Track 定义了扩展如何从实验状态晋升为正式状态，这改变了协议的发展方式。与其让每个新想法都争夺核心规范中的空间并强制进行破坏性版本升级，能力现在可以作为可选加入的扩展，按各自时间线逐步成熟。未协商某项扩展的客户端和服务器不会受到影响。

5. 授权强化

六项 SEP 使 MCP 的授权规范与生产环境 OAuth 2.0 和 OpenID Connect 部署更加一致。无论您 Gateway 的入站授权使用 IAM（SigV4）还是 OAuth/JWT，均不会因协议版本而改变。您的出站凭证提供程序也是如此。升级协议版本不需要变更凭证或授权器配置。

6. 错误处理和弃用项

在早期协议版本中，几乎所有情况都会返回 HTTP 200，并将错误隐藏在 JSON-RPC 请求体中，其中也包括传输层失败。在 2026-07-28 中，传输层与应用层被清晰分离。传输失败会返回真实 HTTP 状态码；应用层结果仍保留在请求体中：

情形	2025- 版本*	2026-07-28
未知方法	请求体内 JSON-RPC 错误，HTTP 200	HTTP 404
不支持的协议版本	不同情况有所不同	HTTP 400，代码 -32022。请求体列出支持的版本
绑定到标头的字段缺失或不匹配	不同情况有所不同	HTTP 400，代码 -32020
缺少必需的客户端能力	不适用	代码 -32021

这些变更仅会影响检查错误响应的代码。它们使您的 HTTP 层监控、告警和重试逻辑能够在无需解析请求体的情况下，区分路由问题与应用层问题。该规范还将“resource not found”错误码从 MCP 专用的 -32002 重新分配为 JSON-RPC 标准的 -32602 Invalid Params（SEP-2164）。如果您的客户端在任何位置匹配 -32002，请审查这些代码路径。此外，在 2026-07-28 路径上：logging/setLevel 已被废弃，调用它的客户端会被拒绝。若要启用日志传递，您可以改为设置每请求元数据字段 io.modelcontextprotocol/logLevel。

根据协议新的功能生命周期政策（SEP-2577），三项核心功能已被弃用：Roots（由工具参数、资源 URI 或服务器配置替代）、Sampling（由与 LLM 提供商 API 的直接集成替代），以及

[原文在此处截断]

Today, the Model Context Protocol (MCP) published its 2026-07-28 specification, the largest and most significant revision of the protocol since its launch. With this release MCP becomes a stateless protocol that scales on ordinary HTTP infrastructure. Alongside the transport changes, this new version introduces a governed extensions system, strengthens authorization by aligning more closely with enterprise practices for OAuth 2.0 and OpenID Connect, and establishes lifecycle guarantees that limit future breakage.

You can start using the latest protocol on your AgentCore Gateway, a capability of Amazon Bedrock AgentCore, today by calling UpdateGateway with the list of versions you want your gateway to support. Existing clients keep working exactly as before, and there is no per-target step. In this post, we walk through what changed in the protocol and why, what it means for your agents and tools, and how to enable the new version on your gateways.

Already familiar with the spec changes? Jump straight to Updating your AgentCore Gateway.

What changes with the new spec and why it matters

This release contains backward-incompatible changes to the MCP protocol. The transition to statelessness is a foundational change that protocol maintainers believe is necessary to address scaling challenges with enterprise deployments. The introduction of breaking changes with new versions, however, is not expected to be the norm. To help facilitate backward-compatible updates in future revisions, maintainers have introduced new governance enhancements to the protocol specification (a feature lifecycle policy, an extensions framework, and a conformance-suite requirement). These enhancements are designed to support protocol evolution without breaking core capabilities.

Upgrading is also opt-in , and nothing changes until both you and your clients act. AgentCore Gateway advertises the protocol versions it speaks through a single configuration field. Clients select a version on every request. Adding 2026-07-28 to a gateway that also advertises 2025-11-25 does not change anything for clients that request the older version. Only a client that requests 2026-07-28 gets the new behavior. Nothing breaks on July 28.

1. MCP is now stateless

In prior versions of the protocol, every Streamable HTTP interaction with an MCP server began with an initialize/initialized handshake, in which the client and server exchanged protocol versions and capabilities. The server then issued an Mcp-Session-Id header that every subsequent request was required to carry:

POST /mcp HTTP/1.1
Mcp-Session-Id: 1868a90c-3a3f-4f5b
Content-Type: application/json
Accept: application/json

{"jsonrpc":"2.0","id":2,"method":"tools/call",
"params":{"name":"search","arguments":{"q":"otters"}}}

That session pinned the client to the server that issued it. Therefore, to scale an MCP server horizontally, operators needed sticky sessions at the load balancer, a shared session store behind the fleet, or both.

By removing sessions, remote MCP servers effectively become standard HTTPS endpoints, which scale cleanly with enterprise workloads. As the protocol becomes stateless, the handshake and the protocol-level session are both no longer needed (SEP-2575 and SEP-2567 remove these requirements from the new protocol version). With 2026-07-28, every request now carries protocol version, client info, and client capabilities inside its _meta parameter, eliminating the need for a one-time initialization handshake. Clients that need to learn what a server supports can call the new server/discover method at any point. The net effect is that a single tool call is fully self-contained. It requires no prior session context and can be routed to any server instance. Removing the protocol session does not preclude support for stateful applications. When servers need continuity across calls, you can follow established patterns for HTTP requests by passing an explicit ID as a tool parameter, which should come from one of your own tools.

POST /mcp HTTP/1.1
MCP-Protocol-Version: 2026-07-28
Mcp-Method: tools/call
Mcp-Name: create_basket
Content-Type: application/json
Accept: application/json,text/event-stream

{"jsonrpc":"2.0","id":1,"method":"tools/call",
"params":{"name":"create_basket","arguments":{},
"_meta":{"io.modelcontextprotocol/clientInfo":{"name":"my-app","version":"1.0"}}}}

Response:

{"jsonrpc":"2.0","id":1,
"result":{"resultType":"complete","content":[{"type":"text","text":"Created basket bsk_a1b2c3"}],"structuredContent":{"basket_id":"bsk_a1b2c3"},"isError": false}}

You can then use the agent’s own capabilities to thread this state handle through subsequent requests:

POST /mcp HTTP/1.1
MCP-Protocol-Version: 2026-07-28
Mcp-Method: tools/call
Mcp-Name: add_item
Content-Type: application/json
Accept: application/json,text/event-stream

{"jsonrpc":"2.0","id":1,"method":"tools/call",
"params":{"name":"add_item","arguments":{"basket_id": "bsk_a1b2c3", "sku": "shoes"},
"_meta":{"io.modelcontextprotocol/clientInfo":{"name":"my-app","version":"1.0"}}}}

AgentCore Gateway has always shielded agents from much of MCP’s session mechanics. It aggregates your AWS Lambda functions, APIs, and MCP servers behind a single MCP endpoint and manages the protocol conversation with each target on your behalf. With 2026-07-28, that gets simpler on both sides: an agent’s first tool call is one self-contained request rather than a handshake followed by a call. Each request carries an Mcp-Protocol-Version header. The gateway serves the request in that version when the version appears in supportedVersions, or rejects it with HTTP 400 (code -32022) and a list of supported versions when it does not. Requests that omit the header default to 2025-03-26.

2. Routing, caching, and tracing without parsing the body

In prior versions of the protocol, the operation a request performed was opaque to anything sitting between client and server. Load balancers, API gateways, and rate limiters all had to parse the JSON-RPC body to determine what method was being called. Detecting changes to a server’s tool catalog meant holding a long-lived SSE stream open and waiting for a push notification. MCP traffic, in short, did not play well with standard HTTP infrastructure.

2026-07-28 closes that gap in three ways. First, every Streamable HTTP request now surfaces its intent in standard headers: Mcp-Method and Mcp-Name (SEP-2243) travel outside the body, giving intermediaries enough information to route, throttle, and meter at the HTTP layer alone. A server that receives a request where the declared headers contradict the body rejects it outright. Second, responses to list and resource-read operations now include explicit freshness metadata, ttlMs and cacheScope, borrowed from the semantics of HTTP Cache-Control (SEP-2549). Clients can cache a tools/list response for a known duration and scope without maintaining a persistent connection only to watch for invalidations. Third, the spec now reserves the W3C Trace Context keys (traceparent, tracestate, baggage) inside _meta (SEP-414), formalizing what several SDKs had already adopted in practice. A distributed trace originating in your application can now propagate through the full call chain, from agent to MCP client to gateway to downstream service, and render as a unified span tree in any OpenTelemetry-compatible collector.

On the 2026-07-28 path, AgentCore Gateway surfaces these primitives directly. Every tool result from your gateway carries the new structured result envelope, and cacheable results include TTL and scope hints for conformant client SDKs. The gateway also enforces the custom-header binding: when a tool’s input schema marks a field as header-bound, the gateway rejects any request whose header is absent or contradicts the body (HTTP 400, code -32020).

3. Server-to-client interactions without persistent connections

A stateless protocol still needs a way for a server to talk back to the client mid-call. MCP has three such interactions: elicitation, where the server asks the end user for input (“this tool is about to delete three files. Confirm?”), roots, where the server asks for available directories and files in the filesystem, and sampling, where the server asks the client’s model to generate a response. In previous versions, delivering these requests meant the server held an SSE stream open back to the client.

With the latest protocol version, server-initiated requests are now only permitted while the server is actively processing a client request (SEP-2260). Every prompt a user sees traces back to something they or their agent started. Multi Round-Trip Requests (SEP-2322) replace the previous long-lived stream. Here, the server embeds questions in an InputRequiredResult and externalizes state through an opaque requestState token rather than pushing a question over SSE. Only tools that declare elicitation or sampling inputs trigger the multi-round-trip exchange, and only when the client advertises support for it.

{
  "resultType": "input_required",
  "inputRequests": {
    "confirm": {
      "method": "elicitation/create",
      "params": {
        "mode": "form",
        "message": "Delete 3 files?",
        "requestedSchema": {
          "type": "object",
          "properties": {
            "confirm": {
              "type": "boolean"
            },
            "required": ["confirm"]
          }
        }
      }
    },
    "requestState": "eyJzdGVwIjoxLCJmaWxlcyI6WyJhIiwiYiIsImMiXX0="
  }
}

Clients collect the user’s answers and re-issue the original call with the responses and the requestState. Everything the server needs is in the payload, so any server instance can pick up the retry.

Separately, progress notifications and log delivery are now request-scoped. The gateway relays progress updates only when the client supplies a progress token on the originating request, and delivers log messages only when the client sets io.modelcontextprotocol/logLevel in per-request metadata.

4. Decoupling extensions from the core spec

Until now, MCP extensions were an informal concept with no governance behind them. SEP-2133 introduces one. Each extension carries a reverse-DNS ID, is negotiated through an extensions map in client and server capabilities, lives in a dedicated repository under delegated maintainers, and follows its own release cadence independent of the core spec. A new Extensions Track within the SEP process defines how an extension graduates from experimental to official status, which changes how the protocol grows. Rather than every new idea competing for space in the core specification and forcing a breaking version bump, capabilities can now mature as opt-in extensions on their own timelines. Clients and servers that do not negotiate a given extension are unaffected.

5. Authorization hardening

Six SEPs bring MCP’s authorization specification into closer alignment with production OAuth 2.0 and OpenID Connect deployments. Your gateway’s inbound authorization, whether IAM (SigV4) or OAuth/JWT, is unchanged by the protocol version. So are your outbound credential providers. Upgrading the protocol version does not require changing credentials or authorizer configuration.

6. Error handling and deprecations

On earlier protocol versions, nearly everything came back as HTTP 200 with an error tucked inside the JSON-RPC body, including transport-level failures. On 2026-07-28, the transport and application layers are cleanly separated. Transport failures return real HTTP status codes. Application-level outcomes stay in the body:

Situation	2025- versions*	2026-07-28
Unknown method	In-body JSON-RPC error, HTTP 200	HTTP 404
Unsupported protocol version	Varies	HTTP 400, code -32022. Body lists supported versions
Header-bound field absent or mismatched	Varies	HTTP 400, code -32020
Missing required client capability	Not applicable	Code -32021

These changes only matter for code that inspects error responses. They let your HTTP-level monitoring, alarming, and retry logic distinguish routing problems from application-level issues without parsing the body. The spec also reassigns the “ resource not found ” error code from the MCP-specific -32002 to JSON-RPC’s standard -32602 Invalid Params (SEP-2164). If your client matches on -32002 anywhere, audit those code paths. Additionally, on the 2026-07-28 path: logging/setLevel is retired, and a client that calls it is rejected. To opt into log delivery, you can set the per-request metadata field io.modelcontextprotocol/logLevel instead.

Three core features are deprecated under the protocol’s new feature lifecycle policy (SEP-2577): Roots (replaced by tool parameters, resource URIs, or server configuration), Sampling (replaced by direct integration with LLM provider APIs), and Logging (replaced by stderr for stdio transports and OpenTelemetry for structured observability). These deprecations are advisory. The methods, types, and capability flags remain functional in this release and in any specification version published within twelve months of it. However, we highly recommend that new implementations not take a dependency on them.

7. Schema support

Tool inputSchema and outputSchema now support the full JSON Schema 2020-12 vocabulary (SEP-2106). Input schemas retain the type: "object" root requirement but gain composition keywords (oneOf, anyOf, allOf), conditionals, and internal references ($ref, $defs). Output schemas have no root-type restriction, and structuredContent may be any valid JSON value. Implementations must not follow external $ref URIs automatically and should enforce depth and time limits during validation.

Deciding if you’re ready to update

Work through three questions before you enable the new version:

1. Are your clients ready? Your agents reach Gateway through MCP client SDKs. Check that the SDKs your agent frameworks and host applications use have shipped 2026-07-28 support. Tier 1 SDKs were expected to ship support during the ten-week release candidate window, so most mainstream stacks are ready today. See the MCP SDK documentation for the current tier list. Test clients that support 2026-07-28 before you advertise it on a production gateway.
2. Does anything you run depend on removed or changed behavior? Audit for: protocol sessions used to carry application state, logging/setLevel, client code matching the literal -32002 error code, and any dependence on Roots, Sampling, or Logging. If your tools use elicitation or sampling, note that the gateway carries these through a new per-request mechanism on 2026-07-28 rather than a persistent session. Confirm your clients declare the matching capability. A client that omits it is rejected with code -32021.
3. Do you control both sides? You don’t need to. Version selection happens per request, so a dual-version gateway serves old and new clients simultaneously. You can upgrade clients and the gateway on independent schedules, in either order.

For the full details, see the MCP 2026-07-28 specification the changelog against 2025-11-25, and the MCP blog’s release candidate announcement

Updating your AgentCore Gateway

For AgentCore Gateway customers, adopting 2026-07-28 is a configuration change. Your AgentCore Gateway can support multiple protocol versions simultaneously. You can add 2026-07-28 to your gateway’s list of supportedVersions with a single UpdateGateway call. There’s no need to re-create the gateway or make changes to individual gateway target configurations. The MCP version is a property of the gateway, not of its targets, and updates to that property are performed in place. Tool definitions, target configuration, and inbound authentication (IAM and OAuth) are all unchanged by the version change.

UpdateGateway replaces supportedVersions with the set you send. It does not append. Read the current configuration first, then send the complete list you want the gateway to advertise:

# 1. Read the current configuration.
aws bedrock-agentcore-control get-gateway \
    --gateway-identifier <gateway-id>

# 2. Advertise 2026-07-28 alongside the existing version.
aws bedrock-agentcore-control update-gateway \
    --name <gateway-name> \
    --role-arn <gateway-role-arn> \
    --protocol-type MCP \
    --authorizer-type <gateway-authorizer-type> \
    --gateway-identifier <gateway-id> \
    --protocol-configuration '{
  "mcp": {
    "supportedVersions": ["2025-11-25", "2026-07-28"]
  }
}'

AgentCore Gateway works with any of the following protocol versions: 2025-03-26, 2025-06-18, 2025-11-25, and 2026-07-28.

Confirm the new version is live by calling your gateway with the new headers:

curl -s https://<your-gateway-endpoint>/mcp \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json,text/event-stream" \
    -H "MCP-Protocol-Version: 2026-07-28" \
    -H "Mcp-Method: tools/list" \
    -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

A successful response confirms the gateway served the request at 2026-07-28. A rejection with code -32022 means the version isn’t in the gateway’s supportedVersions yet, and the response body lists what the gateway currently advertises.

supportedVersions is the complete set the gateway advertises, so rolling back is the same operation in reverse. That is, send the list without 2026-07-28. Requests specifying the removed version are rejected with a response body listing the versions the gateway still supports. Make sure clients you’ve already migrated can fall back before you remove the version they’re requesting.

How version selection works

Clients select a version on each request, not through a one-time handshake. Each MCP request declares its version in the MCP-Protocol-Version header, and the gateway honors it when it’s in supportedVersions:

• A request naming a version the gateway advertises is served in that version. On a dual-version gateway (for example, 2026-07-28 and 2025-11-25), a 2026-07-28 request gets the new behavior and a 2025-11-25 request gets the earlier behavior.
• A request naming a version the gateway does not advertise is rejected with HTTP 400 and code -32022. The response body lists the versions the gateway supports.
• A request that omits the header gets the default version, 2025-03-26. If that default isn’t in the gateway’s supportedVersions, the request is rejected.

Your existing clients continue to work as long as they request protocol versions listed in the gateway’s supportedVersions. That gives you a clean, three-stage rollout: add 2026-07-28 alongside your existing versions, migrate clients at your own pace, and only after all clients request the new version, trim the list down.

If your gateway fronts an MCP server target that upgrades to 2026-07-28 before your clients do, it translates between versions, so a 2025-* client can call ordinary tools on a 2026-07-28 target and receive results in the format it expects, without upgrading. However, this translation does not currently support elicitations and sampling calls from servers to clients. If a 2025-* client calls a tool on the 2026-* server that requires elicitation or sampling, it receives an error.

Conclusion

MCP 2026-07-28 is the protocol’s biggest revision ever, and it’s designed to be the last revision that breaks compatibility. Statelessness gives MCP a foundation that scales on commodity HTTP infrastructure while MCP Extensions give new capabilities room to evolve on their own schedules.

With Amazon Bedrock AgentCore Gateway, adding support for the latest protocol version is only one UpdateGateway call. To get started, see the AgentCore Gateway documentation, review the MCP 2026-07-28 specification and its changelog, and try enabling the new version on a gateway today. If you have feedback on the specification itself, the maintainers welcome issues in the MCP specification repository. For questions about AgentCore Gateway, reach out through AWS re:Post or your usual AWS Support channels.

---

About the authors

Sean Eichenberger

Sean is a Principal Product Manager at AWS Agentic AI. He leads initiatives across agent governance, safety, and connectivity for Amazon Bedrock AgentCore.

Luca Chang

Luca is a Software Development Engineer at AWS working on Amazon Bedrock AgentCore, and is an MCP specification maintainer. Luca is an author of the MCP Tasks feature proposal and is an active bridge between AWS customer needs and protocol development efforts. His background spans distributed systems and complex AI applications.