Streamable HTTP transport

عنوان اصلی: StreamableHTTP transport

هدف یادگیری: اجرای یک MCP server به‌عنوان سرویس remote HTTP با Streamable HTTP transport.

مفاهیم کلیدی: یک endpoint MCP منفرد، HTTP POST + GET، Server-Sent Events (SSE)، Accept: application/json, text/event-stream، single JSON response در مقابل SSE stream، header MCP-Protocol-Version.

Streamable HTTP جایگزین transport قدیمی «HTTP+SSE» (از spec 2024-11-05) است. server یک endpoint HTTP (مثلاً https://example.com/mcp) expose می‌کند که هم POST و هم GET را handle می‌کند. Clientها یک پیام JSON-RPC منفرد POST می‌کنند؛ server با یکی از این سه پاسخ می‌دهد: - HTTP 202 Accepted (اگر ورودی notification یا response بوده — بدون body)، یا - Content-Type: application/json با یک object response JSON-RPC، یا - Content-Type: text/event-stream که یک SSE stream باز می‌کند که در نهایت response را حمل می‌کند (و ممکن است قبلش request/notificationهای server-initiated را حمل کند).

Clientها می‌توانند یک GET مستقل هم بفرستند تا یک SSE stream ناخواسته باز کنند، طوری که server بتواند بدون POST قبلی، notification یا request server-initiated را push کند. Clientها باید MCP-Protocol-Version: 2025-06-18 را روی هر request بعد از init negotiate شده بفرستند.

مثال عملی — Python (اجرای FastMCP روی Streamable HTTP)

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("Remote")

@mcp.tool()
def add(a: int, b: int) -> int:
    return a + b

if __name__ == "__main__":
    mcp.run(transport="streamable-http")
    # serves at http://localhost:8000/mcp

مثال عملی — wire (POST اولیه)

POST /mcp HTTP/1.1
Host: example.com
Accept: application/json, text/event-stream
Content-Type: application/json
MCP-Protocol-Version: 2025-06-18

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{...}}

دیاگرام معماری (متنی): Client، JSON-RPC را به /mcp POST می‌کند. Server یکی از سه شکل پاسخ را انتخاب می‌کند (202، single JSON، یا SSE stream). Client می‌تواند هم‌چنین /mcp را با Accept: text/event-stream GET کند تا پیام‌های push‌شده توسط server را بگیرد.

اشتباهات رایج

• فراموش کردن Accept: application/json, text/event-stream — server ممکن است 406 برگرداند.
• فرستادن header اشتباه MCP-Protocol-Version. Server با 400 پاسخ می‌دهد.
• رفتار با 202 مثل error. این پاسخ موفقیت برای notification است.