客户的 MCP 服务器返回 401,毛病多在请求头
弄清 initialize 顺序、Accept 头和会话 ID,就能读懂客户服务器的报错,赶在周四演示前跑通工具调用。
要点速览
- Streamable HTTP 是远程 MCP 服务器的标准传输方式:只有一个端点,每条消息都是一次新的 POST,客户端必须同时接受 JSON 和 SSE。
- 令牌放在每个请求的 Authorization 头中,绝不放进查询字符串。只能使用该 MCP 服务器自己的授权服务器签发的令牌。
- initialize 之后,每个请求都必须回传会话 ID 和协商好的协议版本。遇到 404 就重新握手。每个请求都要设置超时。
周一,客户在 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 开始,而是从一段在每一步都打印请求头的短脚本开始。
这篇文章对你有帮助吗?
感谢你的反馈!