MCP 服务怎么开 HTTP 端口:六类报错实测与多进程 404

先给结论:这套做法能用,一台普通笔记本十分钟就能把 MCP 服务从 stdio 改成 HTTP,官方 Python 客户端跑完握手、列工具、调工具合计 0.09 秒。麻烦在于失败几乎都不写在返回正文里:Accept 少写一个值返 406,Host 头对不上返 421,用多进程部署时每十次请求会有一到两次莫名 404。

下面每条结论都来自 mcp 2.3.0 加 Python 3.13 的受控实验,服务端用官方 MCPServer 起,客户端用官方 streamable_http_client,原始回包全部留档。

十二行代码把服务改成 HTTP

传输层只要指定一个参数,SSE 编码、会话表、请求分发都由 SDK 处理。默认路径 /mcp,默认端口 8000。

from mcp.server.mcpserver import MCPServer

mcp = MCPServer("demo")


@mcp.tool()
def add(a: int, b: int) -> int:
    """两数相加。"""
    return a + b


if __name__ == "__main__":
    mcp.run(transport="streamable-http", host="127.0.0.1", port=8123)

依赖装法用 uv 最快,国内源怎么设见uv 国内加速那篇。服务起来以后日志只有两行,第三行要等第一个请求进来才会打印,内容是新建运输层的会话号。这条日志后面会反复出现,值得记住它的样子。

406:Accept 必须同时写两个值

这是第一个拦人的地方。请求头只写 application/json,服务端直接拒,返回 406,正文是一段 JSON-RPC 错误,码值 -32600,文案是 Client must accept both application/json and text/event-stream。

curl -i -X POST http://127.0.0.1:8123/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  --data-binary @init.json

两种都写就通了,返回 200,正文是 text/event-stream,一帧 message 事件,里面带服务器信息、协商到的协议版本 2025-11-25,以及响应头里的 mcp-session-id。这个头是后面所有请求的通行证,丢了它一切请求都进不去。

这里有个容易误判的细节。curl 默认发 Accept: */*,SDK 会把星号当成两种都接受,于是手测看起来很顺,等你换成真实客户端,它只声明 application/json,立刻炸成 406。判断方法很简单,看请求头里有没有第二个值,别信 curl 的手感。

400 与 404:会话头是第一道门

拿到会话号之后,后续每个 POST 都要带上 Mcp-Session-Id。不带,返回 400,文案 Bad Request: Missing session ID。带一个自己编的,返回 404,文案 Session not found。两个错看起来只差一个数字,排查方向完全不同:400 是客户端漏传,404 是会话真的没了。

会话什么时候没的,有三种情况。客户端主动 DELETE 会立刻终止它,之后再用就是 404。服务端默认 1800 秒空闲回收,超时后同样 404。最后一种最隐蔽,多进程部署时请求落到另一个进程,那个进程的会话表里没有这条记录,于是也返 404。

还有一个反直觉现象:每个不带会话号的请求,服务端都会先新建一条会话记录再判错。失败请求也不例外。一轮探针打下来,日志里 27 条新建、24 条销毁,差额就是真正活着的会话。健康检查如果拿 GET 去打这个地址,每次都会白造一条记录。

421:Host 白名单的三个坑

SDK 在绑 127.0.0.1、localhost、::1 时会自动打开 DNS 重绑定防护,白名单写死成三条带端口的模式。一旦请求的 Host 头不在里面,返回 421,正文是纯文本 Invalid Host header,连 JSON-RPC 外壳都没有。

第一个坑是端口。白名单条目形如 localhost:*,星号只代表端口部分,Host 必须真的带端口才匹配。所以反代把 Host 透传成裸域名,比如 mcp.example.com,即使白名单里写了 mcp.example.com:* 照样 421。实测把 Host 换成带 443 的同域名立刻 200。要放行裸域名,得在白名单里单独加一条不带冒号的。

第二个坑方向相反。绑 0.0.0.0 时这段防护不会自动打开,白名单为空等于不校验,任意 Host 都能过,实测拿 1.2.3.4:8150 请求照样 200。局域网调试会觉得很方便,生产环境如果照抄这条绑定,等于自己把防护关掉,还以为是开着的。

第三个是 Origin。带 Origin 头发请求时还要过 allowed_origins,不在名单里返 403,文案 Invalid Origin header。浏览器端调用 MCP 服务必须把页面域名写进去,否则前端只会看到一个 403。

from mcp.server.transport_security import TransportSecuritySettings

mcp.run(
    transport="streamable-http",
    host="127.0.0.1",
    port=8151,
    transport_security=TransportSecuritySettings(
        enable_dns_rebinding_protection=True,
        allowed_hosts=["mcp.example.com", "mcp.example.com:*", "127.0.0.1:*"],
        allowed_origins=["https://mcp.example.com"],
    ),
)

409 与 405:一个会话只允许一条推送流

客户端可以用 GET 开一条长连接,让服务端主动往下推消息。同一个会话第二条 GET 会被拒,返回 409,文案 Conflict: Only one SSE stream is allowed per session。浏览器标签开了两个、或者重连逻辑没关旧流,都会撞这个错。

方法不支持时返回 405,响应头里带 Allow: GET, POST, DELETE。这个头值得抄下来当下限约定,反向代理只放行这三个方法就够了。

进度通知:不传令牌就一条都不发

工具里调用 report_progress 上报进度,客户端必须先在请求参数里塞 _meta.progressToken。不传的话,服务端一条通知都不发,也不报错,四秒的任务只回一帧结果。传了同一个令牌,同一份任务会变成四帧:三次进度加一次结果,全部走同一个 POST 的响应流。

curl -N -X POST http://127.0.0.1:8123/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'Mcp-Session-Id: <会话号>' \
  -d '{"jsonrpc":"2.0","id":21,"method":"tools/call",
       "params":{"name":"slow_task","arguments":{"seconds":3},
       "_meta":{"progressToken":"tk1"}}}'

这条对前端体验影响很大。进度条一直不动,先怀疑令牌没传,别怀疑工具没执行。

多进程部署:十次里有一到两次 404

会话表存在进程内存里,进程之间不共享。用 uvicorn 起两个 worker,同一个会话连发 30 次列表请求,27 次 200,3 次 404;起四个 worker 连发 40 次,33 次 200,7 次 404。失败的那几次日志里写的是 Rejected request with unknown or expired session ID,看起来像会话过期,实际是打到了别的进程。

worker 数 请求数 200 404 失败率
2 30 27 3 10.0%
4 40 33 7 17.5%

这个失败率不固定,取决于连接被分到哪个进程,表现是时好时坏,最难查。三条出路:单进程跑,或者开无状态模式,或者在前面加粘性会话让同一客户端固定落到一个进程。要真正多进程扩容,得把会话存储换成外置实现,SDK 留了 event_store 参数给这条路。

无状态与纯 JSON:两种模式的取舍

无状态模式开起来以后没有会话号,响应头里干干净净,客户端连握手都能省,直接 POST 一句 tools/list 就拿到工具清单,伪造的会话头会被忽略,DELETE 返回 405。适合容器化、无状态扩容、每个请求都自包含的服务。代价是无法做服务端主动推送,进度通知仍然能走,因为它挂在当前这条 POST 的响应流里。

纯 JSON 模式是把响应从 SSE 改成一次性 JSON,客户端只声明 application/json 就行,返回 200 加 388 字节的完整结果,中间没有任何帧。调试期最省事,接网关也省事。代价是长任务期间一个字节都不吐,前面挂 60 秒超时的负载均衡会直接掐断。

踩坑:三种错误体并存,状态码不能单独当判据

第一坑是错误体不统一。参数与协议类错误回 JSON-RPC,码值 -32600 或 -32700,正文里带 message;安全检查类错误回纯文本,比如 Content-Type 写成 text/plain 返 400 Invalid Content-Type header,Host 不匹配返 421,Origin 不匹配返 403,body 超过 4MiB 返 413 Request body too large。客户端如果只按 JSON 解析错误体,这四类全会被吞成解析异常,日志里只剩一句看不懂的报错。

第二坑是状态码骗人。调用一个不存在的方法,HTTP 返回 200,错误藏在正文的 -32601 Method not found 里。反过来,参数解析失败是 400 加 -32700,还能带列号,比如 key must be a string at line 1 column 2。判断一次调用成不成功,只能看正文里有没有 error 字段。

第三坑是重复握手不报错。同一个会话里再发一次 initialize,服务端照常返 200 并把握手结果再念一遍,不提示已初始化。客户端重连逻辑写错、握手发两遍,从返回码上完全看不出来,只能靠会话号有没有变来判断。

客户端代码照旧教程抄会直接报错

2.x 把客户端入口改了名,streamablehttp_client 已经不存在,导入时抛 ImportError,新名字是 streamable_http_client,多一个下划线。它返回的是流对象容器,拆包方式也和旧版不同。

模型字段从驼峰改成下划线。握手结果取 server_info 而不是 serverInfo,工具结果取 structured_content 而不是 structuredContent,照旧代码写会报 AttributeError,提示里倒是给了 correct name,但错误发生在取值那一步,很容易以为是服务端没返回。

from mcp import ClientSession
from mcp.client.streamable_http import streamable_http_client

async with streamable_http_client("http://127.0.0.1:8123/mcp") as streams:
    async with ClientSession(streams[0], streams[1]) as s:
        init = await s.initialize()
        print(init.server_info.name, init.protocol_version)
        res = await s.call_tool("add", {"a": 20, "b": 22})
        print(res.content[0].text, res.structured_content)

这段跑通输出 server 名、协议版本 2025-11-25,工具返回 42,结构化结果里是 result 字段。整条链路 0.09 秒。工具返回类型也会影响结构化输出,返回整数或字符串会生成 outputSchema,包成 result 键;直接注解成 dict 或 list 就静默丢掉结构化字段,这条在工具定义那篇里写过。

上线前的五项检查

检查项 错的表现 改法
Accept 头两个值 406,正文 -32600 同时声明 json 与 event-stream
会话头透传 400 Missing session ID 从握手响应头取,逐请求带上
Host 与 Origin 白名单 421 或 403,纯文本 裸域名与带端口写法各加一条
进程数与会话一致性 随机 404,失败率一成上下 单进程、无状态或粘性会话
网关超时与缓冲 长任务中途断流 超时抬高,关响应缓冲

反代那一层还有两个默认值要改。响应缓冲必须关掉,否则 SSE 的帧会被攒在网关里,客户端等到任务结束才一次性收到;SDK 自己会带 x-accel-buffering: no,nginx 认这个头,别的网关要么配 proxy_buffering off,要么手工透传。读超时按最长工具耗时给,默认 60 秒对长任务一定不够。

FAQ

可以 uvicorn 直接起多进程吗

有状态模式不行。会话表在进程内存里,请求落到别的进程就是 404,实测两 worker 失败率一成,四 worker 一成七。要扩就得改成无状态模式,或者把会话存到外置存储,再或者前面加粘性会话。

反向代理最常见的两个 4xx 是什么

421 和 403。前者是 Host 头没进白名单,注意裸域名和带端口是两条不同条目;后者是 Origin 头没进白名单。两个都是纯文本响应,不走 JSON-RPC,抓包时容易被当成网关自己发的。

客户端一直 406 或者一导入就报错怎么办

406 说明 Accept 只写了一个值,补上 text/event-stream。导入报错说明用的是 2.x 里已经不存在的旧函数名,换成 streamable_http_client,同时把取值改成 server_info 与 structured_content 这类下划线写法。

同一套协议在 stdio 上的最小实现与握手细节见FastMCP 改名那篇,需要不带网络端口跑的场景可以先看它。

全部文章归档与模型专题