FDE Times 数据在招 FDE 职位 924▲33 近 7 天在招职位数的变化(同口径比较):不计入本周新开始追踪的公司的职位近 7 天新增 80在招公司 196支持远程 25%美国薪资中位数 $200k招聘最多 Databricks 107
ENVI

前线部署工程师(FDE)的专业媒体

技能指南 · 指南

客户的 MCP 服务器返回 401,毛病多在请求头

弄清 initialize 顺序、Accept 头和会话 ID,就能读懂客户服务器的报错,赶在周四演示前跑通工具调用。

分享微博

要点速览

  • Streamable HTTP 是远程 MCP 服务器的标准传输方式:只有一个端点,每条消息都是一次新的 POST,客户端必须同时接受 JSON 和 SSE。
  • 令牌放在每个请求的 Authorization 头中,绝不放进查询字符串。只能使用该 MCP 服务器自己的授权服务器签发的令牌。
  • initialize 之后,每个请求都必须回传会话 ID 和协商好的协议版本。遇到 404 就重新握手。每个请求都要设置超时。
一张由四个步骤和四个请求头组成的表格。第一次 initialize 时,客户端只发送 Accept,收到 401;带令牌的 initialize 发送 Accept 和 Authorization,并收到 Mcp-Session-Id;从 initialized 开始,客户端发送 Accept、Authorization、Mcp-Session-Id 和 MCP-Protocol-Version 全部四个头。tools/call 一行被高亮:四个头全部发送,收到 200。
发往客户 MCP 服务器的每个请求都必须自己带上身份、会话和版本。从 initialized 开始,客户端的每个请求都必须发送全部四个头;Mcp-Session-Id 仅在服务器分配时需要。来源:MCP 规范(Streamable HTTP、Authorization),见正文讨论。

周一,客户在 Slack 上给你发来一行消息:里面是他们刚搭好的内部 MCP 服务器的 URL,外加一句“把你的 Agent 指过来就行”。你随手发了个 POST,收到 401。客户的团队不在现场,文档很单薄,演示定在周四上午。

对前线部署工程师(FDE)来说,这只是平常的一周。服务器和认证基础设施都不归你管,但调用它们的客户端归你,而且必须稳定可用。本指南从这个 401 出发,一个请求一个请求地走到第一次工具调用。

先记住一点:这个阶段的大多数故障出在 HTTP 请求头,而不是 Agent 逻辑。掌握规范里的几条规则,就能读懂客户服务器返回的错误,而不必靠猜。

远程服务器用的是什么协议?

MCP 规范定义了两种标准传输方式,其中 Streamable HTTP 用于远程服务器。它取代了 2024-11-05 版本中的 HTTP+SSE 机制。如果示例代码为服务器发送事件(SSE)和 POST 分别建立连接,那它几乎肯定已经过时。

Streamable HTTP 的模型很简单。服务器只暴露一个路径,称为 MCP 端点,同时接受 POST 和 GET。客户端的每条 JSON-RPC 消息都是一次新的 POST。Accept 头必须同时列出 application/json 和 text/event-stream,因为服务器可能返回普通 JSON,也可能返回 SSE 流。

生命周期的顺序同样固定。initialize 必须是第一次交互。服务器响应后,客户端发送 initialized 通知,之后才能开始工具调用等常规操作。这个顺序是强制的:先 initialize,再 initialized,然后才是工具。

示例:用原始 HTTP 探测客户服务器

先别急着用 SDK,自己用 httpx 发请求。这样能看清服务器到底返回了什么,以后 SDK 报出含糊的错误时,你知道该去哪里找。假设客户的端点是 https://mcp.khach.vn/mcp。

import httpx
URL = "https://mcp.khach.vn/mcp"
H = {"Accept": "application/json, text/event-stream",
     "Content-Type": "application/json"}
init = {"jsonrpc": "2.0", "id": 1, "method": "initialize",
        "params": {"protocolVersion": "2025-06-18", "capabilities": {},
                   "clientInfo": {"name": "fde-probe", "version": "0.1"}}}

发送请求,并且从第一行起就设置超时。规范建议每个请求都设置超时,到期即取消请求,避免连接挂起。服务器位于客户 VPN 之后时,这一点更加重要。

r = httpx.post(URL, json=init, headers=H, timeout=10)
print(r.status_code)
print(r.headers.get("www-authenticate"))

如果服务器受保护,响应会是带 WWW-Authenticate 头的 401。规范要求客户端解析这个头并正确响应,因为它指向认证元数据。

从 401 到访问令牌

受保护资源的元数据位于默认的 well-known 地址:/.well-known/oauth-protected-resource。客户端从这里查到由哪个授权服务器为该 MCP 服务器签发令牌。

meta_url = "https://mcp.khach.vn/.well-known/oauth-protected-resource"
meta = httpx.get(meta_url, timeout=10).json()
as_url = meta["authorization_servers"][0]

下一步需要授权服务器上的两个地址:一个接收授权请求,一个签发令牌。具体怎么查取决于客户的基础设施。下面的示例用两个占位变量 AUTHORIZE 和 TOKEN_ENDPOINT 表示它们,另外还有 CLIENT_ID 和 REDIRECT。

接下来是 OAuth 流程,规范在这里提出了两条硬性要求:客户端必须使用授权码交换证明密钥(PKCE),并且必须发送 resource 参数,把令牌绑定到目标 MCP 服务器。准备工作如下。

import base64, hashlib, secrets
from urllib.parse import urlencode
verifier = secrets.token_urlsafe(64)
digest = hashlib.sha256(verifier.encode()).digest()
challenge = base64.urlsafe_b64encode(digest).rstrip(b"=").decode()
auth_params = {"response_type": "code", "client_id": CLIENT_ID,
               "redirect_uri": REDIRECT, "code_challenge": challenge,
               "code_challenge_method": "S256", "resource": URL}
login_url = f"{AUTHORIZE}?{urlencode(auth_params)}"

用户在浏览器中打开 login_url 并登录,授权服务器把授权码发送到重定向地址。客户端用授权码换取令牌,同时发送 verifier,并重复同一个 resource 值。

tok = httpx.post(TOKEN_ENDPOINT, timeout=10, data={
    "grant_type": "authorization_code", "code": code,
    "redirect_uri": REDIRECT, "client_id": CLIENT_ID,
    "code_verifier": verifier, "resource": URL}).json()

一个实用建议:对接客户的内部服务器时,CLIENT_ID、REDIRECT 和那两个端点多半得向对方团队要。在写任何代码之前,把它们列进第一次通话的问题清单。

第二次握手,这次做对

拿到令牌后,再发一次 initialize。令牌放在 Authorization 头中。规范要求每个请求都带上这个头,即使这些请求属于同一个逻辑会话。

H["Authorization"] = f"Bearer {tok['access_token']}"
r = httpx.post(URL, json=init, headers=H, timeout=10)
sid = r.headers.get("mcp-session-id")
if sid:
    H["Mcp-Session-Id"] = sid

如果服务器在初始化时分配了 Mcp-Session-Id,客户端之后的每个请求都必须回传它。客户端还必须发送 MCP-Protocol-Version 头,值为协商后的版本。不要把自己提议的版本写死,而要读取服务器在 initialize 结果中返回的版本。

由于 Accept 允许 SSE,initialize 的响应可能是事件流而不是 JSON。下面的代码两种情况都能处理:如果是 SSE,先取出 data 行再解析。

import json
ctype = r.headers.get("content-type", "")
if ctype.startswith("text/event-stream"):
    line = next(l for l in r.text.splitlines() if l.startswith("data:"))
    body = json.loads(line[5:])
else:
    body = r.json()
H["MCP-Protocol-Version"] = body["result"]["protocolVersion"]

直到这时,才带上完整的请求头发送 initialized 通知。

note = {"jsonrpc": "2.0", "method": "notifications/initialized"}
httpx.post(URL, json=note, headers=H, timeout=10)

如果不检查 Content-Type 就直接调用 .json(),你可能要为一个毫无意义的解析错误耗掉半小时。

第一次工具调用

现在 H 中已经有 Accept、Authorization、Mcp-Session-Id 和 MCP-Protocol-Version。挑一个无害的工具来调用,比如只读查询。下面的工具名和参数是假设的(用订单号查询订单),请换成客户服务器实际暴露的工具。

call = {"jsonrpc": "2.0", "id": 2, "method": "tools/call",
        "params": {"name": "tra_cuu_don_hang",
                   "arguments": {"ma_don": "DH001"}}}
r = httpx.post(URL, json=call, headers=H, timeout=10)
print(r.status_code, r.headers.get("content-type"))

返回 200 且带有结果,说明你走完了整条路径:从 401,经过 OAuth,到一次真实的工具调用。保存好这次运行的日志,接下来几天它会是你最好的参考。

弄懂请求头之后,把重活交给 SDK

原始 HTTP 探测是为了弄懂原理,不是为了上生产环境。官方 Python SDK 的 README 写明:向 Client 传入 URL 即选择 Streamable HTTP,工具通过 call_tool 调用。官方的客户端构建教程要求 SDK 版本不低于 2.0.0,所以从网上复制示例代码之前,先确认已安装的版本。

最稳妥的工作顺序是:先用原始 HTTP 探测,直到 tools/call 成功,并记录每一步的全部请求头;然后切换到 SDK,按对应版本的指南加上 OAuth 流程;接着用 call_tool 重复之前测试过的那次只读调用;最后才接入 Agent。

SDK 报错时,回头翻探测阶段的请求头日志,通常一眼就能看出缺了哪个头。

让演示翻车的错误

最常见的错误是把令牌放进 URL,比如为了快速测试加上 ?access_token=。规范明确禁止这样做,而且客户那边的代理和网关日志经常会记录 URL。令牌只能放在 Authorization 头中。

下一个错误更隐蔽:用错令牌。客户已经有另一个内部系统的 API 密钥,有人提议“先凑合用这个”。规范禁止客户端向 MCP 服务器发送任何并非由该服务器自己的授权服务器签发的令牌。resource 参数存在的理由也大致如此。

还有一个错误是把 404 当作致命错误。服务器对携带会话 ID 的请求返回 404 时,客户端必须从 initialize 开始建立新会话。代码里需要一条带重试上限的重新握手路径,而不是把异常直接抛给 Agent。

另外三个小错误同样会浪费几个小时:Accept 头只列了一种内容类型;initialize 之后忘了发送 MCP-Protocol-Version;请求没有超时,客户 VPN 不稳定时 Agent 就一直挂着。再加上复制旧的 HTTP+SSE 代码或 2.0 之前的 SDK 片段,就是一份每次演示前都该过一遍的检查清单。

如何把这项技能写进简历

阅读 FDE 岗位描述时,留意“integrate with customer systems”、“OAuth”、“MCP”或“agent tooling”这类说法。它们意味着这份工作会遇到本文开头的那种情况。

简历上,一句具体的描述比一串技术名词更有分量。例如:“基于 Streamable HTTP 构建 MCP 客户端,支持 OAuth(PKCE、resource),在调用客户 VPN 后的服务器时处理会话过期和超时。”面试官会追问 401 和 404,而你自己的探测脚本早已给了你答案。

下次客户发来一个 URL,附上一句“指过来就行”,你不会从 SDK 开始,而是从一段在每一步都打印请求头的短脚本开始。

这篇文章对你有帮助吗?

6 个信源
路线图上的下一篇 · 阶段 3: AI 应用每个分块加几十个 token 上下文,检索失败减少 49%默认分块参数没见过客户文档,应先用真实问题评测;再加上重排序,降幅可达 67%。