Avantages de l'utilisation des sessions Activez les sessions sur votre passerelle Cycle de vie des sessions Identité de l'utilisateur et définition de la portée de la session Expiration et expiration de la session Gestion des erreurs Exemples de code

Utilisez des sessions MCP avec votre passerelle AgentCore

Les sessions MCP permettent des interactions dynamiques entre les clients et votre AgentCore passerelle. Lorsque les sessions sont activées, la passerelle génère un identifiant de session unique lors de l'initialisation et maintient l'état de plusieurs demandes, activant ainsi des fonctionnalités MCP avancées telles que l'élicitation et l'échantillonnage.

Avantages de l'utilisation des sessions

Interactions ciblées avec le serveur MCP Stateful: La passerelle stocke l'ID de session de la cible du serveur MCP et le réutilise lors des appels d'outils suivants. Cela évite la réinitialisation à chaque demande et permet aux cibles de conserver le contexte entre les appels.
Réponses plus rapides grâce aux cibles AgentCore d'exécution: Lorsque la session de la cible est réutilisée, AgentCore Runtime n'a pas besoin de démarrer à froid une nouvelle connexion au serveur MCP à chaque demande, ce qui permet d'accélérer les temps de réponse.
Active les fonctionnalités MCP avancées: Les sessions sont une condition préalable à l'élicitation et à l'échantillonnage, qui nécessitent le suivi de l'état de plusieurs demandes.
User-scoped sécurité (passerelles authentifiées): Pour les passerelles dotées d'une authentification entrante, les sessions sont liées à l'identité utilisateur vérifiée, ce qui empêche le détournement de session.

Activez les sessions sur votre passerelle

Pour activer les sessions, spécifiez un sessionConfiguration dans le protocolConfiguration.mcp champ lors de la création ou de la mise à jour de votre passerelle.


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

Le paramètre sessionTimeoutInSeconds est facultatif. En cas d'omission, le délai d'expiration par défaut est de 3 600 secondes (1 heure). La plage valide est comprise entre 900 (15 minutes) et 28 800 (8 heures). Le délai d'attente est absolu, calculé à partir de la première initialize demande.

Pour activer également les fonctionnalités qui dépendent des sessions, telles que l'élicitation et l'échantillonnage, vous devez également activer le streaming des réponses :


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

Note

Lorsque les sessions sont activées sur une passerelle, vous ne pouvez pas inclure Mcp-Session-Id les paramètres metadataConfiguration de propagation d'en-tête d'une cible de passerelle. La passerelle gère les identifiants de session en interne. Toute tentative de ce type renvoie une erreur HTTP 400 Bad Request.

Cycle de vie des sessions

Le cycle de vie de session suit le flux d'initialisation du protocole MCP :

Le client envoie une initialize demande à la passerelle.
La passerelle crée une session, stocke les métadonnées de session et renvoie un unique Mcp-Session-Id dans l'en-tête de réponse.
Le client inclut l'Mcp-Session-Iden-tête dans toutes les demandes suivantes.
La passerelle valide l'existence, l'expiration et l'identité de l'utilisateur (pour les passerelles authentifiées) sur chaque demande.
Lorsque la session expire ou que le client se déconnecte, elle expire.

Lors du premier appel d'outil à une cible de serveur MCP au cours d'une session, la passerelle initialise une connexion avec la cible et enregistre l'ID de session de la cible. Les appels d'outils suivants à la même cible réutilisent cet ID de session enregistré, évitant ainsi des initialisations répétées.

Identité de l'utilisateur et définition de la portée de la session

Les sessions sont limitées à l'identité de l'utilisateur authentifié afin d'empêcher le détournement de session. La passerelle obtient l'identité de l'utilisateur différemment en fonction de la méthode d'authentification entrante configurée sur votre passerelle :

Méthode d’authentification	Identifiant utilisateur	Comportement
OAuth//OIDC	`sub`réclamation depuis le jeton JWT	Entièrement cadré. Seul l'utilisateur qui a créé la session peut l'utiliser. La `sub` réclamation est requise par la spécification OIDC, est unique localement au sein de l'émetteur, distingue les majuscules et minuscules et n'est jamais réattribuée.
AWS IAM (SigV4)	ARN principal	Entièrement cadré. Seul le principal IAM qui a créé la session peut l'utiliser. L'ARN principal est unique au monde et immuable pendant toute AWS la durée de vie de l'entité IAM. Exemple : `arn:aws:iam::123456789012:user/john-doe`
Pas d’authentification	Aucune	Aucune définition de la portée de l'utilisateur. Les sessions sont disponibles mais ne sont liées à aucune identité. Toute personne possédant l'identifiant de session peut interagir avec la session.

Important

Pour les passerelles sans authentification entrante, les sessions comportent un risque de détournement de session, comme décrit dans les considérations de sécurité relatives à la spécification MCP. Si un identifiant de session est divulgué ou deviné, une autre partie peut reprendre la session. Utilisez des sessions non authentifiées uniquement pour le développement et les tests, et non pour les charges de travail de production traitant des données sensibles.

Pour les passerelles authentifiées, si un autre utilisateur tente d'utiliser un identifiant de session existant, la passerelle renvoie HTTP 404 Not Found : la session est invisible pour les autres utilisateurs.

Expiration et expiration de la session

Le délai d'expiration de la session est calculé à partir de la première initialize demande. Après le délai d'expiration, la session expire et ne peut pas être utilisée.

Délai d'attente par défaut : 3 600 secondes (1 heure)
Plage configurable : 900 secondes (15 minutes) à 28 800 secondes (8 heures)

Si la session d'une cible de serveur MCP expire avant l'expiration de la session de passerelle, la passerelle se réinitialise de manière transparente avec la cible et met à jour l'ID de session cible enregistré. La session de passerelle reste active.

Gestion des erreurs

Scénario	Statut HTTP	Description
`Mcp-Session-Id`En-tête manquant sur une passerelle activée pour les sessions	400 Requête erronée	Toutes les demandes suivantes `initialize` doivent inclure l'en-tête de session.
ID de session non valide ou expiré	404 – Non trouvé	La session n'existe pas ou a expiré.
Différents utilisateurs tentent d'utiliser la session d'un autre utilisateur (passerelles authentifiées)	404 – Non trouvé	La session est invisible pour les autres utilisateurs.
`Mcp-Session-Id`dans la cible `metadataConfiguration` lorsque les sessions sont activées	400 Requête erronée	Renvoyé au plan de contrôle lors de la création ou de la mise à jour d'une cible.

Exemples de code

Exemple

curl

Envoyez une initialize demande pour démarrer une session :


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 réponse inclut l'Mcp-Session-Iden-tête :


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

Incluez l'identifiant de session dans les demandes suivantes :


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)

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

Rubriques avancées

Streaming des réponses