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 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 e il campionamento, 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:

Il client invia una initialize richiesta al gateway.
Il gateway crea una sessione, archivia i metadati della sessione e ne restituisce uno 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 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. 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

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