# 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](gateway-mcp-elicitation.md) e [amostragem](gateway-mcp-sampling.md), 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:
1. O cliente envia uma `initialize` solicitação para o gateway.
1. O gateway cria uma sessão, armazena os metadados da sessão e retorna um único `Mcp-Session-Id` no cabeçalho da resposta.
1. O cliente inclui o `Mcp-Session-Id` cabeçalho em todas as solicitações subsequentes.
1. 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.
1. 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](https://modelcontextprotocol.io/specification/2025-11-25/client/elicitation#security-considerations). 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
**Example**
1. 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"
}
}
}
```
1. 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"
}
}
}'
```
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))
```
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"
))
```
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)
```