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

Gunakan sesi MCP dengan gateway Anda AgentCore

Sesi MCP memungkinkan interaksi stateful antara klien dan gateway Anda. AgentCore Saat 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 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 mempertahankan konteks di seluruh panggilan.
Respons lebih cepat dengan target AgentCore Runtime: Saat sesi target digunakan kembali, AgentCore Runtime tidak perlu memulai koneksi server MCP baru pada setiap permintaan, sehingga waktu respons lebih cepat.
Mengaktifkan fitur MCP tingkat lanjut: Sesi adalah prasyarat untuk elisitasi 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 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). Batas waktu 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 di gateway, Anda tidak dapat memasukkan Mcp-Session-Id dalam metadataConfiguration pengaturan propagasi header target gateway. Gateway mengelola ID sesi secara internal. Mencoba melakukannya mengembalikan kesalahan Permintaan Buruk HTTP 400.

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 dalam semua permintaan berikutnya.
Gateway memvalidasi keberadaan sesi, kedaluwarsa, dan identitas pengguna (untuk gateway yang diautentikasi) pada setiap permintaan.
Ketika waktu sesi habis 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	Pengenal pengguna	Perilaku
OAuth/OIDC	`sub`klaim dari token JWT	Sepenuhnya tercakup. Hanya pengguna yang membuat sesi yang dapat menggunakannya. `sub`Klaim tersebut diwajibkan oleh spesifikasi OIDC, unik secara lokal di dalam penerbit, peka huruf besar/kecil, dan tidak pernah dipindahkan.
AWS IAM (SiGv4)	ARN Utama	Sepenuhnya tercakup. Hanya kepala sekolah IAM yang membuat sesi yang dapat menggunakannya. Principal ARN secara global unik di seluruh dunia AWS, tidak dapat diubah untuk masa pakai 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 tersebut.

penting

Untuk gateway tanpa otentikasi masuk, sesi membawa risiko pembajakan sesi seperti yang dijelaskan dalam pertimbangan 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.

Batas waktu sesi dan kedaluwarsa

Batas waktu 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 sebelum batas waktu sesi gateway, gateway secara transparan menginisialisasi ulang dengan target dan memperbarui ID sesi target yang disimpan. Sesi gateway tetap aktif.

Penanganan kesalahan

Skenario	Status HTTP	Deskripsi
`Mcp-Session-Id`Header tidak ada pada gateway yang mendukung sesi	400 Permintaan Buruk	Semua permintaan setelah `initialize` harus menyertakan header sesi.
ID sesi tidak valid atau kedaluwarsa	404 Tidak Ditemukan	Sesi tidak ada atau telah habis waktu.
Pengguna yang berbeda mencoba menggunakan sesi pengguna lain (gateway yang diautentikasi)	404 Tidak Ditemukan	Sesi ini tidak terlihat oleh pengguna lain.
`Mcp-Session-Id`dalam 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"
      }
    }
}'

Respons 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 respons