View a markdown version of this page

MCP 协议合约 - 亚马逊基岩 AgentCore
协议实施要求容器要求路径要求错误处理OAuth 身份验证响应

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

MCP 协议合约

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

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

协议实施要求

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

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

  • 会话管理：平台自动为会话隔离添加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 容器-与 AWS 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标头。