View a markdown version of this page

MCP 协议合约 - Amazon Bedrock AgentCore
协议实施要求容器要求路径要求错误处理OAuth 身份验证响应
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

MCP 协议合约

了解实现模型上下文协议 (MCP) 的要求，以便代理可以调用工具和代理服务器。

有关示例代码，请参见在 AgentCore 运行时在 AgentCore 运行时部署 MCP 服务器部署 MCP 服务器。

协议实施要求

您的 MCP 服务器必须实现以下特定协议要求：

  • 运 Streamable-http 输：需要运输。默认情况下，使用无状态模式 (stateless_http=True) 以兼容 Amazon的会话管理和负载平衡。

  • 会话管理：平台自动为会话隔离添加Mcp-Session-Id标头。在无状态模式下，服务器必须支持无状态操作，以免拒绝平台生成的Mcp-Session-Id标头。

提示

Amazon Bedrock AgentCore 还支持有状态 MCP 服务器 (stateless_http=False)，这些服务器支持激发（多回合用户互动）和采样（内容）等功能。LLM-generated 对于 MCP 协议版本2025-11-25及更早版本，需要使用状态模式进行激发和采样，因为服务器通过开放会话传送这些请求。对于版本2026-07-28及更高版本，提取和采样使用多往返请求 (MRTR) 模式，该模式不需要状态模式。有关 MRTR 的更多信息，请参阅模型上下文协议文档中的多往返请求。

状态模式在 MCP 会话中通过多个请求传递状态。无状态 MCP 服务器将状态保存在您的应用程序管理的后备存储区，例如数据库。它使用显式状态句柄来引用该状态。服务器在工具结果中返回状态标识符，客户端在以后的工具调用中将其传递回存储区。有关显式状态句柄的更多信息，请参阅模型上下文协议文档中的显式状态句柄。有关有状态 MCP 服务器的更多信息，请参阅有状态 MCP 服务器功能。

MCP 会话管理和 microVM 粘性

模型上下文协议 (MCP) 使用标Mcp-Session-Id头来管理会话状态和路由请求。有关 MCP 规范，请参阅 MCP Streamable HTTP 传输。

微虚拟机粘性：亚马逊基岩 AgentCore 使用Mcp-Session-Id标头将请求路由到同一个微虚拟机实例。客户端必须捕获响应中Mcp-Session-Id返回的内容并将其包含在所有后续请求中，以确保会话关联性。如果没有一致的会话 ID，每个请求都可能会路由到新的 microVM，这可能会由于冷启动而导致额外的延迟。

无状态 MCP (stateless_http=True)：

  • 平台生成Mcp-Session-Id并将其包含在向您的 MCP 服务器发出的请求中。

  • 您的 MCP 服务器必须接受平台提供的会话 ID（请勿拒绝）。

  • 平台在响应中Mcp-Session-Id将相同的内容返回给客户端。

  • 客户端必须在所有后续的 microVM 关联性请求中包含此会话 ID。

有状态 MCP ()stateless_http=False:

  • 客户端发送不带Mcp-Session-Id标头的初始化请求。

  • 平台在响应Mcp-Session-Id中返回。

  • 客户端必须将其包含Mcp-Session-Id在所有后续的会话状态和 microVM 关联性请求中。

有关有状态 MCP 会话管理的更多详细信息，请参阅 MCP 会话管理规范。

注意

在这两种模式下，Amazon Bedrock AgentCore 始终会向客户返回Mcp-Session-Id标题。请务必捕获并重复使用此标头以获得最佳性能。

容器要求

您的 MCP 服务器必须部署为符合以下规格的容器化应用程序：

  • 主机：0.0.0.0

  • 端口：8000-用于 MCP 服务器通信的标准端口（与 HTTP 协议不同）

  • 平台：ARM64 容器-与 Amazon Amazon Bedrock AgentCore 运行时环境兼容所必需的

路径要求

/mcp-POST

目的

接收 MCP RPC 消息并通过代理的工具功能进行处理，使用标准 MCP RPC 消息完成 InvokeAgentRuntime API 负载的传递

响应格式

JSON-RPC 基于 request/response 格式，支持application/json和text/event-stream作为响应内容类型

使用案例

该/mcp端点有几个关键用途：

  • 工具调用和管理

  • 代理能力发现

  • 资源访问和操作

  • Multi-step 代理工作流程

错误处理

MCP 服务器将错误作为标准 JSON-RPC 2.0 错误响应返回。按照 MCP 规范的要求，大多数错误都以 HTTP 200 状态码传送到 JSON-RPC error对象中。只有身份验证、授权和协议级请求错误才使用非 200 个 HTTP 状态码。下表将每个运行时异常映射到其 JSON-RPC 错误代码、HTTP 状态代码和消息。一些异常共享 JSON-RPC 错误代码，但返回不同的消息，因此它们被列为单独的行。

JSON-RPC 错误码 运行时异常 HTTP 错误代码 错误消息

-32001

UnauthorizedException

401

身份验证错误-凭据无效

-32002

AccessDeniedException

403

授权错误-权限不足

-32003

ThrottlingException

200

已超过速率限制-请求过多

-32003

ServiceQuotaExceededException

200

已超过速率限制-请求过多

-32004

ResourceNotFoundException

200

未找到资源-请求的资源不存在

-32005

ConflictException

200

资源冲突-资源已经存在

-32005

RetryableConflictException

200

会话操作正在进行中，请重试

-32006

ValidationException

200

验证错误-请求数据无效

-32010

RuntimeClientError

200

工具执行错误-请查看您的 CloudWatch 日志以获取更多信息

-32011

McpRequestUnacceptableException

406

接受标头错误-MCP 协议需要接受标头: application/json, text/event-stream

-32603

任何其他例外

200

内部错误-服务器错误

ConflictException并且RetryableConflictException都使用 JSON-RPC 错误代码-32005（HTTP 200），但可以通过其消息来区分。当第二个操作以会话为目标时，服务正在配置或关闭该会话时，该服务返回 RetryableConflictException (Session operation in progress, please retry)。由于 MCP 返回 HTTP 200，且 JSON-RPC 正文中有错误，因此调用者必须检查响应正文并使用短暂的指数退避重试 — MCP 客户端不会自动重试。

错误响应示例：

{
  "jsonrpc": "2.0",
  "id": "req-001",
  "error": {
    "code": -32005,
    "message": "Session operation in progress, please retry"
  }
}

OAuth 身份验证响应

OAuth-configured 代理遵循 RFC 6749 (OAuth 2.0) 身份验证标准。缺少身份验证时，该服务会返回带有 WWW-Authenticate 标头的 401 未经授权的响应（根据 RFC 7235），使客户端能够通过 API 发现授权服务器端点。 GetRuntimeProtectedResourceMetadata

401 未经授权

当授权标头缺失或为空时返回。

响应包括 WWW-Authenticate 标题：

WWW-Authenticate: Bearer resource_metadata="https://bedrock-agentcore.{region}.amazonaws.com/runtimes/{ESCAPED_ARN}/invocations/.well-known/oauth-protected-resource?qualifier={QUALIFIER}"
注意

SigV4-configured 代理返回 HTTP 403 ACCESS_DENIED 时出现错误，并且不包含WWW-Authenticate标头。