通过 Streamable HTTP 提供服务

阅读约需 97分钟 分钟,9节中含6个示例。

版次 2026.11.14 示例于 2026年11月19日 通过 70个示例中有70个通过 变化内容

AI 翻译。由人工以英文核验。 我们如何制作图书

译自英文版图书,版次 2026.11.14。 阅读原文

读完本章,你将能够通过 Streamable HTTP 提供商店的 Model Context Protocol 服务器,读懂每个请求和响应所携带的内容,从耗时较长的调用中以流的方式返回进度并取消该调用,将服务器作为多个副本运行在同一个地址之后而不使用粘性会话,并拒绝浏览器被诱骗发出的请求。本章内容适用于规范的 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 将服务器示例作为独立进程启动在空闲的回环端口上,发送带有所固定修订版要求的请求头的手写请求,并加载先前示例定义的服务器对象。
  • 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

最近一次修改见于版次 2026.11.14

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.

serve-on-loopback.py Python 3.12.15 · cryptography 50.0.2 · httpx2 2.16.2 · jsonschema 4.26.0 · mcp 2.3.0 · mcp-types 2.3.0 · pydantic 2.14.3 · starlette 1.10.0 · uvicorn 0.54.0 通过
"""Serves chapter 3's five tools over Streamable HTTP in a process of its own, then calls one from a client that has onlythe endpoint's URL. The point rests on the protocol revision and O-1873 status lines: the client settles on the pinnedrevision and gets the order's status back."""import asyncioimport sysfrom urllib.parse import urlsplitfrom mcp import Clientfrom lib import http_mcp, loopback, shop_api, shop_toolsserver = shop_tools.create_server(version="0.6.0")      # chapter 3's tools, unchangedasync def main() -> None:    with loopback.serve(shop_api.create_app()) as api_url:        with http_mcp.launch(__file__, env=shop_api.server_env(api_url)) as url:   # runs this file again with --serve, as its own process            async with Client(url) as client:                                # no handshake: the client needs only the URL                print("endpoint host:", urlsplit(url).hostname)                print("endpoint path:", urlsplit(url).path)                print("protocol revision:", client.protocol_version)                print("server:", client.server_info.name, client.server_info.version)                print("tools:", len((await client.list_tools()).tools))                result = await client.call_tool("get_order_status", {"order_id": "O-1873"})                print("O-1873 status:", result.structured_content["status"])if "--serve" in sys.argv:    server.run(transport="streamable-http", port=http_mcp.port())   # 127.0.0.1, path /mcpelse:    asyncio.run(main())
输出python serve-on-loopback.py
endpoint 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.

这部分尚未翻译,因此以英文显示。

Read one HTTP exchange

最近一次修改见于版次 2026.11.11

The client in Move the server from stdio to HTTP hid all of this, but when a call fails behind a proxy or a gateway, the exchange is what you read, so it pays to know what a correct one looks like. At the pinned revision, every POST carries headers that copy parts of its body. MCP-Protocol-Version repeats the version, Mcp-Method the JSON-RPC method, and Mcp-Name the tool, prompt or resource for tools/call, prompts/get and resources/read. The copies exist so that load balancers, gateways and monitoring can route and inspect a request without parsing its body, as the specification's Streamable HTTP transport explains.

The body stays the source of truth. A server MUST reject a request whose headers disagree with its body, with 400 Bad Request and the JSON-RPC error -32020, HeaderMismatch. That rule is what makes the headers safe to route on. A gateway that sends Mcp-Name: check_stock to the stock replicas can trust that the body names check_stock too, because a server would refuse the request otherwise.

Recording one get_order_status call with the SDK's client shows a correct exchange. Two requests the SDK's client never sends, through lib.http_mcp.post, show what the server refuses: a tools/call whose Mcp-Name says check_stock while its body names get_order_status, and a GET.

trace-an-http-exchange.py Python 3.12.15 · cryptography 50.0.2 · httpx2 2.16.2 · jsonschema 4.26.0 · mcp 2.3.0 · mcp-types 2.3.0 · pydantic 2.14.3 · starlette 1.10.0 · uvicorn 0.54.0 通过
"""Records the HTTP exchanges behind one tool call, then sends two requests the SDK's client never would. The point restson the request headers and response status lines of the tool call, and on the mismatched and GET lines, which show whatthe server refuses."""import asyncioimport osimport httpx2from mcp import Clientfrom lib import http_mcp, loopback, shop_api, wireSHOWN = ("content-type", "accept", "mcp-protocol-version", "mcp-method", "mcp-name")async def main() -> None:    server = http_mcp.load_server("serve-on-loopback.py")        # chapter 3's five tools    app = wire.record_http(server.streamable_http_app(), log="http.jsonl")   # logs each exchange as the app saw it    with loopback.serve(shop_api.create_app()) as api_url, loopback.serve(app) as base_url:        os.environ.update(shop_api.server_env(api_url))           # the server runs in this process, so it reads the API address here        async with Client(base_url + "/mcp") as client:            await client.call_tool("get_order_status", {"order_id": "O-1873"})        exchanges = wire.read_http_trace("http.jsonl")        # the recorder keeps header names in lower case        print("POSTs:", ", ".join(e["request_headers"]["mcp-method"] for e in exchanges))        call = next(e for e in exchanges if e["request_headers"]["mcp-method"] == "tools/call")        for name in SHOWN:            print(f"request {name}:", call["request_headers"][name])        print("request _meta keys:", ", ".join(call["request"]["params"]["_meta"]))        print("response status:", call["status"])        print("response content-type:", call["response_headers"]["content-type"])        print("response mcp-session-id:", call["response_headers"].get("mcp-session-id", "none"))        # the body names get_order_status, so this Mcp-Name header disagrees with it        wrong = http_mcp.post(base_url + "/mcp", "tools/call", {"name": "get_order_status",                              "arguments": {"order_id": "O-1873"}}, headers={"Mcp-Name": "check_stock"})        print("mismatched Mcp-Name status:", wrong.status_code)        print("mismatched Mcp-Name error:", wrong.json()["error"]["code"], wrong.json()["error"]["message"])        # a GET marked with the pinned revision, which the app refuses rather than serving its 2025 stream        stream = httpx2.get(base_url + "/mcp", headers={"MCP-Protocol-Version": http_mcp.VERSION})        print("GET status:", stream.status_code)        print("GET allow:", stream.headers["allow"])asyncio.run(main())
输出python trace-an-http-exchange.py
POSTs: 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

The client made three POSTs for that one call: server/discover, tools/call, tools/list. The first asks the server what it supports, since there is no handshake. The last is the SDK's client fetching the tool list after the call, so that it can check the structured result against the tool's output schema (mcp/client/session.py, validate_tool_result). The tools/call POST carried:

  • MCP-Protocol-Version: 2026-07-28
  • Mcp-Method: tools/call
  • Mcp-Name: get_order_status
  • Accept: application/json, text/event-stream, because the client must take either form of response

Its body's _meta held the same three keys that it holds over stdio: io.modelcontextprotocol/protocolVersion, io.modelcontextprotocol/clientInfo, io.modelcontextprotocol/clientCapabilities. The response came back 200 as application/json, and it set no session header (mcp-session-id: none).

The response was plain JSON because the tool sent nothing before its result. The SDK doesn't commit to an event stream until the handler sends a notification or 15 seconds pass, so a handler that finishes silently inside that window gets a JSON response (mcp/server/_streamable_http_modern.py). That 15-second limit belongs to a detail of that private module and may change between releases.

The server refused the mismatched request before the tool ran, with 400 and error -32020 mcp-name header does not match the request body's 'name' parameter. The SDK's own client recovers from -32020 by fetching the tool list again and resending once, because at the pinned revision a tool can mark parameters with x-mcp-header, which clients copy into Mcp-Param-{Name} headers, and a stale listing gets those headers wrong (mcp/client/client.py, call_tool).

The GET was refused too: 405, with Allow: POST. A server that supports only the pinned revision SHOULD answer GET and DELETE with 405 Method Not Allowed, because that revision has no stream a client opens with GET (the transport specification). The SDK's app also serves the 2025 revisions, and sends a GET without the pinned version in MCP-Protocol-Version to its 2025 handler, which serves it and refuses only a GET marked with the pinned revision, as this one was (mcp/server/streamable_http_manager.py).

Working rule: When an HTTP call fails, read the exchange first: the three routing headers, _meta in the body, the status and the content type. Route in a gateway on Mcp-Method and Mcp-Name if you need to, and never rewrite a body without rewriting its headers to match, because the server will refuse the pair with -32020. On a server that supports only the pinned revision, a 405 means an older client is opening a GET stream; the SDK's app serves those clients instead.

这部分尚未翻译,因此以英文显示。

Stream progress on a long call

最近一次修改见于版次 2026.11.14

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.

progress-on-stock-recount.py Python 3.12.15 · cryptography 50.0.2 · httpx2 2.16.2 · jsonschema 4.26.0 · mcp 2.3.0 · mcp-types 2.3.0 · pydantic 2.14.3 · starlette 1.10.0 · uvicorn 0.54.0 通过
"""Runs recount_stock with progress reports, once with the SDK's streaming responses and once with JSON-only responses. Thepoint rests on the content-type and progress report lines: a JSON-only server drops every report, though the recount stillcounts the same units."""import asyncioimport osfrom mcp import Clientfrom mcp.server.mcpserver import Context, MCPServerfrom mcp.types import ToolAnnotationsfrom lib import loopback, recount, shop_api, wireserver = MCPServer("shop-support", version="0.6.0")@server.tool(title="Recount stock", annotations=ToolAnnotations(read_only_hint=False, idempotent_hint=True))async def recount_stock(ctx: Context) -> recount.Recount:    """Recount every product's stock in both warehouses. Slow: reports progress per product."""    units = 0    async with recount.api() as api:        for n, sku in enumerate(recount.SKUS, 1):                       # counts from 1, so the last report is the total            units += await recount.one(api, sku)                        # lib.recount has the API take 0.02 seconds per product unless told otherwise            await ctx.report_progress(n, total=len(recount.SKUS), message=f"recounted {sku}")    return recount.Recount(skus=len(recount.SKUS), units=units)async def run(mode: str, json_response: bool) -> None:    # json_response=True sends every response as one JSON object, with no stream for reports to travel on    app = wire.record_http(server.streamable_http_app(json_response=json_response), log=f"{mode}.jsonl")    reports = []    async def on_progress(progress: float, total: float | None, message: str | None) -> None:        reports.append((progress, total, message))    with loopback.serve(app) as base_url:        async with Client(base_url + "/mcp") as client:            result = await client.call_tool("recount_stock", progress_callback=on_progress)    call = next(e for e in wire.read_http_trace(f"{mode}.jsonl") if e["request"]["method"] == "tools/call")    print(f"{mode} content-type:", call["response_headers"]["content-type"].split(";")[0])    print(f"{mode} progress reports:", len(reports))    print(f"{mode} last report:", "{:g} of {:g}, {}".format(*reports[-1]) if reports else "none")    print(f"{mode} units counted:", result.structured_content["units"])async def main() -> None:    with loopback.serve(shop_api.create_app()) as api_url:        os.environ.update(shop_api.server_env(api_url))          # the servers run in this process        await run("sse", json_response=False)        await run("json", json_response=True)asyncio.run(main())
输出python progress-on-stock-recount.py
sse 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.

取消客户端不再需要的调用

最近一次修改见于版次 2026.11.11

在长时间调用中推送进度一节中的重新盘点之所以能运行到结束,是因为客户端一直在等待它。但在很多情况下,宿主会在中途不再需要结果:用户关闭了工单,或者宿主自己的期限已过。此后仍在继续运行的调用会浪费商店的 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 的取消异常的形式到达。工具可以记录自己停在何处,但必须重新抛出该异常。需要等待某些操作的清理工作必须放在受屏蔽的作用域中,例如 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 记录每次运行是如何结束的,记录器则记录线路上传输的内容。

cancel-the-stock-recount.py Python 3.12.15 · anyio 4.16.0 · cryptography 50.0.2 · httpx2 2.16.2 · mcp 2.3.0 · mcp-types 2.3.0 · pydantic 2.14.3 · starlette 1.10.0 · uvicorn 0.54.0 通过
"""Cancels recount_stock after five progress reports by closing its response stream, and records where the server stopped.The `server saw` and `tools/call stream` lines are the ones the prose's point rests on: they show where the toolstopped and how the client ended the call."""import osimport anyiofrom mcp import Clientfrom mcp.server.mcpserver import Context, MCPServerfrom lib import loopback, recount, shop_api, wireserver = MCPServer("shop-support", version="0.6.0")runs: list = []                           # how a recount ended, and how many recounts it asked the API for@server.tool(title="Recount stock")async def recount_stock(ctx: Context) -> recount.Recount:    """Recount every product's stock in both warehouses. Slow: reports progress per product."""    done = units = 0    async with recount.api() as api:        try:            for asked, sku in enumerate(recount.SKUS, 1):      # counted before each request to the API                units += await recount.one(api, sku, seconds=0.1)       # 0.1 seconds per product keeps the server inside the sixth one                done += 1                await ctx.report_progress(done, total=len(recount.SKUS), message=f"recounted {sku}")        except anyio.get_cancelled_exc_class():            runs.extend([f"cancelled with {done} of {len(recount.SKUS)} recounted", asked])            raise                         # always re-raise; cleanup that awaits goes under a shielded scope    return recount.Recount(skus=done, units=units)async def main() -> None:    app = wire.record_http(server.streamable_http_app(), log="cancel.jsonl")    with loopback.serve(shop_api.create_app()) as api_url, loopback.serve(app) as base_url:        os.environ.update(shop_api.server_env(api_url))        async with Client(base_url + "/mcp") as client:            with anyio.CancelScope() as scope:                async def on_progress(progress, total, message):                    if progress >= 5:                                   # the threshold: the host cancels after the fifth report                        scope.cancel()    # the host no longer needs the answer                await client.call_tool("recount_stock", progress_callback=on_progress)            await anyio.sleep(0.5)        # give the server time to see the closed stream        print(f"server saw: {runs[0]}\nrecounts asked of the API: {runs[1]}")    exchanges = wire.read_http_trace("cancel.jsonl")    print("POSTs:", ", ".join(e["request"]["method"] for e in exchanges))    kinds = [m.get("method", "result") for m in exchanges[-1]["messages"]]   # a response has no method, so it counts as the result    print("tools/call stream:", "finished" if exchanges[-1]["complete"] else "closed by the client")    print("tools/call messages:", kinds.count("notifications/progress"), "progress,", kinds.count("result"), "result")anyio.run(main)
输出python cancel-the-stock-recount.py
server 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,重新抛出取消异常,并把任何需要等待的清理工作放在受屏蔽的作用域下。让每个长时间运行的工具都能安全重试,因为流中断会丢失该调用,客户端会再次发送它。

这部分尚未翻译,因此以英文显示。

Run replicas without sticky sessions

最近一次修改见于版次 2026.11.14

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 sealed requestState and opens it on the retry. By default MCPServer seals 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_id in 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 answered requestState in 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:

  1. each replica makes its own key;
  2. both replicas read one key from SHOP_REQUEST_STATE_KEY, through confirmations.state_security();
  3. 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.

two-replicas-one-client.py Python 3.12.15 · cryptography 50.0.2 · httpx2 2.16.2 · jsonschema 4.26.0 · mcp 2.3.0 · mcp-types 2.3.0 · pydantic 2.14.3 · starlette 1.10.0 · uvicorn 0.54.0 通过
"""Runs two replicas of chapter 5's refund server through three kinds of shared state, and replays one confirmation across them.The point rests on the retry and replay lines: each shared kind of state removes one way the second replica fails."""import asyncioimport reimport sysimport tempfilefrom mcp import Client, MCPErrorfrom lib import confirmations, http_mcp, loopback, shared_state, shop_apiSHARED_KEY = "chapter-6-test-key-not-a-secret-0123456789"             # at least 32 bytes; a deployment reads its ownYES = {"action": "accept", "content": {"release": True}}              # the support lead's answer, as on the wireasync def outcome(call) -> str:                                       # refund status, tool error or protocol error    try:        result = await call    except MCPError as error:        return f"error {error.error.code} {error.error.message}"    # keeps only the error's first sentence, which names the cause    text = result.content[0].text.split(". ")[0] if result.is_error else result.structured_content["status"]    return re.sub(r"Q-[0-9a-f]{10}", "Q-…", text)                    # quote IDs are randomasync def refund_across(label: str, env: dict) -> None:    with http_mcp.launch(__file__, env=env) as url_a, http_mcp.launch(__file__, env=env) as url_b:        async with Client(url_a, elicitation_callback=confirmations.say_yes) as on_a, \                Client(url_b, elicitation_callback=confirmations.say_yes) as on_b:            print(f"{label} reads on a and b:", ", ".join([(await c.call_tool("get_order_status", {                "order_id": "O-1873"})).structured_content["status"] for c in (on_a, on_b)]))            quoted = await on_a.call_tool("quote_refund", {"order_id": "O-2289"})       # above the policy's limit            args = {"quote_id": quoted.structured_content["quote_id"]}            # allow_input_required lets the server answer with an input request, not a result, when it needs confirmation            first = await on_a.session.call_tool("issue_refund", args, allow_input_required=True)   # asks on a            # the answer goes back with the request state the server sealed, which the retry must open            answer = dict(input_responses={"confirm": YES}, request_state=first.request_state)            print(f"{label} retry on b:", await outcome(on_b.session.call_tool("issue_refund", args, **answer)))            if shared_state.STORE_VARIABLE in env:                    # only the shared-store run sends the answer a second time                print(f"{label} replay on a:", await outcome(on_a.session.call_tool("issue_refund", args, **answer)))async def main() -> None:    with loopback.serve(shop_api.create_app()) as api_url, tempfile.TemporaryDirectory() as shared:        env = shop_api.server_env(api_url)                            # one shop API behind both replicas        keyed = {**env, confirmations.STATE_KEY_VARIABLE: SHARED_KEY}        await refund_across("own keys", env)                          # each process makes its own key        await refund_across("shared key", keyed)        await refund_across("shared store", {**keyed, shared_state.STORE_VARIABLE: f"{shared}/state.db"})if "--serve" in sys.argv:                                             # one replica: chapter 5's server, over HTTP    http_mcp.load_server("refund-asks-to-confirm.py").run(transport="streamable-http", port=http_mcp.port())else:    asyncio.run(main())
输出python two-replicas-one-client.py
own 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.

拒绝来自其他来源的请求

最近一次修改见于版次 2026.11.11

无粘性会话的多副本部署中的各个副本监听在 127.0.0.1 上,这让人觉得它是私有的,其实不然。在同一台机器上,浏览器中打开的任何网页都可以向环回端口发送请求。借助 DNS 重绑定(DNS rebinding),攻击者可以让自己的域名在页面加载之后解析到 127.0.0.1,于是浏览器会把本地服务器当作攻击者站点的一部分。规范中关于本地服务器的教程指出,绑定到 127.0.0.1“不是身份验证边界”(本地服务器安全)。

浏览器把防御手段交到了服务器手里:它代表页面发出每个请求时,都会附带该页面的 Origin。规范中的 Streamable HTTP 传输规定,服务器必须(MUST)对每个传入连接校验 Origin,当它存在但无效时必须返回 403,并且在本地运行时应当(SHOULD)绑定到 127.0.0.1。同时检查 Host 可以阻止重绑定的情形,因为此时浏览器所写的是攻击者的域名。

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,因为被测试的只是这项设置。

reject-a-foreign-origin.py Python 3.12.15 · cryptography 50.0.2 · httpx2 2.16.2 · mcp 2.3.0 · mcp-types 2.3.0 · pydantic 2.14.3 · starlette 1.10.0 · uvicorn 0.54.0 通过
"""Sends tools/list to the shop's server with foreign Origin and Host headers, first with the SDK's loopback default and thenwith host="0.0.0.0". The point rests on the foreign Origin and foreign Host lines: the default answers 403 and 421, and the0.0.0.0 app answers 200 to both."""from urllib.parse import urlsplitfrom lib import http_mcp, loopbackserver = http_mcp.load_server("serve-on-loopback.py")             # chapter 3's five toolsFOREIGN = "http://attacker.example"                                # a page in the user's browser, on another sitedef probe(label: str, url: str, headers: dict[str, str]) -> None:    response = http_mcp.post(url, "tools/list", headers=headers)    print(f"{label}:", response.status_code, response.text if response.status_code != 200 else "tools listed")def main() -> None:    with loopback.serve(server.streamable_http_app()) as base_url:             # host defaults to 127.0.0.1        # the server's own origin: loopback and the port it listens on, as a page served from it would send        url, own = base_url + "/mcp", f"http://127.0.0.1:{urlsplit(base_url).port}"        probe("no Origin", url, {})        probe("own Origin", url, {"Origin": own})        probe("foreign Origin", url, {"Origin": FOREIGN})        probe("foreign Host", url, {"Host": "fernhill.example"})         # a Host the loopback allowlist does not name    with loopback.serve(server.streamable_http_app(host="0.0.0.0")) as base_url:   # still bound to 127.0.0.1        probe("0.0.0.0 app, foreign Origin", base_url + "/mcp", {"Origin": FOREIGN})        probe("0.0.0.0 app, foreign Host", base_url + "/mcp", {"Host": "fernhill.example"})main()
输出python reject-a-foreign-origin.py
no 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

最近一次修改见于版次 2026.11.11

本节之前的各节已经把商店的服务器迁移到了 Streamable HTTP。从取消请求到副本,再到来源检查,这次迁移所需的工作就是迁移的代价。stdio 则没有这些工作。规范中的 stdio 传输由客户端将服务器作为子进程启动,并通过子进程的标准输入和标准输出交换消息。进程由宿主拥有,因此其他任何对象都无法访问它;服务器只继承宿主传给它的内容,并且在宿主需要的期间一直存活。

两种传输方式的区别在于由谁运行服务器,以及由此产生的后果:

stdio Streamable HTTP
启动者 宿主,每个宿主一个 由你启动,一次服务多个宿主
可访问者 其自身的宿主 任何能够访问该地址的对象
取消 notifications/cancelled 关闭响应流
日志 标准错误 你的服务器日志
凭据 宿主的环境 OAuth 访问令牌
扩展方式 每个宿主一个进程 负载均衡器后的多个副本

对于在单个用户的机器上为该用户工作的服务器,例如读取本地文件或使用用户自己凭据的服务器,以及在开发阶段,我们推荐使用 stdio。当多个宿主共享同一个服务器,当服务器必须运行在宿主无法访问的系统旁边(例如商店内部网络中的 API),或者当你需要把服务器作为服务来部署、扩展和监控时,我们推荐使用 Streamable HTTP。此时应当从一开始就规划授权,因为位于某个地址上的服务器需要知道调用者是谁(从资源找到授权服务器)。

宿主很多时,商店的 API 不应该能从客服团队的笔记本电脑访问,因此服务器迁移到 Streamable HTTP。本书在只需要一个宿主和一个服务器的示例中仍使用 stdio,因为子进程是运行服务器最简便的方式。

工作准则: 当服务器在用户自己的机器上为单个用户工作时,通过 stdio 交付。当服务器为多个宿主提供服务、守护宿主无法访问的系统,或者必须扩展时,通过 Streamable HTTP 交付,并在第一个外部用户出现之前为它配置来源检查和授权。同一份服务器代码可以同时支持两种方式,因此应按部署来选择,而不是按服务器来选择。

生产环境中会出什么问题

最近一次修改见于版次 2026.11.11

商店的服务器在回环地址上、一次只服务一个客户端时运行正常。放到真实的代理、负载均衡器和客户端之后,它会以回环环境从不暴露的方式出错。下面逐一列出这些问题及其表现。

每个请求都得到 421。 部署沿用了 SDK 的回环允许列表,而请求到达时 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 有各自的设置。进度条从零直接跳到完成,就是这个问题的表现。请通过真实路径测试进度,而不是在回环地址上测试。

长时间调用在整数秒处中断。 代理和负载均衡器会在固定时间后关闭空闲连接。流一旦打开,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)。请留意只有这些客户端收到带有 "Session not found" 的 404,这发生在请求落到另一个副本之后(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

最近一次修改见于版次 2026.11.11
  • 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_http stays unset until 2025-era clients need serving behind a load balancer, and then costs them cancellation.
  • json_response=True is never used, because it drops progress and cancellation.
  • recount_stock reports 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 requestState keys through SHOP_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_security lists the server's names explicitly. Authorization, not Origin, keeps out callers that aren't browsers.
  • Gateways may route on Mcp-Method and Mcp-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 from lib.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。

引用本节

格式

每种格式均引用英文原书,本译本以其为准。

每种格式都会注明该版次。其链接会打开当前版次,节标题处会说明该节文本最后一次修改的时间。访问日期和检索日期即为您打开此页的当天。

本页内容

第 6 章,共 12 章: 通过 Streamable HTTP 提供服务

  1. Move the server from stdio to HTTP
  2. Read one HTTP exchange
  3. Stream progress on a long call
  4. 取消客户端不再需要的调用
  5. Run replicas without sticky sessions
  6. 拒绝来自其他来源的请求
  7. 选择 stdio 还是 Streamable HTTP
  8. 生产环境中会出什么问题
  9. Decisions this chapter made

返回顶部全部章节