How AgentCore Gateway supports the MCP 2026-07-28 spec

AgentCore 网关如何支持 MCP 2026-07-28 规范 | 人工智能

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

今天，模型上下文协议（MCP）发布了其 2026-07-28 版本规范，这是自协议发布以来规模最大的一次修订。此次更新使 MCP 成为可在普通 HTTP 基础设施上扩展的无状态协议。除了传输层变更外，新版本引入了受控扩展系统，通过更贴近企业实践的 OAuth 2.0 和 OpenID Connect 增强了授权机制，并建立了生命周期保障以减少未来版本变更带来的影响。

您现在可以通过调用 UpdateGateway 并指定网关需要支持的版本列表，在 Amazon Bedrock AgentCore 的 AgentCore 网关上立即使用最新协议。现有客户端无需任何修改即可继续正常运行，且无需针对每个目标执行额外步骤。在本文中，我们将带您了解协议变更内容及其原因，这些变更对您的代理和工具意味着什么，以及如何在网关上启用新版本。

已经熟悉规范变更内容？可直接跳转至 [更新您的 AgentCore 网关](#)。

新规范变更内容及重要性

此次发布包含对 MCP 协议的向后不兼容变更。向无状态协议的过渡是协议维护者认为应对企业部署扩展挑战所必需的基础性变更。然而，新版本引入的破坏性变更并非预期常态。为便于未来版本实现向后兼容更新，维护者在协议规范中新增了治理增强功能（包括特性生命周期策略、扩展框架和符合性套件要求）。这些增强功能旨在支持协议演进而不破坏核心功能。

升级过程是可选的，直到您和客户端都采取行动前，一切保持不变。AgentCore 网关通过单一配置字段声明其支持的协议版本。客户端在每次请求时选择版本。例如，将 2026-07-28 添加到同时声明支持 2025-11-25 的网关上，请求旧版本的客户端不会发生任何变化。只有请求 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方法。最终效果是单个工具调用完全自包含，不需要任何先前的会话上下文，也可以路由到任意服务器实例。移除协议会话并不会妨碍对有状态应用的支持。当服务器需要跨调用保持连续性时，可以通过将显式ID作为工具参数传递，遵循HTTP请求的既定模式，该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}}

之后您可以使用代理自身的功能，将这个状态句柄贯穿到后续请求中：

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网关一直保护代理免受MCP会话机制的大部分影响。它将您的AWS Lambda函数、API和MCP服务器聚合到单一MCP端点后方，并代表您管理与每个目标的协议对话。自2026-07-28起，双方都变得更简单：代理的首次工具调用是一个自包含的请求，而不是先握手再调用。每个请求都携带Mcp-Protocol-Version头部。当版本出现在supportedVersions中时，网关会以该版本处理请求；如果未出现，则会以HTTP 400（代码-32022）拒绝请求并列出支持的版本。省略头部的请求默认使用2025-03-26版本。

2. 不解析正文的路由、缓存和追踪

在协议的早期版本中，请求执行的操作对客户端和服务器之间的任何中间组件都是不透明的。负载均衡器、API网关和速率限制器都必须解析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 已经在实践中采用的机制提供了标准化定义。现在，源自您应用程序的分布式跟踪可以完整贯穿整个调用链路，从代理到 MCP 客户端、网关再到下游服务，并在任何兼容 OpenTelemetry 的收集器中呈现为统一的跨度树结构。

在 2026-07-28 的实现路径中，AgentCore 网关直接暴露了这些底层能力。网关返回的每个工具结果都携带新的结构化响应包，可缓存的结果会包含 TTL 和作用域提示信息供符合规范的客户端 SDK 使用。网关还强制执行自定义请求头绑定规则：当工具的输入模式将某个字段标记为请求头绑定时，网关会拒绝任何缺少对应请求头或请求头内容与请求体矛盾的请求（HTTP 400，代码 -32020）。

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

无状态协议仍需要一种机制让服务器在调用过程中向客户端发送消息。MCP 提供了三种这样的交互方式：1）elicitation（引导），服务器向终端用户请求输入（例如："该工具即将删除三个文件，确认？"）；2）roots（根目录），服务器请求文件系统中可用的目录和文件；3）sampling（采样），服务器要求客户端模型生成响应。在早期版本中，实现这些交互需要服务器保持 SSE 流与客户端的连接。

在最新协议版本中，服务器主动发起的请求仅允许在服务器正在处理客户端请求时进行（SEP-2260）。用户看到的每个提示都可追溯到用户或其代理发起的某个操作。多跳交互请求（SEP-2322）取代了之前的长连接流。在此机制中，服务器将问题嵌入 InputRequiredResult，通过不透明的 requestState 令牌传递状态信息，而非通过 SSE 推送问题。只有声明了 elicitation 或 sampling 输入的工具才会触发多跳交互，且仅当客户端声明支持该功能时才会触发。

{
  "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="
  }
}

另外，进度通知和日志传输现在是请求作用域的。网关仅在客户端在原始请求中提供进度令牌时才会传递进度更新，仅在客户端在每请求元数据中设置 io.modelcontextprotocol/logLevel 时才会传输日志消息。

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

此前，MCP 扩展是一个没有治理机制的非正式概念。SEP-2133 引入了新的治理机制。每个扩展都携带一个反向 DNS ID，通过客户端和服务器能力中的扩展映射进行协商，存放在由委派维护者管理的专用仓库中，并遵循独立于核心规范的自有发布节奏。SEP 流程中新增的“扩展跟踪”机制定义了扩展如何从实验状态升级为正式状态，这改变了协议的演进方式。现在，新想法无需争夺核心规范中的空间或强制触发重大版本升级，能力可以按照自己的时间线作为可选扩展逐步成熟。未协商特定扩展的客户端和服务器不受影响。

5. 授权加固

六个 SEP 让 MCP 的授权规范更贴近生产环境中的 OAuth 2.0 和 OpenID Connect 部署。无论您的网关使用的是 IAM（SigV4）还是 OAuth/JWT 入站授权，协议版本的升级都不会改变这些授权方式。出站凭证提供者也是如此。升级协议版本无需更改凭证或授权器配置。

6. 错误处理与弃用

在早期协议版本中，几乎所有内容（包括传输层故障）都以 HTTP 200 返回，错误信息隐藏在 JSON-RPC 正文内部。2026-07-28 版本后，传输层和应用层被清晰分离。传输层故障现在返回真实的 HTTP 状态码，应用层结果仍保留在正文中：

| 情况 | 2025-* 版本 | 2026-07-28 | |------|-------------|------------| | 未知方法 | 正文中的 JSON-RPC 错误<br>`HTTP 200 | HTTP 404 | | 不支持的协议版本 | 各不相同 | HTTP 400<br>代码 -32022<br>正文列出支持的版本 | | 头部绑定字段缺失或不匹配 | -32020 | | | 缺少必需的客户端能力 | 不适用 | 代码 -32021` |

这些变更仅影响检查错误响应的代码。它们使您的 HTTP 层监控、告警和重试逻辑能够无需解析正文即可区分路由问题和应用层问题。规范还将“资源未找到”错误码从 MCP 特有的 -32002 重新分配给 JSON-RPC 标准的 -32602 Invalid Params（SEP-2164）。如果您的客户端在任何地方匹配 -32002，请审查这些代码路径。此外，在 2026-07-28 版本中：logging/setLevel 已弃用，调用该方法的客户端将被拒绝。要启用日志传输，可以改用每请求元数据字段 io.modelcontextprotocol/logLevel。

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:

• 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.

• 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 .

• 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. 查看当前配置
aws bedrock-agentcore-control get-gateway \
    --gateway-identifier <gateway-id>

# 2. 将 2026-07-28 与现有版本一同发布
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 支持以下协议版本：2025-03-26、2025-06-18、2025-11-25 和 2026-07-28。

通过使用新请求头调用网关确认新版本已上线：

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":{}}'

成功响应表明网关已按 2026-07-28 版本处理请求。若返回代码 -32022 表示该版本尚未加入网关的 supportedVersions，响应体中会列出网关当前发布的版本。

supportedVersions 是网关发布的完整版本列表，因此回滚操作只需反向执行相同操作即可。即从列表中移除 2026-07-28。若请求使用已移除的版本，网关会返回 HTTP 400 错误码 -32022，并在响应体中列出网关当前仍支持的版本。在移除客户端正在使用的版本前，请确保已迁移的客户端具备回退能力。

版本选择机制

客户端在每次请求时选择版本，而非通过一次性握手协议。每个 MCP 请求都会在 MCP-Protocol-Version 请求头中声明所使用的版本，网关在该版本位于 supportedVersions 时会按对应版本处理请求：

• 若请求指定的版本在网关发布的版本列表中，网关将按该版本处理请求。例如在双版本网关（如 2026-07-28 和 2025-11-25）中，2026-07-28 请求将获得新功能，2025-11-25 请求将获得旧版行为。

• 若请求指定的版本不在网关发布的版本列表中，网关将返回 HTTP 400 错误码 -32022，响应体中列出网关支持的版本。

• 若请求未指定版本，网关将使用默认版本 2025-03-26。若该默认版本不在网关支持列表中，请求将被拒绝。

只要现有客户端请求的协议版本在网关的 supportedVersions 列表中，它们将继续正常工作。这为您提供了清晰的三阶段升级路径：首先将 2026-07-28 与现有版本一同发布，然后按自己的节奏迁移客户端，最后在所有客户端都切换到新版本后，再移除旧版本。

如果网关前端的 MCP 服务器目标在客户端升级前已切换到 2026-07-28 版本，网关会在不同版本间进行转换，使使用 2025-* 版本的客户端仍能调用 2026-07-28 目标上的普通工具并获得预期格式的响应，而无需升级。但目前这种转换不支持服务器向客户端发起的 elicitations 和 sampling 调用。若 2025-* 客户端调用需要 elicitations 或 sampling 的 2026-* 服务器工具，将收到错误响应。

总结

MCP 2026-07-28 是协议有史以来最大的一次修订，它被设计为最后一次破坏兼容性的修订。无状态设计为 MCP 提供了在通用 HTTP 基础设施上扩展的基础，而 MCP 扩展则为新功能提供了按自身时间表演进的空间。

通过 Amazon Bedrock AgentCore Gateway，添加对最新协议版本的支持只需一次 UpdateGateway 调用。要开始使用，请查看 AgentCore Gateway 文档，查阅 MCP 2026-07-28 规范及其变更日志，并尝试今天在网关上启用新版本。如果您对规范本身有任何反馈，欢迎在 MCP 规范仓库中提交问题。关于 AgentCore Gateway 的问题，请通过 AWS re:Post 或常规 AWS 支持渠道联系。

## 关于作者

'"`