기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

MCP 프로토콜 계약

에이전트가 도구 및 에이전트 서버를 호출할 수 있도록 모델 컨텍스트 프로토콜(MCP)을 구현하기 위한 요구 사항을 이해합니다.

예제 코드는 AgentCore 런타임에서 MCP 서버 배포를 참조하세요.

프로토콜 구현 요구 사항

MCP 서버는 다음과 같은 특정 프로토콜 요구 사항을 구현해야 합니다.

MCP 세션 관리 및 microVM 고정성

모델 컨텍스트 프로토콜(MCP)은 Mcp-Session-Id 헤더를 사용하여 세션 상태 및 라우팅 요청을 관리합니다. MCP 사양은 MCP 스트리밍 가능한 HTTP 전송을 참조하세요.

MicroVM 고정성: Amazon Bedrock AgentCore는 Mcp-Session-Id 헤더를 사용하여 요청을 동일한 microVM 인스턴스로 라우팅합니다. 클라이언트는 응답에서 Mcp-Session-Id 반환된를 캡처하고 세션 선호도를 보장하기 위해 모든 후속 요청에 포함해야 합니다. 일관된 세션 ID가 없으면 각 요청이 새 microVM으로 라우팅되어 콜드 스타트로 인한 추가 지연 시간이 발생할 수 있습니다.

상태 비저장 MCP(stateless_http=True):

상태 저장 MCP(stateless_http=False):

상태 저장 MCP 세션 관리에 대한 자세한 내용은 MCP 세션 관리 사양을 참조하세요.

컨테이너 요구 사항

MCP 서버는 다음 사양을 충족하는 컨테이너화된 애플리케이션으로 배포되어야 합니다.

경로 요구 사항

/mcp - POST

용도

MCP RPC 메시지를 수신하고 에이전트의 도구 기능을 통해 처리하고 표준 MCP RPC 메시지를 사용하여 InvokeAgentRuntime API 페이로드를 완전히 전달합니다.

응답 형식

application/json 및를 응답 콘텐츠 유형text/event-stream으로 지원하는 JSON-RPC 기반 요청/응답 형식

사용 사례

/mcp 엔드포인트는 다음과 같은 몇 가지 주요 용도로 사용됩니다.

오류 처리

MCP 서버는 오류를 표준 JSON-RPC 2.0 오류 응답으로 반환합니다. 대부분의 오류는 MCP 사양에 따라 HTTP 200 상태 코드와 함께 JSON-RPC error 객체에서 전달됩니다. 인증, 권한 부여 및 프로토콜 수준 요청 오류만 200이 아닌 HTTP 상태 코드를 사용합니다. 다음 표는 각 런타임 예외를 JSON-RPC 오류 코드, HTTP 상태 코드 및 메시지에 매핑합니다. 일부 예외는 JSON-RPC 오류 코드를 공유하지만 다른 메시지를 반환하므로 별도의 행으로 나열됩니다.

ConflictException 및 RetryableConflictException 둘 다 JSON-RPC 오류 코드-32005(HTTP 200)를 사용하지만 메시지로 구분됩니다. 서비스가 세션을 프로비저닝하거나 해제하는 동안 두 번째 작업이 세션을 대상으로 하면 서비스는 RetryableConflictException (Session operation in progress, please retry)를 반환합니다. MCP는 JSON-RPC 본문의 오류와 함께 HTTP 200을 반환하므로 호출자는 응답 본문을 검사하고 짧은 지수 백오프로 재시도해야 합니다. MCP 클라이언트는 이를 자동 재시도하지 않습니다.

오류 응답 예제:

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

OAuth 인증 응답

OAuth로 구성된 에이전트는 RFC 6749(OAuth 2.0) 인증 표준을 따릅니다. 인증이 누락된 경우 서비스는 클라이언트가 GetRuntimeProtectedResourceMetadata API를 통해 권한 부여 서버 엔드포인트를 검색할 수 있도록 (RFC 7235에 따라) WWW-Authenticate 헤더와 함께 401 무단 응답을 반환합니다.

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