Manfaat menggunakan sesi Aktifkan sesi di gateway Anda Siklus hidup sesi Identitas pengguna dan pelingkupan sesi Waktu tunggu dan kedaluwarsa sesi Penanganan kesalahan Sampel Kode

Gunakan sesi MCP dengan gateway Anda AgentCore

Sesi MCP memungkinkan interaksi stateful antara klien dan gateway Anda AgentCore . Ketika sesi diaktifkan, gateway menghasilkan pengenal sesi unik selama inisialisasi dan mempertahankan status di beberapa permintaan, memungkinkan fitur MCP tingkat lanjut seperti elicitation dan sampling.

Manfaat menggunakan sesi

Interaksi target server MCP yang bersifat stateful: Gateway menyimpan ID sesi target server MCP dan menggunakannya kembali pada panggilan alat berikutnya. Ini menghindari inisialisasi ulang pada setiap permintaan dan memungkinkan target untuk mempertahankan konteks di seluruh panggilan.
Respons yang lebih cepat dengan target AgentCore Runtime: Ketika sesi target digunakan kembali, AgentCore Runtime tidak perlu memulai koneksi server MCP baru pada setiap permintaan, menghasilkan waktu respons yang lebih cepat.
Mengaktifkan fitur MCP tingkat lanjut: Sesi merupakan prasyarat untuk elis itasi dan pengambilan sampel, yang memerlukan status pelacakan di beberapa permintaan.
User-scoped keamanan (gateway yang diautentikasi): Untuk gateway dengan otentikasi masuk, sesi terikat pada identitas pengguna yang diverifikasi, mencegah pembajakan sesi.

Aktifkan sesi di gateway Anda

Untuk mengaktifkan sesi, tentukan a sessionConfiguration di protocolConfiguration.mcp bidang saat membuat atau memperbarui gateway Anda.


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

Parameter sessionTimeoutInSeconds bersifat opsional. Jika dihilangkan, batas waktu default adalah 3600 detik (1 jam). Rentang yang valid adalah 900 (15 menit) hingga 28800 (8 jam). Waktu tunggu mutlak, dihitung dari initialize permintaan pertama.

Untuk juga mengaktifkan fitur yang bergantung pada sesi seperti elisitasi dan pengambilan sampel, Anda juga harus mengaktifkan streaming respons:


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

catatan

Saat sesi diaktifkan pada gateway, Anda tidak dapat menyer metadataConfiguration takan pengaturan propagasi header target gateway. Mcp-Session-Id Gateway mengelola ID sesi secara internal. Mencoba melakukannya mengembalikan kesalahan HTTP 400 Bad Request.

Siklus hidup sesi

Siklus hidup sesi mengikuti alur inisialisasi protokol MCP:

Klien mengirimkan initialize permintaan ke gateway.
Gateway membuat sesi, menyimpan metadata sesi, dan mengembalikan unik Mcp-Session-Id di header respons.
Klien menyertakan Mcp-Session-Id header di semua permintaan berikutnya.
Gateway memvalidasi keberadaan sesi, kedaluwarsa, dan identitas pengguna (untuk gateway yang diautentikasi) pada setiap permintaan.
Saat sesi habis waktu atau klien terputus, sesi berakhir.

Pada panggilan alat pertama ke target server MCP dalam sesi, gateway menginisialisasi koneksi dengan target dan menyimpan ID sesi target. Panggilan alat berikutnya ke target yang sama menggunakan kembali ID sesi yang disimpan ini, menghindari inisialisasi berulang.

Identitas pengguna dan pelingkupan sesi

Sesi dicakup ke identitas pengguna yang diautentikasi untuk mencegah pembajakan sesi. Gateway memperoleh identitas pengguna secara berbeda tergantung pada metode otentikasi masuk yang dikonfigurasi pada gateway Anda:

Metode otentikasi	Pengidentifikasi pengguna	Perilaku
OAuth/OIDC	`sub`klaim dari token JWT	Terbatas penuh. Hanya pengguna yang membuat sesi yang dapat menggunakannya. K `sub` laim diperlukan oleh spesifikasi OIDC, unik secara lokal di dalam penerbit, peka huruf besar/kecil, dan tidak pernah ditugaskan kembali.
AWS IAM (SIGv4)	Kepala ARN	Terbatas penuh. Hanya kepala sekolah IAM yang membuat sesi yang dapat menggunakannya. ARN Utama unik secara global AWS, tidak dapat diubah selama masa hidup entitas IAM. Contoh: `arn:aws:iam::123456789012:user/john-doe`
Tidak ada otentikasi	Tidak ada	Tidak ada pelingkupan pengguna. Sesi tersedia tetapi tidak terikat pada identitas apa pun. Siapa pun yang memiliki ID sesi dapat berinteraksi dengan sesi.

penting

Untuk gateway tanpa autentikasi masuk, sesi membawa risiko pembajakan sesi seperti yang dijelaskan dalam pertim bangan keamanan spesifikasi MCP. Jika ID sesi bocor atau ditebak, pihak lain dapat melanjutkan sesi. Gunakan sesi yang tidak diautentikasi hanya untuk pengembangan dan pengujian, bukan untuk beban kerja produksi yang menangani data sensitif.

Untuk gateway yang diautentikasi, jika pengguna lain mencoba menggunakan ID sesi yang ada, gateway mengembalikan HTTP 404 Not Found — sesi tidak terlihat oleh pengguna lain.

Waktu tunggu dan kedaluwarsa sesi

Waktu tunggu sesi dihitung dari initialize permintaan pertama. Setelah periode batas waktu, sesi berakhir dan tidak dapat digunakan.

Batas waktu default: 3600 detik (1 jam)
Rentang yang dapat dikonfigurasi: 900 detik (15 menit) hingga 28800 detik (8 jam)

Jika sesi target server MCP kedaluwarsa atau hilang sebelum sesi gateway habis (misalnya, jika target dimulai ulang), panggilan alat berikutnya ke target tersebut mengembalikan kesalahan klien (4xx), seperti. session not found Untuk memulihkan, inisialisasi ulang koneksi MCP Anda ke gateway dengan mengirimkan initialize permintaan baru untuk memulai sesi gateway baru. Ini menetapkan sesi target baru, dan panggilan alat berikutnya menggunakan ID sesi target yang diperbarui.

Penanganan kesalahan

Skenario	Status HTTP	Deskripsi
`Mcp-Session-Id`Header hilang pada gateway berkemampuan sesi	400 Permintaan Buruk	Semua permintaan setelahnya `initialize` harus menyertakan header sesi.
ID sesi tidak valid atau kedaluwarsa	404 Tidak Ditemukan	Sesi tidak ada atau telah habis waktunya.
Pengguna yang berbeda mencoba untuk menggunakan sesi pengguna lain (gateway yang diautentikasi)	404 Tidak Ditemukan	Sesi ini tidak terlihat oleh pengguna lain.
`Mcp-Session-Id`di target `metadataConfiguration` saat sesi diaktifkan	400 Permintaan Buruk	Kembali di bidang kontrol saat membuat atau memperbarui target.

Sampel Kode

contoh

curl

Kirim initialize permintaan untuk memulai sesi:


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

Tanggapan termasuk Mcp-Session-Id header:


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

Sertakan ID sesi dalam permintaan berikutnya:


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)

Awas Javascript dinonaktifkan atau tidak tersedia di browser Anda.

Untuk menggunakan Dokumentasi AWS, Javascript harus diaktifkan. Lihat halaman Bantuan browser Anda untuk petunjuk.

Konvensi Dokumen

Topik lanjutan

Streaming tanggapan