本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# MCP 协议合约
了解实现模型上下文协议 (MCP) 的要求，以便代理可以调用工具和代理服务器。
有关示例代码，请参见在 AgentCore 运行时[在 AgentCore 运行时部署 MCP 服务器](runtime-mcp.md)部署 MCP 服务器。
**Topics**
+ [协议实施要求](#protocol-implementation-requirements)
+ [容器要求](#container-requirements-mcp)
+ [路径要求](#path-requirements-mcp)
+ [错误处理](#mcp-error-handling)
+ [OAuth 身份验证响应](#mcp-oauth-authentication-responses)
## 协议实施要求
您的 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 的更多信息，请参阅模型上下文协议文档[中的](https://modelcontextprotocol.io/specification/2026-07-28/basic/patterns/mrtr)多往返请求。
状态模式在 MCP 会话中通过多个请求传递状态。无状态 MCP 服务器将状态保存在您的应用程序管理的后备存储区，例如数据库。它使用显式状态句柄来引用该状态。服务器在工具结果中返回状态标识符，客户端在以后的工具调用中将其传递回存储区。有关显式状态句柄的更多信息，请参阅模型上下文协议文档[中的](https://modelcontextprotocol.io/seps/2567-sessionless-mcp#explicit-state-handles)显式状态句柄。有关有状态 MCP 服务器的更多信息，请参阅[有状态 MCP 服务器功能。](mcp-stateful-features.md)
### MCP 会话管理和 microVM 粘性
模型上下文协议 (MCP) 使用标`Mcp-Session-Id`头来管理会话状态和路由请求。有关 MCP 规范，请参阅 [ MCP Streamable HTTP 传输。](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#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 会话管理规范。](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#session-management)
**注意**
在这两种模式下，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 ](https://docs.amazonaws.cn/bedrock-agentcore/latest/APIReference/API_InvokeAgentRuntime.html) 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) 身份验证标准。](https://datatracker.ietf.org/doc/html/rfc6749)缺少身份验证时，该服务会返回带有 WWW-Authenticate 标头的 401 未经授权的响应（根据 [ RFC 7235](https://datatracker.ietf.org/doc/html/rfc7235)），使客户端能够通过 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`标头。