8.3 流式 HTTP:生产级传输

8.3 流式 HTTP:生产级传输

本节摘要:流式 HTTP(Streamable HTTP)是 2025-03-26 协议引入的生产级传输,取代了旧版 SSE。它让 MCP 服务端跑成一个真正的 HTTP 服务,支持远程访问、多客户端并发、现代基础设施(负载均衡、反代)。本节讲透它的两种启动方式(mcp.run("streamable-http") 一行启动、mcp.streamable_http_app() 拿 ASGI app 嵌入),关键配置项,以及它为什么比 SSE 更好。

一、流式 HTTP 是什么

流式 HTTP 让 MCP 服务端跑成一个 HTTP 服务——监听一个端口,接受 HTTP 请求,用 HTTP 承载 MCP 消息:

客户端                                  服务端
┌──────────────┐    HTTP POST/GET     ┌──────────────┐
│   Client     │ ───────────────────► │ MCPServer    │
│              │ ◄─────────────────── │ (HTTP 服务)  │
└──────────────┘   HTTP 响应/SSE 流   └──────────────┘
                                          监听端口
​

与 stdio(子进程)不同,流式 HTTP 是个真正的网络服务——可以远程访问、可以多客户端连、可以放在负载均衡后面。这就是它「生产级」的含义。

二、两种启动方式

流式 HTTP 有两种启动方式,适合不同场景:

方式一:一行启动(独立服务)

最简单的方式,mcp.run 指定传输:

from mcp.server import MCPServer

mcp = MCPServer("Demo")

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

if __name__ == "__main__":
    mcp.run("streamable-http")    # 跑成独立 HTTP 服务
​

mcp.run("streamable-http") 会启动一个 HTTP 服务,默认监听 localhost:8000,路径 /mcp。客户端用 Client("http://localhost:8000/mcp") 连接。

方式二:拿 ASGI app(嵌入现有服务)

如果你想把 MCP 服务端嵌入现有的 Web 服务(如 FastAPI/Starlette 应用),用 streamable_http_app 拿到 ASGI app:

mcp = MCPServer("Demo")

# ... 注册工具/资源/提示词 ...

# 拿到 ASGI app,可挂到任何 ASGI 服务器或现有应用
app = mcp.streamable_http_app()
​

这个 app 可以:

• 用 uvicorn 直接跑:uvicorn.run(app)
• 挂到现有 Starlette/FastAPI 应用里作为子路由
• 部署到任何 ASGI 兼容的服务器

💡 技巧:独立服务用方式一(一行启动),嵌入现有服务用方式二(ASGI app)。方式一简单,适合纯 MCP 服务;方式二灵活,适合「我的 Web 应用里要加一块 MCP 能力」的场景。

三、关键配置项

流式 HTTP 有几个关键配置项,影响服务行为:

最常用的是 host/port(监听地址)与 streamable_http_path(端点路径):

mcp.run(
    "streamable-http",
    host="0.0.0.0",              # 监听所有网卡(可远程访问)
    port=9000,                   # 端口
    streamable_http_path="/mcp"  # 端点路径
)
​

四、json_response vs SSE 流

json_response 配置项决定响应形态,值得单独讲:

默认(json_response=False):SSE 流响应
   客户端 POST 请求
   服务端用 SSE(Server-Sent Events)流式返回
   → 支持服务端持续推送(进度、日志、引导填写问题)
   → 适合需要流式交互的场景

json_response=True:普通 JSON 响应
   客户端 POST 请求
   服务端用普通 JSON 一次性返回
   → 简单,但不能流式推送
   → 适合简单请求-响应场景
​

多数场景用默认(SSE 流),因为它支持第 7 章讲的进度上报、日志通知、引导填写问题——这些都需要服务端持续推送。如果你的场景纯是「请求-响应」无推送,可设 json_response=True 简化。

五、流式 HTTP vs SSE:为什么取代

流式 HTTP 在 2025-03-26 取代了旧版 SSE 传输。为什么?

简单说:流式 HTTP 更简单、更适配现代基础设施。SSE 的双连接模型(一个 POST 发请求,一个 SSE 收响应)在反代、负载均衡下问题多;流式 HTTP 用单一端点,与普通 HTTP 服务无异。

⚠️ 注意:新代码用流式 HTTP,别用 SSE。SSE 仍能工作但已弃用,官方未来可能移除。如果你维护用 SSE 的老代码,规划迁移到流式 HTTP。

六、生产部署的考量

把流式 HTTP 服务端部署到生产,有几个考量:

# 生产部署的概念性配置
mcp.run(
    "streamable-http",
    host="0.0.0.0",                # 远程可访问
    port=8000,
    transport_security=...,        # DNS 重绑定防护配置(第 8.5 节)
    # 认证由第 11 章的 OAuth 中间件处理
)
​

七、流式 HTTP 的优势总结

最后总结流式 HTTP 相对其他传输的优势:

这些优势使流式 HTTP 成为「生产部署的首选传输」——任何需要远程访问、多客户端、高可用的场景,都该用它。

本节要点回顾

1. 流式 HTTP 是生产级传输(2025-03-26),让服务端跑成 HTTP 服务。
2. 两种启动:方式一 mcp.run("streamable-http") 独立服务;方式二 streamable_http_app() 拿 ASGI app 嵌入。
3. 关键配置:host/port(监听)、streamable_http_path(端点,默认 /mcp)、json_response、stateless_http。
4. json_response 决定响应形态:默认 SSE 流(支持推送),True 用普通 JSON(简单)。
5. 取代 SSE 的理由:更简单(单端点)、更适配现代基础设施、支持无状态。
6. 生产考量:监听 0.0.0.0、配置传输安全、加认证、用 HTTPS、可反代/负载均衡。
7. 生产部署首选传输:远程访问、多客户端、高可用场景都该用流式 HTTP。

流式 HTTP 清楚了,下一节讲它取代的 SSE——旧版遗留,知道即可。