View a markdown version of this page

MCP 通訊協定合約 - Amazon Bedrock AgentCore
通訊協定實作要求容器需求路徑需求錯誤處理OAuth 身分驗證回應

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

MCP 通訊協定合約

了解實作模型內容通訊協定 (MCP) 的要求，以便客服人員可以呼叫工具和客服人員伺服器。

如需範例程式碼，請參閱在 AgentCore 執行期中部署 MCP 伺服器。

通訊協定實作要求

您的 MCP 伺服器必須實作這些特定的通訊協定需求：

  • Transport ：需要 Streamable-http 傳輸。根據預設，使用無狀態模式 stateless_http=True () 與 AWS工作階段管理和負載平衡的相容性。

  • 工作階段管理：平台會自動新增工作階段隔離的Mcp-Session-Id標頭。在無狀態模式下，伺服器必須支援無狀態操作，以免拒絕平台產生的Mcp-Session-Id標頭。

提示

Amazon Bedrock AgentCore 也支援具狀態的 MCP 伺服器 stateless_http=False ()，其可啟用引出 （多迴轉使用者互動） 和取樣 (LLM 產生的內容） 等功能。對於 MCP 通訊協定版本 2025-11-25和更早版本，引出和取樣需要有狀態模式，因為伺服器透過開啟的工作階段傳遞這些請求。對於 版本 2026-07-28 和更新版本，引出和取樣使用多往返請求 (MRTR) 模式，這不需要有狀態模式。如需 MRTR 的詳細資訊，請參閱模型內容通訊協定文件中的多重往返請求。

狀態模式會在多個請求的 MCP 工作階段中攜帶狀態。無狀態 MCP 伺服器會將狀態保留在您的應用程式管理的備份存放區中，例如資料庫。它使用明確狀態控點來參考該狀態。伺服器會在工具結果中傳回狀態識別符，而用戶端會在稍後工具呼叫金鑰時將其傳回至存放區。如需明確狀態控點的詳細資訊，請參閱模型內容通訊協定文件中的明確狀態控點。如需具狀態 MCP 伺服器的詳細資訊，請參閱具狀態 MCP 伺服器功能。

MCP 工作階段管理和 microVM 黏性

模型內容通訊協定 (MCP) 使用 Mcp-Session-Id標頭來管理工作階段狀態和路由請求。如需 MCP 規格，請參閱 MCP 可串流 HTTP 傳輸。

MicroVM Stickiness：Amazon Bedrock AgentCore 使用 Mcp-Session-Id標頭將請求路由到相同的 microVM 執行個體。用戶端必須擷取回應中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中傳回 。

  • 用戶端必須在工作階段狀態和 microVM 親和性的所有後續請求Mcp-Session-Id中包含此項目。

如需具狀態 MCP 工作階段管理的詳細資訊，請參閱 MCP 工作階段管理規格。

注意

在這兩種模式下，Amazon Bedrock AgentCore 一律會傳回 Mcp-Session-Id標頭給用戶端。一律擷取和重複使用此標頭，以獲得最佳效能。

容器需求

您的 MCP 伺服器必須部署為符合下列規格的容器化應用程式：

  • 主機 ： 0.0.0.0

  • 連接埠：8000- MCP 伺服器通訊的標準連接埠 （與 HTTP 通訊協定不同）

  • 平台 ：ARM64 容器 - 與 Amazon Bedrock AgentCore AWS 執行期環境相容時需要

路徑需求

/mcp - POST

用途

接收 MCP RPC 訊息，並透過客服人員的工具功能進行處理，透過標準 MCP RPC 訊息完成傳遞 InvokeAgentRuntime API 承載

回應格式

以 JSON-RPC 為基礎的請求/回應格式，支援 application/json和 text/event-stream作為回應內容類型

使用案例

/mcp 端點有幾個主要用途：

  • 工具調用和管理

  • 代理程式功能探索

  • 資源存取和操作

  • 多步驟代理程式工作流程

錯誤處理

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 設定的代理程式遵循 RFC 6749 (OAuth 2.0) 身分驗證標準。缺少身分驗證時，服務會傳回具有 WWW-Authenticate 標頭的 401 未授權回應 （根據 RFC 7235)，讓用戶端能夠透過 GetRuntimeProtectedResourceMetadata API 探索授權伺服器端點。

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標頭。