Vantaggi dell'utilizzo delle sessioni Abilita le sessioni sul tuo gateway Ciclo di vita della sessione Identità dell'utente e ambito della sessione Timeout e scadenza della sessione Gestione degli errori Esempi di codice

Usa le sessioni MCP con il tuo gateway AgentCore

Le sessioni MCP consentono interazioni statiche 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 su più richieste, abilitando funzionalità MCP avanzate come l'elicitazione e il campionamento.

Vantaggi dell'utilizzo delle sessioni

Interazioni con destinazione del server MCP con stato: Il gateway memorizza l'ID di sessione del server MCP target e lo riutilizza nelle successive chiamate allo strumento. Ciò evita la reinizializzazione su ogni richiesta e consente ai target di mantenere il contesto tra le chiamate.
Risposte più rapide con gli obiettivi Runtime AgentCore: Quando la sessione del target viene riutilizzata, AgentCore Runtime non ha bisogno di avviare a freddo una nuova connessione al server MCP su ogni richiesta, con conseguenti tempi di risposta più rapidi.
Abilita funzionalità MCP avanzate: Le sessioni sono un prerequisito per l'elicitazione e il campionamento, che richiedono il monitoraggio dello stato su più richieste.
User-scoped sicurezza (gateway autenticati): Per i gateway con autenticazione in entrata, le sessioni sono associate all'identità utente verificata, impedendo il dirottamento della sessione.

Abilita le sessioni sul tuo gateway

Per abilitare le sessioni, specifica a 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 le funzionalità che dipendono da 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 includerle Mcp-Session-Id nelle impostazioni metadataConfiguration di propagazione dell'header di un gateway target. Il gateway gestisce gli ID di sessione internamente. 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:

Il client invia una initialize richiesta al gateway.
Il gateway crea una sessione, memorizza i metadati della sessione e restituisce un valore univoco Mcp-Session-Id nell'intestazione della risposta.
Il client include l'Mcp-Session-Idintestazione in tutte le richieste successive.
Il gateway convalida l'esistenza, la scadenza e l'identità dell'utente (per i gateway autenticati) su ogni richiesta.
Quando la sessione scade o il client si disconnette, la sessione scade.

Alla prima chiamata dello 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 verso la stessa destinazione 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 dal token JWT	Ambito completo. Solo l'utente che ha creato la sessione può utilizzarla. L'attestazione è `sub` richiesta dalla specifica OIDC, è localmente univoca all'interno dell'emittente, fa distinzione tra maiuscole e minuscole e non viene mai riassegnata.
AWS IAM (SIGv4)	ARN principale	Ambito completo. Solo il responsabile IAM che ha creato la sessione può utilizzarla. L'ARN principale è unico a livello globale e immutabile per tutta AWS la durata dell'entità IAM. Ad esempio: `arn:aws:iam::123456789012:user/john-doe`
Nessuna autenticazione	Nessuno	Nessun ambito utente. Le sessioni sono disponibili ma non sono vincolate 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. 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 i 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 destinazione di un server MCP scade o viene persa prima del timeout della sessione del gateway (ad esempio, se il target si riavvia), le successive chiamate allo strumento a tale destinazione restituiscono un errore del client (4xx), ad esempio. session not found Per ripristinarlo, reinizializza la connessione MCP al gateway inviando una nuova initialize richiesta per avviare una nuova sessione del gateway. Ciò stabilisce una nuova sessione di destinazione e le successive chiamate allo strumento utilizzano l'ID della sessione di destinazione aggiornato.

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 utente 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 sul piano di controllo durante la creazione o l'aggiornamento di un obiettivo.

Esempi di codice

Esempio

curl

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-Idintestazione:


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

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

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)

Avvertimento JavaScript è disabilitato o non è disponibile nel tuo browser.

Per usare la documentazione AWS, JavaScript deve essere abilitato. Consulta le pagine della guida del browser per le istruzioni.

Convenzioni dei documenti

Argomenti avanzati

Streaming delle risposte