Ventajas de usar 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 de MCP permiten interacciones estables 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 de varias solicitudes, lo que permite utilizar funciones avanzadas de MCP, como la obtención y el muestreo.

Ventajas de usar sesiones

Interacciones estatales entre servidores MCP y destinos: La puerta de enlace almacena el identificador de sesión del servidor MCP de destino y lo reutiliza en las siguientes llamadas a las herramientas. Esto evita la reinicialización de 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 del objetivo, AgentCore Runtime no necesita iniciar en frío una nueva conexión al servidor MCP en cada solicitud, lo que se traduce en tiempos de respuesta más rápidos.
Habilita las funciones avanzadas de MCP: 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 se vinculan a la identidad del usuario verificada, lo que evita el secuestro de sesiones.

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 intervalo 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 se pueden incluir Mcp-Session-Id en la configuración de propagación metadataConfiguration de encabezados de un destino de puerta de enlace. La puerta de enlace administra los ID de sesión internamente. Si lo intenta, se produce un error de solicitud incorrecta de 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 identificador único Mcp-Session-Id en el encabezado de la respuesta.
El cliente incluye el Mcp-Session-Id encabezado en todas las solicitudes posteriores.
La puerta de enlace valida la existencia de la sesión, la caducidad y la identidad del usuario (en el caso de las puertas de enlace 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 destino de servidor MCP dentro de una sesión, la puerta de enlace inicializa una conexión con el destino y almacena el identificador de sesión del destino. Las llamadas subsiguientes a la 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

Las sesiones se limitan a la identidad del usuario autenticado para evitar el secuestro de sesiones. La puerta de enlace obtiene la identidad del usuario de forma diferente según el método de autenticación entrante configurado en su puerta de enlace:

Método de autenticación	Identificador de usuario	Comportamiento
OAuth/ OIDC	`sub`reclamación del token JWT	Con un alcance completo. Solo el usuario que creó la sesión puede usarla. La `sub` notificación es obligatoria según la especificación del OIDC, es única a nivel local dentro del emisor, distingue entre mayúsculas y 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 usarla. El ARN principal es único en todo el mundo y es inmutable durante toda AWS la vida de la entidad de IAM. Ejemplo: `arn:aws:iam::123456789012:user/john-doe`
Sin autenticación	Ninguno	Sin límite de usuarios. Las sesiones están disponibles pero no están vinculadas a ninguna identidad. Cualquier persona que tenga el identificador 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 un identificador de sesión o se adivina, otra persona 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 otro usuario intenta utilizar un identificador de sesión existente, la puerta de enlace devuelve el mensaje HTTP 404 Not Found, lo que significa que 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 initialize solicitud. Una vez transcurrido el tiempo de espera, la sesión caduca y no se puede utilizar.

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

Si la sesión de destino de un servidor MCP caduca o se pierde antes de que se agote el tiempo de espera de la sesión de puerta de enlace (por ejemplo, si el destino se reinicia), las siguientes llamadas a la herramienta a ese destino arrojan un error de cliente (4xx), como. session not found Para recuperarla, reinicie la conexión MCP con la puerta de enlace enviando una nueva initialize solicitud para iniciar una nueva sesión de puerta de enlace. De este modo, se establece una nueva sesión de destino y las siguientes llamadas a la herramienta utilizan el ID de sesión de destino actualizado.

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 el objetivo `metadataConfiguration` cuando las sesiones están habilitadas	400: solicitud maligna	Se devuelve en el 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 identificador 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