Benefícios do uso de sessões Habilite sessões em seu gateway Ciclo de vida da sessão Identidade do usuário e escopo da sessão Tempo limite e expiração da sessão Tratamento de erros Exemplos de código

Use sessões MCP com seu gateway AgentCore

As sessões MCP permitem interações com estado entre clientes e seu AgentCore gateway. Quando as sessões são habilitadas, o gateway gera um identificador de sessão exclusivo durante a inicialização e mantém o estado em várias solicitações, habilitando recursos avançados de MCP, como elicitação e amostragem.

Benefícios do uso de sessões

Interações de destino do servidor MCP com estado: O gateway armazena o ID da sessão de destino do servidor MCP e o reutiliza nas chamadas subsequentes da ferramenta. Isso evita a reinicialização em cada solicitação e permite que os destinos mantenham o contexto em todas as chamadas.
Respostas mais rápidas com metas AgentCore de tempo de execução: Quando a sessão do alvo é reutilizada, o AgentCore Runtime não precisa iniciar a frio uma nova conexão com o servidor MCP em cada solicitação, resultando em tempos de resposta mais rápidos.
Habilita recursos avançados de MCP: As sessões são um pré-requisito para elicitação e amostragem, que exigem o rastreamento do estado em várias solicitações.
User-scoped segurança (gateways autenticados): Para gateways com autenticação de entrada, as sessões são vinculadas à identidade verificada do usuário, evitando o sequestro da sessão.

Habilite sessões em seu gateway

Para habilitar sessões, especifique um sessionConfiguration no protocolConfiguration.mcp campo ao criar ou atualizar seu gateway.


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

O parâmetro sessionTimeoutInSeconds é opcional. Se omitido, o tempo limite padrão é de 3600 segundos (1 hora). O intervalo válido é de 900 (15 minutos) a 28800 (8 horas). O tempo limite é absoluto, calculado a partir da primeira initialize solicitação.

Para também ativar recursos que dependem de sessões, como elicitação e amostragem, você também deve ativar o streaming de respostas:


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

nota

Quando as sessões são habilitadas em um gateway, você não pode incluir Mcp-Session-Id nas configurações metadataConfiguration de propagação do cabeçalho de um destino do gateway. O gateway gerencia os IDs de sessão internamente. A tentativa de fazer isso retorna um erro HTTP 400 Bad Request.

Ciclo de vida da sessão

O ciclo de vida da sessão segue o fluxo de inicialização do protocolo MCP:

O cliente envia uma initialize solicitação para o gateway.
O gateway cria uma sessão, armazena os metadados da sessão e retorna um único Mcp-Session-Id no cabeçalho da resposta.
O cliente inclui o Mcp-Session-Id cabeçalho em todas as solicitações subsequentes.
O gateway valida a existência, a expiração e a identidade do usuário da sessão (para gateways autenticados) em cada solicitação.
Quando a sessão expira ou o cliente se desconecta, a sessão expira.

Na primeira chamada de ferramenta para um destino de servidor MCP em uma sessão, o gateway inicializa uma conexão com o destino e armazena o ID da sessão do alvo. Chamadas de ferramentas subsequentes para o mesmo destino reutilizam esse ID de sessão armazenado, evitando a inicialização repetida.

Identidade do usuário e escopo da sessão

As sessões têm como escopo a identidade do usuário autenticado para evitar o sequestro da sessão. O gateway deriva a identidade do usuário de forma diferente, dependendo do método de autenticação de entrada configurado em seu gateway:

Método de autenticação	Identificador do usuário	Comportamento
OAuth/OIDC	`sub`reivindicação do token JWT	Com escopo completo. Somente o usuário que criou a sessão pode usá-la. A `sub` reclamação é exigida pela especificação do OIDC, é localmente exclusiva dentro do emissor, diferencia maiúsculas de minúsculas e nunca é reatribuída.
AWS IAM (SigV4)	ARN da entidade principal	Com escopo completo. Somente o diretor do IAM que criou a sessão pode usá-la. O ARN principal é globalmente AWSúnico e imutável durante a vida útil da entidade IAM. Exemplo: `arn:aws:iam::123456789012:user/john-doe`
Sem autenticação	Nenhum	Sem definição do escopo do usuário. As sessões estão disponíveis, mas não estão vinculadas a nenhuma identidade. Qualquer pessoa com o ID da sessão pode interagir com a sessão.

Importante

Para gateways sem autenticação de entrada, as sessões apresentam um risco de sequestro de sessão, conforme descrito nas considerações de segurança da especificação MCP. Se uma ID de sessão vazar ou adivinhar, outra parte poderá retomar a sessão. Use sessões não autenticadas somente para desenvolvimento e teste, não para cargas de trabalho de produção que lidam com dados confidenciais.

Para gateways autenticados, se um usuário diferente tentar usar uma ID de sessão existente, o gateway retornará HTTP 404 Not Found — a sessão é invisível para outros usuários.

Tempo limite e expiração da sessão

O tempo limite da sessão é calculado a partir da primeira initialize solicitação. Após o período de tempo limite, a sessão expira e não pode ser usada.

Tempo limite padrão: 3600 segundos (1 hora)
Intervalo configurável: 900 segundos (15 minutos) a 28800 segundos (8 horas)

Se a sessão de um servidor MCP de destino expirar antes do tempo limite da sessão do gateway, o gateway será reinicializado de forma transparente com o destino e atualizará a ID da sessão de destino armazenada. A sessão do gateway permanece ativa.

Tratamento de erros

Cenário	Status HTTP	Description
`Mcp-Session-Id`Cabeçalho ausente em um gateway habilitado para sessão	400 solicitação inválida	Todas as solicitações posteriores `initialize` devem incluir o cabeçalho da sessão.
ID de sessão inválida ou expirada	404 Not Found (404 Não encontrado)	A sessão não existe ou atingiu o tempo limite.
Diferentes tentativas de usuários de usar a sessão de outro usuário (gateways autenticados)	404 Not Found (404 Não encontrado)	A sessão é invisível para outros usuários.
`Mcp-Session-Id`no alvo `metadataConfiguration` quando as sessões estão habilitadas	400 solicitação inválida	Retornado no plano de controle ao criar ou atualizar um alvo.

Exemplos de código

exemplo

curl

Envie uma initialize solicitação para iniciar uma sessão:


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

A resposta inclui o Mcp-Session-Id cabeçalho:


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

Inclua o ID da sessão nas solicitações subsequentes:


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


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


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


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)

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Tópicos avançados

Streaming de respostas