透過 Streamable HTTP 提供服務
閱讀約需 90 分鐘 分鐘,9 節 中共有 6 個範例。
讀完本章,你將能透過 Streamable HTTP 提供商店的 Model Context Protocol 伺服器、讀懂每個請求與回應所攜帶的內容、將長時間呼叫的進度以串流方式回傳並取消該呼叫、以多個副本在同一個位址後執行伺服器而不使用黏性工作階段(sticky session),並拒絕瀏覽器被誘騙送出的請求。本章所述內容適用於規格的 2026-07-28 版本,以及 Python SDK 的 2.3.0 版本,即 mcp。
在本章之前,每個主機都是以子行程的方式啟動 shop-support,也就是商店的伺服器,並透過 stdio 與它溝通,這對單一機器上的一個人來說是可行的。商店的客服團隊現在從許多主機處理工單,伺服器必須能從商店的網路內部連到商店的 API,而團隊還希望伺服器能執行一項耗時的工作:recount_stock,它會重新清點兩座倉庫中的每項商品,在真實的商店中需要數分鐘。每個主機各自一個子行程,無法共用、擴充,也無法從單一處所監看。
對於由多個主機共用的伺服器,Model Context Protocol(MCP)定義了第二種傳輸方式:Streamable HTTP。伺服器在單一 HTTP 端點上監聽,客戶端送出的每則訊息都是獨立的 POST,詳見規格的 Streamable HTTP 傳輸。MCP 的其餘部分維持不變:JSON-RPC 訊息、每個請求上的 _meta,以及相同的工具。
examples/lib/ 中有四個小型共用模組負責本章的設定,因此每個範例只呈現其核心概念:
lib.http_mcp會將伺服器範例啟動為獨立行程,使用空閒的迴路(loopback)連接埠,以所採用版本要求的標頭送出手寫的請求,並載入先前範例所定義的伺服器物件。lib.wire是讀取線路上的訊息中的追蹤列印器,本章為它新增record_http,用來包裝伺服器的 HTTP 應用程式,並記錄每次交換:標頭、本文、狀態,以及回應中的每則訊息。lib.recount存放商店的重新清點邏輯、其 SKU,以及每項商品一次的 API 呼叫。lib.shared_state將狀態保存在單一 SQLite 檔案中,供多個伺服器行程開啟,用於不使用黏性工作階段的副本執行。
多數範例在自己的行程中提供伺服器的 HTTP 應用程式,透過 lib.loopback,也就是第 1 章中在空閒迴路連接埠上執行應用程式的輔助工具,讓記錄器能看到伺服器端。第一個範例與副本範例是例外,它們如同實際部署一樣,將伺服器以獨立行程執行。所有服務都繫結至 127.0.0.1。
此部分尚未翻譯,因此以英文呈現。
Move the server from stdio to HTTP
A server on stdio has exactly one client, the host that launched it. A server on Streamable HTTP has an address, and any client that can reach that address can use it. At the pinned revision that costs the server little, because the protocol keeps no state between requests. The changelog records that the revision removed the initialize handshake and the Mcp-Session-Id header, and that each request carries its own protocol version and client capabilities in _meta. A request over HTTP is therefore self-contained, like a call to the shop's own API: one POST in, one response out.
A server answers each request in one of two forms: a single JSON object (Content-Type: application/json), or a Server-Sent Events stream (text/event-stream) that belongs to that one request. The client must accept both, as the transport specification says. The stream exists so that the server can send notifications, such as progress, before the result, which Stream progress on a long call relies on.
In the Python SDK the change is one argument. MCPServer.run(transport="streamable-http") serves the server under uvicorn, by default on 127.0.0.1, port 8000, at the path /mcp (mcp/server/mcpserver/server.py). On the client side, Client takes a URL where it took StdioServerParameters, and connects with the SDK's Streamable HTTP client (mcp/client/client.py). The shop's server keeps chapter 3's five tools unchanged, and only the last lines of its file change. The port comes from http_mcp.port(), not 8000, so it never collides with anything else.
1"""Serves chapter 3's five tools over Streamable HTTP in a process of its own, then calls one from a client that has only2the endpoint's URL. The point rests on the protocol revision and O-1873 status lines: the client settles on the pinned3revision and gets the order's status back."""4import asyncio5import sys6from urllib.parse import urlsplit78from mcp import Client910from lib import http_mcp, loopback, shop_api, shop_tools1112server = shop_tools.create_server(version="0.6.0") # chapter 3's tools, unchanged131415async def main() -> None:16 with loopback.serve(shop_api.create_app()) as api_url:17 with http_mcp.launch(__file__, env=shop_api.server_env(api_url)) as url: # runs this file again with --serve, as its own process18 async with Client(url) as client: # no handshake: the client needs only the URL19 print("endpoint host:", urlsplit(url).hostname)20 print("endpoint path:", urlsplit(url).path)21 print("protocol revision:", client.protocol_version)22 print("server:", client.server_info.name, client.server_info.version)23 print("tools:", len((await client.list_tools()).tools))24 result = await client.call_tool("get_order_status", {"order_id": "O-1873"})25 print("O-1873 status:", result.structured_content["status"])262728if "--serve" in sys.argv:29 server.run(transport="streamable-http", port=http_mcp.port()) # 127.0.0.1, path /mcp30else:31 asyncio.run(main())
python serve-on-loopback.pyendpoint host: 127.0.0.1
endpoint path: /mcp
protocol revision: 2026-07-28
server: shop-support 0.6.0
tools: 5
O-1873 status: delivered
The client reached the server at the SDK's defaults, 127.0.0.1 at /mcp.
It settled on revision 2026-07-28 and found 5 tools on shop-support 0.6.0. Order O-1873 came back delivered, as it does over stdio. The server process got the shop's API address and key in its environment, as the stdio servers did, and nothing else changed.
The SDK's streamable_http_app() also takes a stateless_http flag, At 2.3.0, the app routes each request by its MCP-Protocol-Version header, and a request at the pinned revision goes to a handler that serves one exchange and never sets Mcp-Session-Id, whatever the flag says. The flag only changes how clients on a 2025 revision are served (mcp/server/streamable_http_manager.py). The older HTTP+SSE transport, with its separate event endpoint, has been deprecated since revision 2025-03-26. Its earliest removal is three months after the specification's feature-lifecycle proposal, SEP-2596, reaches Final (deprecated features). Move from HTTP+SSE to Streamable HTTP ports a server off it.
Working rule: Serve over Streamable HTTP with MCPServer.run(transport="streamable-http") and its loopback default while you develop, and give clients the endpoint's URL. Leave stateless_http alone unless you also serve clients on a 2025 revision, where it decides whether they get sessions. Keep stdio for servers that a host launches for one user, as Choose stdio or Streamable HTTP explains.
讀懂一次 HTTP 交換
將伺服器從 stdio 移到 HTTP中的用戶端把這一切都隱藏起來了,但當呼叫在代理伺服器或閘道器後方失敗時,你要讀的正是這次交換,因此了解正確的交換長什麼樣子是值得的。在鎖定版本上,每個 POST 都帶有複製其本文部分內容的標頭。MCP-Protocol-Version重複版本,Mcp-Method重複 JSON-RPC 方法,而Mcp-Name則針對tools/call、prompts/get與resources/read重複工具、提示或資源。這些副本的用途,是讓負載平衡器、閘道器與監控系統不必解析本文就能路由並檢查請求,規格中的 Streamable HTTP transport 對此有所說明。
本文仍然是事實的依據。伺服器必須拒絕標頭與本文不一致的請求,並回應400 Bad Request與 JSON-RPC 錯誤 -32020,即HeaderMismatch。這項規則使得依據標頭進行路由是安全的。把Mcp-Name: check_stock送往庫存副本的閘道器,可以確信本文指名的也是check_stock,因為否則伺服器會拒絕該請求。
用 SDK 的用戶端記錄一次get_order_status呼叫,可以看到正確的交換。另有兩個 SDK 用戶端絕不會送出的請求,透過lib.http_mcp.post送出後,可看出伺服器拒絕什麼:一個是tools/call,其Mcp-Name寫的是check_stock,但本文指名的卻是get_order_status;另一個是 GET。
1"""Records the HTTP exchanges behind one tool call, then sends two requests the SDK's client never would. The point rests2on the request headers and response status lines of the tool call, and on the mismatched and GET lines, which show what3the server refuses."""4import asyncio5import os67import httpx28from mcp import Client910from lib import http_mcp, loopback, shop_api, wire1112SHOWN = ("content-type", "accept", "mcp-protocol-version", "mcp-method", "mcp-name")131415async def main() -> None:16 server = http_mcp.load_server("serve-on-loopback.py") # chapter 3's five tools17 app = wire.record_http(server.streamable_http_app(), log="http.jsonl") # logs each exchange as the app saw it18 with loopback.serve(shop_api.create_app()) as api_url, loopback.serve(app) as base_url:19 os.environ.update(shop_api.server_env(api_url)) # the server runs in this process, so it reads the API address here20 async with Client(base_url + "/mcp") as client:21 await client.call_tool("get_order_status", {"order_id": "O-1873"})22 exchanges = wire.read_http_trace("http.jsonl")23 # the recorder keeps header names in lower case24 print("POSTs:", ", ".join(e["request_headers"]["mcp-method"] for e in exchanges))25 call = next(e for e in exchanges if e["request_headers"]["mcp-method"] == "tools/call")26 for name in SHOWN:27 print(f"request {name}:", call["request_headers"][name])28 print("request _meta keys:", ", ".join(call["request"]["params"]["_meta"]))29 print("response status:", call["status"])30 print("response content-type:", call["response_headers"]["content-type"])31 print("response mcp-session-id:", call["response_headers"].get("mcp-session-id", "none"))3233 # the body names get_order_status, so this Mcp-Name header disagrees with it34 wrong = http_mcp.post(base_url + "/mcp", "tools/call", {"name": "get_order_status",35 "arguments": {"order_id": "O-1873"}}, headers={"Mcp-Name": "check_stock"})36 print("mismatched Mcp-Name status:", wrong.status_code)37 print("mismatched Mcp-Name error:", wrong.json()["error"]["code"], wrong.json()["error"]["message"])38 # a GET marked with the pinned revision, which the app refuses rather than serving its 2025 stream39 stream = httpx2.get(base_url + "/mcp", headers={"MCP-Protocol-Version": http_mcp.VERSION})40 print("GET status:", stream.status_code)41 print("GET allow:", stream.headers["allow"])424344asyncio.run(main())
python trace-an-http-exchange.pyPOSTs: server/discover, tools/call, tools/list
request content-type: application/json
request accept: application/json, text/event-stream
request mcp-protocol-version: 2026-07-28
request mcp-method: tools/call
request mcp-name: get_order_status
request _meta keys: io.modelcontextprotocol/protocolVersion, io.modelcontextprotocol/clientInfo, io.modelcontextprotocol/clientCapabilities
response status: 200
response content-type: application/json
response mcp-session-id: none
mismatched Mcp-Name status: 400
mismatched Mcp-Name error: -32020 mcp-name header does not match the request body's 'name' parameter
GET status: 405
GET allow: POST
用戶端為這一次呼叫發出了三個 POST:server/discover, tools/call, tools/list。第一個詢問伺服器支援什麼,因為這裡沒有交握。最後一個是 SDK 的用戶端在呼叫之後取得工具清單,以便依工具的輸出結構描述檢查結構化結果(mcp/client/session.py,validate_tool_result)。tools/call POST 帶有:
MCP-Protocol-Version: 2026-07-28Mcp-Method: tools/callMcp-Name: get_order_statusAccept: application/json, text/event-stream,因為用戶端必須接受任一種形式的回應
其本文的_meta含有與透過 stdio 時相同的三個鍵:io.modelcontextprotocol/protocolVersion, io.modelcontextprotocol/clientInfo, io.modelcontextprotocol/clientCapabilities。回應以200回來,內容類型為application/json,且沒有設定工作階段標頭(mcp-session-id:none)。
回應是純 JSON,因為工具在送出結果之前沒有送出任何內容。在處理常式送出通知或經過 15 秒之前,SDK 不會採用事件串流,因此在這段時間內靜默完成的處理常式會得到 JSON 回應(mcp/server/_streamable_http_modern.py)。這個 15 秒的限制屬於該私有模組的實作細節,可能在不同版本之間改變。
伺服器在工具執行之前就拒絕了不一致的請求,回應400與錯誤-32020 mcp-name header does not match the request body's 'name' parameter。SDK 自己的用戶端遇到 -32020 時,會重新取得工具清單並重送一次,因為在鎖定版本上,工具可以用x-mcp-header標記參數,用戶端會把這些參數複製到Mcp-Param-{Name}標頭中,而過期的清單會讓這些標頭出錯(mcp/client/client.py,call_tool)。
GET 同樣被拒絕:405,並附有Allow: POST。只支援鎖定版本的伺服器應該以405 Method Not Allowed回應 GET 與 DELETE,因為該版本沒有由用戶端以 GET 開啟的串流(傳輸規格)。SDK 的應用程式也提供 2025 版本的服務,會把MCP-Protocol-Version中沒有鎖定版本的 GET 送給其 2025 處理常式,由它提供服務,只拒絕標示為鎖定版本的 GET,就像這一個一樣(mcp/server/streamable_http_manager.py)。
**實用原則:**HTTP 呼叫失敗時,先讀這次交換:三個路由標頭、本文中的_meta、狀態碼與內容類型。如有需要,可在閘道器依Mcp-Method與Mcp-Name進行路由,而且絕不要在改寫本文時不同步改寫標頭,因為伺服器會以 -32020 拒絕這組不一致的內容。在只支援鎖定版本的伺服器上,405 表示較舊的用戶端正在開啟 GET 串流;SDK 的應用程式則會為這些用戶端提供服務。
此部分尚未翻譯,因此以英文呈現。
Stream progress on a long call
The exchange in Read one HTTP exchange returned in milliseconds. A call that takes minutes leaves the person at the host seeing nothing, and the host can't tell slow from stuck. Progress is MCP's answer to a long call: the server reports how far it has got while the call runs. A client that wants progress puts a progressToken in the request's _meta. The server MAY then send notifications/progress with that token, each carrying a progress value that MUST increase with every notification, and optionally a total and a message (progress). Over Streamable HTTP, these notifications travel only on the response stream of the request they belong to (Streamable HTTP transport).
In the SDK, a tool reports with await ctx.report_progress(progress, total=..., message=...). A client asks for reports on a call with call_tool(..., progress_callback=...), which also puts the token in _meta. When the caller didn't ask, report_progress does nothing (mcp/server/_streamable_http_modern.py, progress), so a tool can always call it.
The shop's API has an endpoint, POST /stock/{sku}/recount, which recounts one product in both warehouses and takes a few seconds per product in the real shop. recount_stock calls it for each of the shop's 64 SKUs and reports after each one. In the examples, lib.recount asks the API to take 0.02 seconds per product, so a full recount takes a few seconds. The same server runs twice: once with the SDK's default, which can stream, and once with json_response=True, which makes every response a single JSON object.
1"""Runs recount_stock with progress reports, once with the SDK's streaming responses and once with JSON-only responses. The2point rests on the content-type and progress report lines: a JSON-only server drops every report, though the recount still3counts the same units."""4import asyncio5import os67from mcp import Client8from mcp.server.mcpserver import Context, MCPServer9from mcp.types import ToolAnnotations1011from lib import loopback, recount, shop_api, wire1213server = MCPServer("shop-support", version="0.6.0")141516@server.tool(title="Recount stock", annotations=ToolAnnotations(read_only_hint=False, idempotent_hint=True))17async def recount_stock(ctx: Context) -> recount.Recount:18 """Recount every product's stock in both warehouses. Slow: reports progress per product."""19 units = 020 async with recount.api() as api:21 for n, sku in enumerate(recount.SKUS, 1): # counts from 1, so the last report is the total22 units += await recount.one(api, sku) # lib.recount has the API take 0.02 seconds per product unless told otherwise23 await ctx.report_progress(n, total=len(recount.SKUS), message=f"recounted {sku}")24 return recount.Recount(skus=len(recount.SKUS), units=units)252627async def run(mode: str, json_response: bool) -> None:28 # json_response=True sends every response as one JSON object, with no stream for reports to travel on29 app = wire.record_http(server.streamable_http_app(json_response=json_response), log=f"{mode}.jsonl")30 reports = []3132 async def on_progress(progress: float, total: float | None, message: str | None) -> None:33 reports.append((progress, total, message))3435 with loopback.serve(app) as base_url:36 async with Client(base_url + "/mcp") as client:37 result = await client.call_tool("recount_stock", progress_callback=on_progress)38 call = next(e for e in wire.read_http_trace(f"{mode}.jsonl") if e["request"]["method"] == "tools/call")39 print(f"{mode} content-type:", call["response_headers"]["content-type"].split(";")[0])40 print(f"{mode} progress reports:", len(reports))41 print(f"{mode} last report:", "{:g} of {:g}, {}".format(*reports[-1]) if reports else "none")42 print(f"{mode} units counted:", result.structured_content["units"])434445async def main() -> None:46 with loopback.serve(shop_api.create_app()) as api_url:47 os.environ.update(shop_api.server_env(api_url)) # the servers run in this process48 await run("sse", json_response=False)49 await run("json", json_response=True)505152asyncio.run(main())
python progress-on-stock-recount.pysse content-type: text/event-stream
sse progress reports: 64
sse last report: 64 of 64, recounted KG-1064
sse units counted: 6969
json content-type: application/json
json progress reports: 0
json last report: none
json units counted: 6969
With the default, the host saw the recount move. The response came back as text/event-stream, and the client received 64 reports, the last of them 64 of 64, recounted KG-1064. The first progress notification is what committed the response to an event stream, so nobody had to wait out the SDK's 15-second window. The recount counted 6969 units.
With json_response=True, the host got nothing until the end. The response was application/json, and the client received 0 reports. The recount still ran and counted 6969 units, and nothing failed. The SDK's JSON path has nowhere to send a notification, so report_progress returns without sending, and neither side logs it (mcp/server/_streamable_http_modern.py). The specification allows that, because progress is optional for the server. The person at the host would have waited the whole recount with no sign of life.
Streaming also has to survive intermediaries, since a proxy that buffers responses holds progress back until the end. The transport specification says servers SHOULD send X-Accel-Buffering: no on event streams to stop that, and the SDK sends it, with Cache-Control: no-cache, no-transform (mcp/server/_streamable_http_modern.py, _SSE_HEADERS).
Working rule: Report progress from any tool that can run longer than a few seconds, with a total when you know it and a message a person can read. Keep the SDK's default response mode. Use json_response=True only for a server whose every tool is quick, and know that it drops every progress report and every cancellation without telling anyone.
取消用戶端不再需要的呼叫
在長時間呼叫中串流進度中的重新盤點之所以執行到最後,是因為用戶端一直在等它。然而,主機端常常在中途就不再需要答案:使用者關閉了工單,或是主機自己的期限已過。呼叫在這之後仍繼續執行,會浪費商店的 API,也會一直占用工具所持有的資源。
在 Streamable HTTP 上,用戶端藉由關閉該請求的回應串流來取消請求。規範中的取消模式把關閉的串流稱為「取消訊號」,並指出伺服器 MUST 把用戶端斷線視為取消該請求,同時說明不「需要或預期」任何 notifications/cancelled 訊息。這與 stdio 不同,stdio 上用戶端仍會送出 notifications/cancelled;也與 2025 年的各修訂版不同,當時 HTTP 用戶端也會送出它。SDK 實作了這兩個部分。它的用戶端在等待中的任務被取消或讀取逾時時會中止 POST,且不會再送出其他任何內容(mcp/client/streamable_http.py)。它的伺服器則監看斷線,並取消執行處理常式的任務(mcp/server/_streamable_http_modern.py、watch_disconnect)。
在 async def 工具內,取消會在下一個 await 處以 anyio 的取消例外形式抵達。工具可以記錄自己停在哪裡,但必須重新拋出該例外。若清理工作本身需要 await 某些操作,就需要受保護(shielded)的範圍,例如 anyio.move_on_after(5, shield=True),否則取消也會連清理工作一併取消。一般的 def 工具在工作執行緒中執行,只有在呼叫 anyio.from_thread.check_cancelled() 時才會停止。從不呼叫它的工具會執行到結束,其結果則被丟棄。SDK 的取消指南與 mcp/server/_streamable_http_modern.py(watch_disconnect)描述了這兩種情況。
為了從頭到尾觀察這條路徑,主機在第五次進度回報時取消呼叫,就像主機在使用者關閉工單時會做的那樣。這裡每項產品需時 0.1 秒,因此串流關閉時,伺服器仍在第六項產品的重新盤點之中。recount_stock 記錄每次執行如何結束,而記錄器則記下線路上傳送的內容。
1"""Cancels recount_stock after five progress reports by closing its response stream, and records where the server stopped.2The `server saw` and `tools/call stream` lines are the ones the prose's point rests on: they show where the tool3stopped and how the client ended the call."""4import os56import anyio7from mcp import Client8from mcp.server.mcpserver import Context, MCPServer910from lib import loopback, recount, shop_api, wire1112server = MCPServer("shop-support", version="0.6.0")13runs: list = [] # how a recount ended, and how many recounts it asked the API for141516@server.tool(title="Recount stock")17async def recount_stock(ctx: Context) -> recount.Recount:18 """Recount every product's stock in both warehouses. Slow: reports progress per product."""19 done = units = 020 async with recount.api() as api:21 try:22 for asked, sku in enumerate(recount.SKUS, 1): # counted before each request to the API23 units += await recount.one(api, sku, seconds=0.1) # 0.1 seconds per product keeps the server inside the sixth one24 done += 125 await ctx.report_progress(done, total=len(recount.SKUS), message=f"recounted {sku}")26 except anyio.get_cancelled_exc_class():27 runs.extend([f"cancelled with {done} of {len(recount.SKUS)} recounted", asked])28 raise # always re-raise; cleanup that awaits goes under a shielded scope29 return recount.Recount(skus=done, units=units)303132async def main() -> None:33 app = wire.record_http(server.streamable_http_app(), log="cancel.jsonl")34 with loopback.serve(shop_api.create_app()) as api_url, loopback.serve(app) as base_url:35 os.environ.update(shop_api.server_env(api_url))36 async with Client(base_url + "/mcp") as client:37 with anyio.CancelScope() as scope:38 async def on_progress(progress, total, message):39 if progress >= 5: # the threshold: the host cancels after the fifth report40 scope.cancel() # the host no longer needs the answer41 await client.call_tool("recount_stock", progress_callback=on_progress)42 await anyio.sleep(0.5) # give the server time to see the closed stream43 print(f"server saw: {runs[0]}\nrecounts asked of the API: {runs[1]}")44 exchanges = wire.read_http_trace("cancel.jsonl")45 print("POSTs:", ", ".join(e["request"]["method"] for e in exchanges))46 kinds = [m.get("method", "result") for m in exchanges[-1]["messages"]] # a response has no method, so it counts as the result47 print("tools/call stream:", "finished" if exchanges[-1]["complete"] else "closed by the client")48 print("tools/call messages:", kinds.count("notifications/progress"), "progress,", kinds.count("result"), "result")495051anyio.run(main)
python cancel-the-stock-recount.pyserver saw: cancelled with 5 of 64 recounted
recounts asked of the API: 6
POSTs: server/discover, tools/call
tools/call stream: closed by the client
tools/call messages: 5 progress, 0 result
串流一關閉,工具就停止了。伺服器看到的呼叫結果是 cancelled with 5 of 64 recounted,而工具已向商店的 API 要求了 6 次重新盤點。取消在工具等待第六次時抵達,因此其餘產品從未送往 API。
線路上有兩次 POST,即 server/discover, tools/call,所以沒有任何取消訊息通過。工具呼叫的串流是 closed by the client,其中承載了 5 progress, 0 result。對於被取消的呼叫,用戶端收不到結果,伺服器也不會送出結果。
有兩件事會使這項機制失效。使用 json_response=True 時,SDK 的 JSON 路徑沒有斷線監看器,因此關閉的連線永遠不會傳到處理常式,處理常式會執行到結束(mcp/server/_streamable_http_modern.py)。另外,因任何其他原因而中斷的串流,例如被代理伺服器逾時切斷,也會以相同方式取消該請求。在固定的修訂版中串流無法續傳,所以用戶端 MUST 以新的請求 ID 重新送出請求(變更紀錄)。可能被中斷串流打斷的工具必須能安全地執行兩次,而重新盤點正是如此,因為再數一次會得到相同的數量。若重新盤點必須在用戶端離開後仍能存活,改為啟動任務而非等待會把它移入任務中。
逾時機制疊加在取消之上。取消模式指出,傳送方 SHOULD 為每個請求設定逾時,MAY 在進度到達時重設它,並 SHOULD 一律強制執行最大上限。Client(read_timeout_seconds=...) 以及 call_tool 上的同名引數提供了這個上限,時間用盡時會藉由關閉串流來取消呼叫(mcp/client/streamable_http.py)。
實用原則: 在 Streamable HTTP 上,藉由取消等待該呼叫的任務,或使用逾時來取消呼叫,並讓 SDK 關閉串流。把長時間執行的工具寫成 async def,重新拋出取消例外,並把任何需要 await 的清理放在受保護的範圍之下。讓每個執行時間長的工具都能安全重試,因為中斷的串流會遺失該呼叫,而用戶端會再送出一次。
此部分尚未翻譯,因此以英文呈現。
Run replicas without sticky sessions
Every example so far, including the cancelled recount in Cancel a call the client no longer needs, ran one server process. The support team needs more than one, so that a restart or a slow recount doesn't stop every host. A load balancer in front of two replicas sends each request wherever it likes. With 2025-era sessions, the load balancer had to use sticky sessions, which route every request carrying the same Mcp-Session-Id to the replica that held the session. The pinned revision has no sessions, so any replica can serve any request. A server that needs state across calls mints an explicit handle instead, and the client passes it back as an ordinary argument (changelog).
The protocol keeping no state doesn't mean the application keeps none. The shop's server holds three kinds of state that a second replica doesn't see:
- The key that seals
requestState. The refund confirmation from Return an input request instead of a result sends the client a sealedrequestStateand opens it on the retry. By defaultMCPServerseals with a key that each process makes when it starts, and the state also names the server's name as its audience (mcp/server/request_state.py). - The handles the tools mint. Chapter 3's quote store keeps each
quote_idin the memory of the process that made it, as What goes wrong in production in chapter 3 warned. - The record of answered confirmations.
confirmations.OnceOnly, from Keep round-trip state tamper-proof, remembers each answeredrequestStatein one process's memory.
One refund, asked for on replica a and confirmed on replica b, touches all three kinds of state. Two replicas of chapter 5's refund server, each a process on its own port with one shop API behind both, run it. lib.http_mcp.load_server loads the server that refund-asks-to-confirm.py defines, and each replica runs it over HTTP. One client connects to each replica, and both read order O-1873. Then the client on replica a quotes a refund for order O-2289, whose amount is above the policy's limit, and replica a asks for confirmation. The retry with the support lead's yes goes to replica b, as a load balancer might send it. The sequence runs three times, fixing one kind of state each time:
- each replica makes its own key;
- both replicas read one key from
SHOP_REQUEST_STATE_KEY, throughconfirmations.state_security(); - both also keep their quotes and their answered confirmations in one shared store, a SQLite file named by
SHOP_STATE_STORE, and the client then sends the same answer a second time, to replica a.
The shared store is lib.shared_state. Its SharedMap and SharedSet keep entries in a SQLite file that every process on the machine opens, and each carries a lock on a file beside it, so that one replica's check-then-write can't interleave with another's. shop_tools.create_server(quotes=...) and confirmations.OnceOnly(seen=...) take any such container, and fall back to process memory without one, so chapters 3 and 5 run as before. Rows hold JSON, not pickles, and a quote's expiry is stored as a wall-clock time, because a monotonic deadline means nothing on another host. A SQLite file reaches only processes on one machine. A deployment puts the same two tables in a database its replicas share.
1"""Runs two replicas of chapter 5's refund server through three kinds of shared state, and replays one confirmation across them.2The point rests on the retry and replay lines: each shared kind of state removes one way the second replica fails."""3import asyncio4import re5import sys6import tempfile78from mcp import Client, MCPError910from lib import confirmations, http_mcp, loopback, shared_state, shop_api1112SHARED_KEY = "chapter-6-test-key-not-a-secret-0123456789" # at least 32 bytes; a deployment reads its own13YES = {"action": "accept", "content": {"release": True}} # the support lead's answer, as on the wire141516async def outcome(call) -> str: # refund status, tool error or protocol error17 try:18 result = await call19 except MCPError as error:20 return f"error {error.error.code} {error.error.message}"21 # keeps only the error's first sentence, which names the cause22 text = result.content[0].text.split(". ")[0] if result.is_error else result.structured_content["status"]23 return re.sub(r"Q-[0-9a-f]{10}", "Q-…", text) # quote IDs are random242526async def refund_across(label: str, env: dict) -> None:27 with http_mcp.launch(__file__, env=env) as url_a, http_mcp.launch(__file__, env=env) as url_b:28 async with Client(url_a, elicitation_callback=confirmations.say_yes) as on_a, \29 Client(url_b, elicitation_callback=confirmations.say_yes) as on_b:30 print(f"{label} reads on a and b:", ", ".join([(await c.call_tool("get_order_status", {31 "order_id": "O-1873"})).structured_content["status"] for c in (on_a, on_b)]))32 quoted = await on_a.call_tool("quote_refund", {"order_id": "O-2289"}) # above the policy's limit33 args = {"quote_id": quoted.structured_content["quote_id"]}34 # allow_input_required lets the server answer with an input request, not a result, when it needs confirmation35 first = await on_a.session.call_tool("issue_refund", args, allow_input_required=True) # asks on a36 # the answer goes back with the request state the server sealed, which the retry must open37 answer = dict(input_responses={"confirm": YES}, request_state=first.request_state)38 print(f"{label} retry on b:", await outcome(on_b.session.call_tool("issue_refund", args, **answer)))39 if shared_state.STORE_VARIABLE in env: # only the shared-store run sends the answer a second time40 print(f"{label} replay on a:", await outcome(on_a.session.call_tool("issue_refund", args, **answer)))414243async def main() -> None:44 with loopback.serve(shop_api.create_app()) as api_url, tempfile.TemporaryDirectory() as shared:45 env = shop_api.server_env(api_url) # one shop API behind both replicas46 keyed = {**env, confirmations.STATE_KEY_VARIABLE: SHARED_KEY}47 await refund_across("own keys", env) # each process makes its own key48 await refund_across("shared key", keyed)49 await refund_across("shared store", {**keyed, shared_state.STORE_VARIABLE: f"{shared}/state.db"})505152if "--serve" in sys.argv: # one replica: chapter 5's server, over HTTP53 http_mcp.load_server("refund-asks-to-confirm.py").run(transport="streamable-http", port=http_mcp.port())54else:55 asyncio.run(main())
python two-replicas-one-client.pyown keys reads on a and b: delivered, delivered
own keys retry on b: error -32602 Invalid or expired requestState
shared key reads on a and b: delivered, delivered
shared key retry on b: Error executing tool issue_refund: There is no quote Q-…
shared store reads on a and b: delivered, delivered
shared store retry on b: requested
shared store replay on a: Error executing tool issue_refund: Refund R-0113 was already confirmed
With their own keys, both reads worked (delivered, delivered), but the retry failed: error -32602 Invalid or expired requestState. Replica b couldn't open a state that replica a sealed, so the SDK refused the retry before the tool ran.
With one shared key, replica b opened the state, and the call failed one step later, inside the tool: "Error executing tool issue_refund: There is no quote Q-…" The quote lived in replica a's memory. The shared key fixed the first kind of state and exposed the second.
With the shared store as well, the retry on replica b released the refund, and its status became requested. Replica b found replica a's quote in the shared store, and with it the refund the shop's API already held, so it released that refund without asking for a second one. The same answer sent again to replica a was refused: "Error executing tool issue_refund: Refund R-0113 was already confirmed" Replica a had never seen the first answer. Without the shared record, its own OnceOnly check would have passed, and it would have asked the shop's API to release the refund again. Only the API's 409 for a refund it no longer holds would have stopped it. The refund completed once, across two replicas, with no sticky sessions. The specification asks for opaque, expiring handles (tools). Where their state lives is the server's choice, but with replicas it must be somewhere every replica reaches.
A deployment that hasn't moved some state yet can use a stopgap from the routing headers in Read one HTTP exchange. It isn't stickiness: a gateway sends every request whose Mcp-Name names a tool that depends on that state to one replica, and spreads the rest. A subscriptions/listen stream is held by one replica, and the SDK ships only an in-memory bus, so events published on another replica never reach it (deploy and scale; mcp/server/subscriptions.py, InMemorySubscriptionBus).
Working rule: Run replicas with no sticky sessions, and give every replica the same server name and the same requestState keys, injected from your secret store. Before you add a second replica, list every piece of state your tools keep in memory, such as handles, once-only records and subscriptions, and move each into storage that every replica reaches. Until one is moved, route the tools that depend on it to a single replica by Mcp-Name.
拒絕來自其他來源的請求
不使用黏性工作階段來執行多個副本中的副本都監聽 127.0.0.1,這看起來像是私有的,但其實不是。同一台機器上,瀏覽器中開啟的任何網頁都可以向迴路(loopback)連接埠發送請求。透過 DNS rebinding,攻擊者的網域可以在頁面載入後被解析到 127.0.0.1,使瀏覽器把本機伺服器視為攻擊者網站的一部分。規格中關於本機伺服器的教學指出,綁定到 127.0.0.1「不是驗證邊界」(本機伺服器安全性)。
瀏覽器把防禦的依據交給了伺服器。瀏覽器代表頁面發出每個請求時,都會附上該頁面的 Origin。規格中的 Streamable HTTP transport 規定,伺服器 MUST 對每個傳入連線驗證 Origin,當它存在但無效時 MUST 回應 403,並且在本機執行時 SHOULD 綁定到 127.0.0.1。同時檢查 Host,則可以擋下 rebinding 的情形,因為此時瀏覽器所指名的是攻擊者的網域。
SDK 預設啟用這兩項檢查。當應用程式的 host 是迴路名稱,而且你沒有傳入 transport_security 時,它只允許 Host 值為 127.0.0.1:*、localhost:* 與 [::1]:*,並且只允許 Origin 值為 http:// 之下相同名稱的來源(mcp/server/mcpserver/server.py)。以下四個請求用來探測這個預設行為:對 tools/list 發送不帶 Origin 的請求、帶有伺服器自身來源的請求、帶有 http://attacker.example 的請求,以及 Host 為 fernhill.example 的請求。接著範例以 host="0.0.0.0"(容器中常見的設定)建立同一個應用程式,再次發送這兩個外部請求。該應用程式仍綁定到 127.0.0.1,因為受測的只有這項設定。
1"""Sends tools/list to the shop's server with foreign Origin and Host headers, first with the SDK's loopback default and then2with host="0.0.0.0". The point rests on the foreign Origin and foreign Host lines: the default answers 403 and 421, and the30.0.0.0 app answers 200 to both."""4from urllib.parse import urlsplit56from lib import http_mcp, loopback78server = http_mcp.load_server("serve-on-loopback.py") # chapter 3's five tools9FOREIGN = "http://attacker.example" # a page in the user's browser, on another site101112def probe(label: str, url: str, headers: dict[str, str]) -> None:13 response = http_mcp.post(url, "tools/list", headers=headers)14 print(f"{label}:", response.status_code, response.text if response.status_code != 200 else "tools listed")151617def main() -> None:18 with loopback.serve(server.streamable_http_app()) as base_url: # host defaults to 127.0.0.119 # the server's own origin: loopback and the port it listens on, as a page served from it would send20 url, own = base_url + "/mcp", f"http://127.0.0.1:{urlsplit(base_url).port}"21 probe("no Origin", url, {})22 probe("own Origin", url, {"Origin": own})23 probe("foreign Origin", url, {"Origin": FOREIGN})24 probe("foreign Host", url, {"Host": "fernhill.example"}) # a Host the loopback allowlist does not name25 with loopback.serve(server.streamable_http_app(host="0.0.0.0")) as base_url: # still bound to 127.0.0.126 probe("0.0.0.0 app, foreign Origin", base_url + "/mcp", {"Origin": FOREIGN})27 probe("0.0.0.0 app, foreign Host", base_url + "/mcp", {"Host": "fernhill.example"})282930main()
python reject-a-foreign-origin.pyno Origin: 200 tools listed
own Origin: 200 tools listed
foreign Origin: 403 Invalid Origin header
foreign Host: 421 Invalid Host header
0.0.0.0 app, foreign Origin: 200 tools listed
0.0.0.0 app, foreign Host: 200 tools listed
迴路預設值擋下了兩個外部請求。沒有 Origin 的請求得到 200 tools listed,伺服器自身的來源也是如此:200 tools listed。外部來源得到 403 Invalid Origin header,外部主機得到 421 Invalid Host header,兩者都是純文字,而不是 JSON-RPC(mcp/server/transport_security.py)。規格允許 403 搭配任一種內容。
以 host="0.0.0.0" 建立的應用程式則讓兩者都通過:200 tools listed 與 200 tools listed。SDK 不認得為迴路的主機,只會使它不啟用預設值,而在沒有傳入任何設定時,檢查是關閉的(mcp/server/transport_security.py)。這不符合規格的 MUST,而且日誌中沒有任何訊息提示這一點。
沒有 Origin 的請求顯示了這項防禦涵蓋的範圍。瀏覽器會送出 Origin,而腳本、命令列工具和其他伺服器不會,SDK 會讓沒有它的請求通過。來源驗證保護伺服器免受網頁攻擊,對於能連到該連接埠的程式則毫無作用,那正是授權的用途(以 OAuth 授權用戶端)。
實用原則: 在開發者的機器上,保留 SDK 的迴路預設值。部署在任何其他位址時,請傳入 transport_security=TransportSecuritySettings(allowed_hosts=[...], allowed_origins=[...]),列出伺服器所回應的名稱,例如 mcp.fernhill.example,切勿依賴預設值。把 Origin 驗證視為僅能防範瀏覽器的保護,並在每一個除自身主機之外還有其他對象可連上的伺服器前面加上授權。
選擇 stdio 或 Streamable HTTP
前面幾節已將商店的伺服器遷移到 Streamable HTTP。這次遷移所需的工作,從取消請求到副本,再到來源檢查,都是遷移的代價。stdio 則完全不需要這些。規格中的 stdio 傳輸由用戶端將伺服器作為子行程啟動,並透過其標準輸入與標準輸出交換訊息。行程由主機擁有,因此其他對象無法連上它,伺服器只繼承主機傳給它的內容,而且只要主機需要,它就會持續存在。
這兩種傳輸的差異在於由誰執行伺服器,以及由此產生的後果:
| stdio | Streamable HTTP | |
|---|---|---|
| 啟動者 | 主機,每個主機一個 | 由你啟動,一次服務多個主機 |
| 可連線者 | 其所屬的主機 | 任何能連到該位址的對象 |
| 取消 | notifications/cancelled |
關閉回應串流 |
| 日誌 | 標準錯誤 | 你的伺服器日誌 |
| 憑證 | 主機的環境 | OAuth 存取權杖 |
| 擴充方式 | 每個主機一個行程 | 負載平衡器後方的多個副本 |
對於替單一使用者在該使用者的機器上工作的伺服器,例如讀取本機檔案或使用該使用者自己的憑證的伺服器,以及用於開發時,我們建議使用 stdio。當多個主機共用一個伺服器、當伺服器必須與主機無法連到的系統並排執行(例如位於商店內部網路中的商店 API),或是需要將伺服器當成服務來部署、擴充與監控時,我們建議使用 Streamable HTTP。此時請從一開始就規劃授權,因為位於某個位址上的伺服器需要知道呼叫者是誰(從資源找出授權伺服器)。
由於主機眾多,商店的 API 不應讓支援團隊的筆記型電腦直接連到,因此伺服器改用 Streamable HTTP。本書對於只需要一個主機和一個伺服器的範例仍使用 stdio,因為子行程是執行它的最短途徑。
實用原則: 當伺服器替單一使用者在該使用者的機器上運作時,以 stdio 提供。當它服務多個主機、保護主機無法連到的系統,或必須擴充時,以 Streamable HTTP 提供,並在第一位外部使用者使用之前加上來源檢查與授權。同一份伺服器程式碼可以同時支援兩者,因此應依每次部署選擇,而不是依每個伺服器選擇。
正式環境中會出什麼問題
商店的伺服器在 loopback 上一次只服務一個用戶端時運作正常。放到真實的代理伺服器、負載平衡器和用戶端之後,會以 loopback 從未出現過的方式失效;以下逐項說明,並附上各自的徵兆。
每個請求都收到 421。 部署沿用了 SDK 的 loopback 允許清單,而請求抵達時,Host 帶的是伺服器的公開名稱。徵兆是每次呼叫都回傳純文字的 Invalid Host header,而工具記錄中沒有任何紀錄。請以 allowed_hosts 傳入伺服器所回應的名稱(拒絕來自其他來源的請求)。
檢查在無人決定的情況下被關閉。 以 host="0.0.0.0" 啟動的伺服器(這是容器中常見的設定)會接受所有的 Host 與 Origin(mcp/server/transport_security.py)。沒有任何失敗,所以唯一的徵兆,是像 reject-a-foreign-origin 這樣的探測得到 200。請對每個部署執行這項探測,並明確設定 transport_security。
進度一次全部抵達。 會緩衝回應的代理伺服器,會把所有通知扣住,直到結果產生才一併送出。SDK 會送出 X-Accel-Buffering: no,這是規格為此所指定的標頭,但忽略此標頭的代理伺服器與 CDN 另有各自的設定。進度條從零直接跳到完成,就是這個問題的跡象。請透過真實路徑測試進度,不要在 loopback 上測試。
長時間呼叫在整數秒時中斷。 代理伺服器與負載平衡器會在固定時間後關閉閒置的連線。串流一旦開啟,SDK 會在每 15 秒沒有其他事件時送出一則 : ping 註解,讓連線保持忙碌(mcp/server/_streamable_http_modern.py)。閒置上限更短、或對每個請求設有總時間上限的代理伺服器,仍會切斷串流,而切斷會取消工具。請留意集中在同一時間長度的取消。請調高代理伺服器對 MCP 路徑的限制,或把工作移到任務中(啟動任務而非等待)。
重試使工作執行兩次。 中斷的串流無法恢復,用戶端會以新的 ID 再次送出請求(變更記錄)。不能安全重複執行的工具,會把副作用做兩次。商店的 issue_refund 是安全的,因為一份報價只會退款一次,而且有了共用儲存區,這在每個副本上都成立。請為每個有副作用的工具提供控制代碼或金鑰,使第二次呼叫回傳第一次呼叫的結果,並把該紀錄存放在每個副本都看得到的地方。
json_response=True 會使進度與取消失效。 在不喜歡事件串流的閘道器後面,這很誘人,而 SDK 不會給出任何警告(在長時間呼叫中串流進度)。它的表現是:長時間呼叫從不回報進度,且在用戶端離開後仍持續執行。
閘道器改寫本文。 閘道器若會編輯 JSON 本文但不編輯標頭,會使請求以 -32020 失敗,即 HeaderMismatch。SDK 的用戶端會在取得工具清單後重送一次,因此你會看到成對重複的 tools/call 請求,以及伺服器回應中穩定出現的少量 -32020。
使用 2025 版修訂的用戶端需要工作階段。 同一個應用程式透過舊式交握服務 2025 年代的用戶端,預設把它們的工作階段保存在單一行程的記憶體中,這需要黏性路由(mcp/server/streamable_http_manager.py)。請留意僅來自這些用戶端、在請求落到另一個副本後出現的 404 與「Session not found」(mcp/server/streamable_http_manager.py)。若在負載平衡器後面服務這些用戶端,請設定 stateless_http=True,並了解其代價:這些用戶端會失去取消功能,所以無論用戶端做了什麼,其處理常式都會執行到結束(取消),而且也會失去由伺服器發往用戶端的請求,例如取樣與徵詢(部署與擴展)。在過渡期間同時服務舊用戶端與新用戶端會權衡這項取捨。
大型請求以 413 失敗。 SDK 預設把請求本文上限設為 4 MiB(mcp/server/transport_security.py)。以文件作為引數的工具會最先碰到這個上限。請為該伺服器調高 max_request_body_size,或改為傳遞文件的參照,而不是其位元組。
實用原則: 在商店的伺服器於某個位址開始接受流量之前,請透過真實的代理路徑測試四件事:外來的 Origin 會得到 403、呼叫執行期間進度會抵達、超過代理伺服器閒置上限的呼叫能夠存活、關閉某次呼叫的串流會使工具停止。接著依用戶端監看 421、403 與 -32020,並依時間長度監看取消。
此部分尚未翻譯,因此以英文呈現。
Decisions this chapter made
- The shop's server moves to Streamable HTTP for the support team's hosts, with chapter 3's tools unchanged. stdio stays for examples with one host and one server.
MCPServer.run(transport="streamable-http")with the SDK's defaults: loopback, path/mcp, and the default response mode, which streams.stateless_httpstays unset until 2025-era clients need serving behind a load balancer, and then costs them cancellation.json_response=Trueis never used, because it drops progress and cancellation.recount_stockreports progress after each product, with a total and a message, and is safe to run twice.- Cancellation is a closed stream. Long tools are
async def, re-raise cancellation, and shield any awaited cleanup. - Replicas share their server name and
requestStatekeys throughSHOP_REQUEST_STATE_KEY, and their quotes and answered confirmations through one shared store,SHOP_STATE_STORE. Every request, refunds included, runs on any replica. The examples' store is a SQLite file of JSON rows with wall-clock expiry; a deployment uses a database its replicas share. - Origin and Host checks stay on. On any address but loopback,
transport_securitylists the server's names explicitly. Authorization, not Origin, keeps out callers that aren't browsers. - Gateways may route on
Mcp-MethodandMcp-Name, because the server rejects a request whose headers disagree with its body. No gateway rewrites a body. - HTTP traces come from
lib.wire.record_http, and hand-written requests fromlib.http_mcp.post, only to show errors the SDK's client would never cause. - Examples run replicas as separate processes, so that each has its own memory and its own key, as in a deployment.
本章,於本版次中
版次 2026.11.14範例於 2026年11 月 19 通過測試本章 6 個範例 個範例中有 6 個通過
譯自英文書,版次 2026.11.14。