# Usa le sessioni MCP con il tuo gateway AgentCore
Le sessioni MCP consentono interazioni basate sullo stato tra i client e il gateway. AgentCore Quando le sessioni sono abilitate, il gateway genera un identificatore di sessione univoco durante l'inizializzazione e mantiene lo stato tra più richieste, abilitando funzionalità MCP avanzate come elicitazione e campionamento.
## Vantaggi dell'utilizzo delle sessioni
**Interazioni mirate con il server Stateful MCP**
Il gateway memorizza l'ID di sessione del server MCP di destinazione e lo riutilizza nelle successive chiamate allo strumento. Ciò evita la reinizializzazione a ogni richiesta e consente ai target di mantenere il contesto tra le chiamate.
**Risposte più rapide con obiettivi Runtime AgentCore **
Quando la sessione della destinazione viene riutilizzata, AgentCore Runtime non deve avviare a freddo una nuova connessione al server MCP per ogni richiesta, con tempi di risposta più rapidi.
**Abilita funzionalità MCP avanzate**
Le sessioni sono un prerequisito per l'[elicitazione](gateway-mcp-elicitation.md) e il [campionamento](gateway-mcp-sampling.md), che richiedono il tracciamento dello stato su più richieste.
**User-scoped sicurezza (gateway autenticati)**
Per i gateway con autenticazione in entrata, le sessioni sono legate all'identità dell'utente verificata, impedendo così il dirottamento della sessione.
## Abilita le sessioni sul tuo gateway
Per abilitare le sessioni, specifica un `sessionConfiguration` nel `protocolConfiguration.mcp` campo durante la creazione o l'aggiornamento del gateway.
```
{
"protocolConfiguration": {
"mcp": {
"sessionConfiguration": {
"sessionTimeoutInSeconds": 3600
}
}
}
}
```
Il parametro `sessionTimeoutInSeconds` è facoltativo. Se omesso, il timeout predefinito è di 3600 secondi (1 ora). L'intervallo valido è compreso tra 900 (15 minuti) e 28800 (8 ore). Il timeout è assoluto, calcolato a partire dalla prima `initialize` richiesta.
Per abilitare anche funzionalità che dipendono dalle sessioni come l'elicitazione e il campionamento, devi abilitare anche lo streaming delle risposte:
```
{
"protocolConfiguration": {
"mcp": {
"sessionConfiguration": {
"sessionTimeoutInSeconds": 3600
},
"streamingConfiguration": {
"enableResponseStreaming": true
}
}
}
}
```
**Nota**
Quando le sessioni sono abilitate su un gateway, non è possibile includere `Mcp-Session-Id` nelle impostazioni di propagazione `metadataConfiguration` dell'intestazione di un target gateway. Il gateway gestisce internamente gli ID di sessione. Il tentativo di eseguire questa operazione restituisce un errore HTTP 400 Bad Request.
## Ciclo di vita della sessione
Il ciclo di vita della sessione segue il flusso di inizializzazione del protocollo MCP:
1. Il client invia una `initialize` richiesta al gateway.
1. Il gateway crea una sessione, archivia i metadati della sessione e ne restituisce uno univoco `Mcp-Session-Id` nell'intestazione della risposta.
1. Il client include l'`Mcp-Session-Id`intestazione in tutte le richieste successive.
1. Il gateway convalida l'esistenza, la scadenza e l'identità dell'utente (per i gateway autenticati) su ogni richiesta.
1. Quando la sessione scade o il client si disconnette, la sessione scade.
Alla prima chiamata allo strumento a una destinazione del server MCP all'interno di una sessione, il gateway inizializza una connessione con la destinazione e memorizza l'ID di sessione della destinazione. Le successive chiamate allo strumento allo stesso target riutilizzano questo ID di sessione memorizzato, evitando ripetute inizializzazioni.
## Identità dell'utente e ambito della sessione
Le sessioni sono limitate all'identità dell'utente autenticato per impedire il dirottamento della sessione. Il gateway ricava l'identità dell'utente in modo diverso a seconda del metodo di autenticazione in entrata configurato sul gateway:
| Metodo di autenticazione | Identificatore utente | Comportamento |
| --- | --- | --- |
| OAuth /OIDC | `sub`reclamo derivante dal token JWT | Completamente mirato. Solo l'utente che ha creato la sessione può utilizzarla. La `sub` dichiarazione è richiesta dalla specifica OIDC, è localmente unica all'interno dell'emittente, fa distinzione tra maiuscole e minuscole e non è mai riassegnata. |
| AWS IAM (SigV4) | ARN principale | Ambito completo. Solo il principale IAM che ha creato la sessione può utilizzarla. L'ARN principale è unico a livello globale AWS, immutabile per tutta la durata dell'entità IAM. Ad esempio: `arn:aws:iam::123456789012:user/john-doe` |
| Nessuna autenticazione | Nessuno | **Nessun ambito di applicazione degli utenti.** Le sessioni sono disponibili ma non sono legate ad alcuna identità. Chiunque disponga dell'ID di sessione può interagire con la sessione. |
**Importante**
Per i gateway senza autenticazione in entrata, le sessioni comportano un **rischio di dirottamento della sessione**, come descritto nelle considerazioni sulla sicurezza della specifica [MCP](https://modelcontextprotocol.io/specification/2025-11-25/client/elicitation#security-considerations). Se un ID di sessione viene divulgato o indovinato, un'altra parte può riprendere la sessione. Utilizza sessioni non autenticate solo per lo sviluppo e il test, non per carichi di lavoro di produzione che gestiscono dati sensibili.
Per i gateway autenticati, se un altro utente tenta di utilizzare un ID di sessione esistente, il gateway restituisce HTTP 404 Not Found: la sessione è invisibile agli altri utenti.
## Timeout e scadenza della sessione
Il timeout della sessione viene calcolato a partire dalla prima richiesta. `initialize` Dopo il periodo di timeout, la sessione scade e non può essere utilizzata.
+ **Timeout predefinito**: 3600 secondi (1 ora)
+ **Intervallo configurabile**: da 900 secondi (15 minuti) a 28800 secondi (8 ore)
Se la sessione di un server MCP di destinazione scade prima del timeout della sessione gateway, il gateway si reinizializza in modo trasparente con la destinazione e aggiorna l'ID di sessione di destinazione memorizzato. La sessione gateway rimane attiva.
## Gestione degli errori
| Scenario | Stato HTTP | Description |
| --- | --- | --- |
| `Mcp-Session-Id`Intestazione mancante su un gateway abilitato alla sessione | 400 Richiesta non valida | Tutte le richieste successive `initialize` devono includere l'intestazione della sessione. |
| ID di sessione non valido o scaduto | 404 Not Found (404 Non trovato) | La sessione non esiste o è scaduta. |
| Tentativi diversi di utilizzare la sessione di un altro utente (gateway autenticati) | 404 Not Found (404 Non trovato) | La sessione è invisibile agli altri utenti. |
| `Mcp-Session-Id`in target `metadataConfiguration` quando le sessioni sono abilitate | 400 Richiesta non valida | Restituito al piano di controllo durante la creazione o l'aggiornamento di un target. |
## Esempi di codice
**Example**
1. Invia una `initialize` richiesta per iniziare una sessione:
```
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"
}
}
}'
```
La risposta include l'`Mcp-Session-Id`intestazione:
```
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. Includi l'ID della sessione nelle richieste successive:
```
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)
```