View a markdown version of this page

AgentCore 게이트웨이에서 MCP 세션 사용 - Amazon Bedrock AgentCore

AgentCore 게이트웨이에서 MCP 세션 사용

MCP 세션은 클라이언트와 AgentCore 게이트웨이 간의 상태 저장 상호 작용을 활성화합니다. 세션이 활성화되면 게이트웨이는 초기화 중에 고유한 세션 식별자를 생성하고 여러 요청에서 상태를 유지하여 유도 및 샘플링과 같은 고급 MCP 기능을 활성화합니다.

세션 사용의 이점

상태 저장 MCP 서버 대상 상호 작용

게이트웨이는 MCP 서버 대상의 세션 ID를 저장하고 후속 도구 호출에서 재사용합니다. 이렇게 하면 모든 요청에 대한 재초기화를 방지하고 대상이 호출 간에 컨텍스트를 유지할 수 있습니다.

AgentCore 런타임 대상을 사용한 더 빠른 응답

대상의 세션이 재사용되면 AgentCore 런타임은 각 요청에서 새 MCP 서버 연결을 콜드 스타트할 필요가 없으므로 응답 시간이 빨라집니다.

고급 MCP 기능 활성화

세션은 여러 요청에서 상태를 추적해야 하는 유도샘플링을 위한 사전 조건입니다.

사용자 범위 보안(인증된 게이트웨이)

인바운드 인증이 있는 게이트웨이의 경우 세션은 확인된 사용자 자격 증명으로 바인딩되어 세션 하이재킹을 방지합니다.

게이트웨이에서 세션 활성화

세션을 활성화하려면 게이트웨이를 생성하거나 업데이트할 때 protocolConfiguration.mcp 필드에 sessionConfiguration를 지정합니다.

{ "protocolConfiguration": { "mcp": { "sessionConfiguration": { "sessionTimeoutInSeconds": 3600 } } } }

sessionTimeoutInSeconds 파라미터는 선택 항목입니다. 생략하면 기본 제한 시간은 3600초(1시간)입니다. 유효한 범위는 900(15분)~28800(8시간)입니다. 제한 시간은 첫 번째 initialize 요청에서 계산된 절대 시간입니다.

또한 유도 및 샘플링과 같은 세션에 의존하는 기능을 활성화하려면 응답 스트리밍을 추가로 활성화해야 합니다.

{ "protocolConfiguration": { "mcp": { "sessionConfiguration": { "sessionTimeoutInSeconds": 3600 }, "streamingConfiguration": { "enableResponseStreaming": true } } } }
참고

게이트웨이에서 세션이 활성화된 경우 게이트웨이 대상metadataConfiguration의 헤더 전파 설정의 Mcp-Session-Id에를 포함할 수 없습니다. 게이트웨이는 세션 IDs 내부적으로 관리합니다. 이렇게 하려고 하면 HTTP 400 잘못된 요청 오류가 반환됩니다.

세션 수명 주기

세션 수명 주기는 MCP 프로토콜의 초기화 흐름을 따릅니다.

  1. 클라이언트는 게이트웨이에 initialize 요청을 보냅니다.

  2. 게이트웨이는 세션을 생성하고, 세션 메타데이터를 저장하고, 응답 헤더Mcp-Session-Id에 고유한를 반환합니다.

  3. 클라이언트는 모든 후속 요청에 Mcp-Session-Id 헤더를 포함합니다.

  4. 게이트웨이는 각 요청에서 세션 존재, 만료 및 사용자 자격 증명(인증된 게이트웨이의 경우)을 검증합니다.

  5. 세션 시간이 초과되거나 클라이언트 연결이 끊어지면 세션이 만료됩니다.

세션 내에서 MCP 서버 대상에 대한 첫 번째 도구 호출 시 게이트웨이는 대상과의 연결을 초기화하고 대상의 세션 ID를 저장합니다. 동일한 대상에 대한 후속 도구 호출은이 저장된 세션 ID를 재사용하므로 초기화가 반복되지 않습니다.

사용자 ID 및 세션 범위 지정

세션은 세션 하이재킹을 방지하기 위해 인증된 사용자 자격 증명으로 범위가 지정됩니다. 게이트웨이는 게이트웨이에 구성된 인바운드 인증 방법에 따라 사용자 자격 증명을 다르게 도출합니다.

인증 방법 사용자 식별자 동작

OAuth/OIDC

sub JWT 토큰에서 클레임

범위가 완전히 지정되었습니다. 세션을 생성한 사용자만 세션을 사용할 수 있습니다. sub 클레임은 OIDC 사양에 필요하며 발급자 내에서 로컬로 고유하고 대/소문자를 구분하며 재할당되지 않습니다.

AWS IAM(SigV4)

보안 주체 ARN

범위가 완전히 지정되었습니다. 세션을 생성한 IAM 보안 주체만 세션을 사용할 수 있습니다. 보안 주체 ARN은 전 세계적으로 고유하며 IAM 엔 AWS터티의 수명 동안 변경할 수 없습니다. 예시: arn:aws:iam::123456789012:user/john-doe

인증 없음

없음

사용자 범위 지정이 없습니다. 세션은 사용할 수 있지만 자격 증명에 바인딩되지 않습니다. 세션 ID를 가진 사람은 누구나 세션과 상호 작용할 수 있습니다.

중요

인바운드 인증이 없는 게이트웨이의 경우 MCP 사양 보안 고려 사항에 설명된 대로 세션에는 세션 하이재킹 위험이 있습니다. 세션 ID가 유출되거나 추측되면 다른 당사자가 세션을 재개할 수 있습니다. 인증되지 않은 세션은 민감한 데이터를 처리하는 프로덕션 워크로드가 아닌 개발 및 테스트에만 사용합니다.

인증된 게이트웨이의 경우 다른 사용자가 기존 세션 ID를 사용하려고 하면 게이트웨이는 HTTP 404 찾을 수 없음 - 세션을 다른 사용자에게 보이지 않습니다.

세션 제한 시간 및 만료

세션 제한 시간은 첫 번째 initialize 요청부터 계산됩니다. 제한 시간이 지나면 세션이 만료되어 사용할 수 없습니다.

  • 기본 제한 시간: 3600초(1시간)

  • 구성 가능한 범위: 900초(15분)~28800초(8시간)

게이트웨이 세션 제한 시간 전에 MCP 서버 대상의 세션이 만료되면 게이트웨이는 대상으로 투명하게 다시 초기화되고 저장된 대상 세션 ID를 업데이트합니다. 게이트웨이 세션은 활성 상태로 유지됩니다.

오류 처리

시나리오 HTTP 상태 설명

세션이 활성화된 게이트웨이에서 Mcp-Session-Id 헤더 누락

400 잘못된 요청

이후의 모든 요청에는 세션 헤더가 포함되어야 initialize 합니다.

유효하지 않거나 만료된 세션 ID

404 Not Found(404 찾을 수 없음)

세션이 존재하지 않거나 시간 초과되었습니다.

다른 사용자가 다른 사용자의 세션을 사용하려고 시도함(인증된 게이트웨이)

404 Not Found(404 찾을 수 없음)

세션은 다른 사용자에게 보이지 않습니다.

Mcp-Session-Id 세션이 활성화된 metadataConfiguration 경우 대상의

400 잘못된 요청

대상을 생성하거나 업데이트할 때 컨트롤 플레인에 반환됩니다.

코드 샘플

curl
  1. 요청을 전송initialize하여 세션을 시작합니다.

    curl -X POST \ https://mygateway-abcdefghij.gateway.bedrock-agentcore.us-west-2.amazonaws.com/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -d '{ "jsonrpc": "2.0", "id": "init-request", "method": "initialize", "params": { "protocolVersion": "2025-06-18", "capabilities": {}, "clientInfo": { "name": "my-agent", "version": "1.0.0" } } }'

    응답에는 Mcp-Session-Id 헤더가 포함됩니다.

    HTTP/1.1 200 OK Mcp-Session-Id: session-abc123def456 Content-Type: application/json { "jsonrpc": "2.0", "id": "init-request", "result": { "protocolVersion": "2025-06-18", "capabilities": { "tools": { "listChanged": true } }, "serverInfo": { "name": "agentcore-gateway", "version": "1.0.0" } } }
  2. 후속 요청에 세션 ID를 포함합니다.

    curl -X POST \ https://mygateway-abcdefghij.gateway.bedrock-agentcore.us-west-2.amazonaws.com/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Mcp-Session-Id: session-abc123def456" \ -d '{ "jsonrpc": "2.0", "id": "call-tool-request", "method": "tools/call", "params": { "name": "searchProducts", "arguments": { "query": "wireless headphones" } } }'
Python requests package
  1. import requests import json gateway_url = "https://mygateway-abcdefghij.gateway.bedrock-agentcore.us-west-2.amazonaws.com/mcp" headers = { "Content-Type": "application/json", "Accept": "application/json", "Authorization": "Bearer YOUR_ACCESS_TOKEN" } # Step 1: Initialize and get session ID init_response = requests.post(gateway_url, headers=headers, json={ "jsonrpc": "2.0", "id": "init-request", "method": "initialize", "params": { "protocolVersion": "2025-06-18", "capabilities": {}, "clientInfo": {"name": "my-agent", "version": "1.0.0"} } }) session_id = init_response.headers["Mcp-Session-Id"] print(f"Session ID: {session_id}") # Step 2: Use session ID in subsequent requests headers["Mcp-Session-Id"] = session_id tool_response = requests.post(gateway_url, headers=headers, json={ "jsonrpc": "2.0", "id": "call-tool-request", "method": "tools/call", "params": { "name": "searchProducts", "arguments": {"query": "wireless headphones"} } }) print(json.dumps(tool_response.json(), indent=2))
MCP Client
  1. from mcp import ClientSession from mcp.client.streamable_http import streamablehttp_client import asyncio async def use_session(url, token): headers = {"Authorization": f"Bearer {token}"} async with streamablehttp_client(url=url, headers=headers) as ( read_stream, write_stream, _ ): async with ClientSession(read_stream, write_stream) as session: # Initialize - session ID is managed automatically by the MCP client init_response = await session.initialize() print(f"Initialized: {init_response}") # Subsequent calls reuse the session automatically tool_response = await session.call_tool( name="searchProducts", arguments={"query": "wireless headphones"} ) print(f"Tool response: {tool_response}") return tool_response asyncio.run(use_session( url="https://mygateway-abcdefghij.gateway.bedrock-agentcore.us-west-2.amazonaws.com/mcp", token="YOUR_ACCESS_TOKEN" ))
Strands MCP Client
  1. from mcp.client.streamable_http import streamablehttp_client from strands import Agent from strands.tools.mcp import MCPClient mcp_url = "https://mygateway-abcdefghij.gateway.bedrock-agentcore.us-west-2.amazonaws.com/mcp" access_token = "YOUR_ACCESS_TOKEN" mcp_client = MCPClient( lambda: streamablehttp_client( mcp_url, headers={"Authorization": f"Bearer {access_token}"} ) ) # Strands MCP client handles session management automatically with mcp_client: agent = Agent(tools=mcp_client.list_tools_sync()) response = agent("Search for wireless headphones") print(response)