Ventajas del uso de sesiones Habilite las sesiones en su puerta de enlace Ciclo de vida de la sesión Identidad del usuario y alcance de la sesión Tiempo de espera y caducidad de la sesión Gestión de errores Ejemplos de código

Utilice las sesiones de MCP con su AgentCore puerta de enlace

Las sesiones MCP permiten interacciones con estado entre los clientes y su puerta de enlace. AgentCore Cuando las sesiones están habilitadas, la puerta de enlace genera un identificador de sesión único durante la inicialización y mantiene el estado en varias solicitudes, lo que permite utilizar funciones MCP avanzadas, como la obtención y el muestreo.

Ventajas del uso de sesiones

Interacciones estáticas entre el servidor MCP y el objetivo: La puerta de enlace almacena el ID de sesión del servidor MCP objetivo y lo reutiliza en las siguientes llamadas a la herramienta. Esto evita la reinicialización en cada solicitud y permite a los objetivos mantener el contexto en todas las llamadas.
Respuestas más rápidas con AgentCore objetivos de tiempo de ejecución: Cuando se reutiliza la sesión de destino, AgentCore Runtime no necesita iniciar en frío una nueva conexión de servidor MCP en cada solicitud, lo que se traduce en tiempos de respuesta más rápidos.
Habilita funciones MCP avanzadas: Las sesiones son un requisito previo para la obtención y el muestreo, que requieren el seguimiento del estado de varias solicitudes.
User-scoped seguridad (pasarelas autenticadas): En el caso de las pasarelas con autenticación entrante, las sesiones están vinculadas a la identidad del usuario verificada, lo que evita el secuestro de la sesión.

Habilite las sesiones en su puerta de enlace

Para habilitar las sesiones, especifique una sessionConfiguration en el protocolConfiguration.mcp campo al crear o actualizar la puerta de enlace.


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

El parámetro sessionTimeoutInSeconds es opcional. Si se omite, el tiempo de espera predeterminado es de 3600 segundos (1 hora). El rango válido es de 900 (15 minutos) a 28800 (8 horas). El tiempo de espera es absoluto y se calcula a partir de la primera initialize solicitud.

Para habilitar también las funciones que dependen de las sesiones, como la obtención y el muestreo, también debes habilitar la transmisión de respuestas:


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

nota

Cuando las sesiones están habilitadas en una puerta de enlace, no puede incluirlas Mcp-Session-Id en la configuración metadataConfiguration de propagación del encabezado del destino de una puerta de enlace. La puerta de enlace administra los ID de sesión internamente. Si se intenta hacerlo, se produce un error de solicitud incorrecta del HTTP 400.

Ciclo de vida de la sesión

El ciclo de vida de la sesión sigue el flujo de inicialización del protocolo MCP:

El cliente envía una initialize solicitud a la puerta de enlace.
La puerta de enlace crea una sesión, almacena los metadatos de la sesión y devuelve un elemento único Mcp-Session-Id en el encabezado de la respuesta.
El cliente incluye el Mcp-Session-Id encabezado en todas las solicitudes posteriores.
La pasarela valida la existencia de la sesión, la caducidad y la identidad del usuario (en el caso de las pasarelas autenticadas) en cada solicitud.
Cuando se agota el tiempo de espera de la sesión o el cliente se desconecta, la sesión caduca.

En la primera llamada de herramienta a un servidor MCP de destino dentro de una sesión, la puerta de enlace inicializa una conexión con el destino y almacena el identificador de sesión del objetivo. Las siguientes llamadas a una herramienta al mismo destino reutilizan este ID de sesión almacenado, lo que evita la inicialización repetida.

Identidad del usuario y alcance de la sesión

El ámbito de las sesiones se basa en la identidad del usuario autenticado para evitar el secuestro de la sesión. La puerta de enlace obtiene la identidad del usuario de forma diferente según el método de autenticación entrante configurado en la puerta de enlace:

Método de autenticación	Identificador de usuario	Comportamiento
OAuth/ OIDC	`sub`afirmación del token JWT	Alcance completo. Solo el usuario que creó la sesión puede utilizarla. La `sub` reclamación es obligatoria según la especificación de la OIDC, es única a nivel local dentro del emisor, distingue mayúsculas de minúsculas y nunca se reasigna.
AWS IAM (SiGv4)	ARN de la entidad principal	Alcance completo. Solo el director de IAM que creó la sesión puede utilizarla. El ARN principal es único en todo el mundo e inmutable durante toda AWS la vida útil de la entidad de IAM. Ejemplo: `arn:aws:iam::123456789012:user/john-doe`
Sin autenticación	Ninguno	Sin ámbito de usuario. Las sesiones están disponibles pero no están vinculadas a ninguna identidad. Cualquier persona con el ID de sesión puede interactuar con la sesión.

importante

En el caso de las puertas de enlace sin autenticación entrante, las sesiones conllevan un riesgo de secuestro de la sesión, tal como se describe en las consideraciones de seguridad de la especificación MCP. Si se filtra o adivina un identificador de sesión, otra parte puede reanudar la sesión. Utilice las sesiones no autenticadas solo para el desarrollo y las pruebas, no para las cargas de trabajo de producción que manejan datos confidenciales.

En el caso de las puertas de enlace autenticadas, si un usuario diferente intenta utilizar un ID de sesión existente, la puerta de enlace devuelve el HTTP 404 Not Found (la sesión es invisible para los demás usuarios).

Tiempo de espera y caducidad de la sesión

El tiempo de espera de la sesión se calcula a partir de la primera solicitud. initialize Una vez transcurrido el tiempo de espera, la sesión caduca y no se puede utilizar.

Tiempo de espera predeterminado: 3600 segundos (1 hora)
Rango configurable: de 900 segundos (15 minutos) a 28800 segundos (8 horas)

Si la sesión de un servidor MCP de destino caduca antes de que se agote el tiempo de espera de la sesión de la puerta de enlace, la puerta de enlace se reinicializa de forma transparente con el destino y actualiza el ID de sesión de destino almacenado. La sesión de puerta de enlace permanece activa.

Gestión de errores

Escenario	Estado HTTP	Description (Descripción)
Falta el `Mcp-Session-Id` encabezado en una puerta de enlace con sesión habilitada	400: solicitud maligna	Todas las solicitudes posteriores `initialize` deben incluir el encabezado de la sesión.
ID de sesión no válido o caducado	404 Not Found (No encontrado)	La sesión no existe o se ha agotado el tiempo de espera.
Un usuario diferente intenta usar la sesión de otro usuario (pasarelas autenticadas)	404 Not Found (No encontrado)	La sesión es invisible para otros usuarios.
`Mcp-Session-Id`en Target `metadataConfiguration` cuando las sesiones están habilitadas	400: solicitud maligna	Se devuelve al plano de control al crear o actualizar un objetivo.

Ejemplos de código

ejemplo

curl

Enviar una initialize solicitud para iniciar una sesión:


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 respuesta incluye el Mcp-Session-Id encabezado:


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

Incluya el ID de sesión en las solicitudes posteriores:


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)

Aviso JavaScript está desactivado o no está disponible en su navegador.

Para utilizar la documentación de AWS, debe estar habilitado JavaScript. Para obtener más información, consulte las páginas de ayuda de su navegador.

Convenciones del documento

Temas avanzados

Transmisión de respuestas