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

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

原文: https://fdetimes.net/zh/guides/mcp-client-remote-server-oauth/

周一，客户在 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。

```python
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 之后时，这一点更加重要。

```python
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 服务器签发令牌。

```python
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 服务器。准备工作如下。

```python
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 值。

```python
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 头中。规范要求每个请求都带上这个头，即使这些请求属于同一个逻辑会话。

```python
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 行再解析。

```python
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 通知。

```python
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。挑一个无害的工具来调用，比如只读查询。下面的工具名和参数是假设的（用订单号查询订单），请换成客户服务器实际暴露的工具。

```python
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 开始，而是从一段在每一步都打印请求头的短脚本开始。

**本周动手试试:**

- 用 httpx 写一个探测脚本，向一台开启认证的测试 MCP 服务器依次发送 initialize 和 tools/call，并在每一步打印状态码和响应头。
- 给脚本加上三项自动检查：每个请求都带 Authorization；initialize 之后的每个请求都带 Mcp-Session-Id（如果服务器分配了）和 MCP-Protocol-Version；每个请求都设置了超时。
- 把这段经历写成简历上的一句话，写明传输方式、带 PKCE 的 OAuth 流程，以及你如何处理会话过期。

## 信源

- [Transports - Model Context Protocol](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports)

- [Lifecycle - Model Context Protocol](https://modelcontextprotocol.io/specification/2025-06-18/basic/lifecycle)

- [Authorization - Model Context Protocol](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization)

- [RFC 9728: OAuth 2.0 Protected Resource Metadata](https://www.rfc-editor.org/rfc/rfc9728.html)

- [modelcontextprotocol/python-sdk](https://github.com/modelcontextprotocol/python-sdk)

- [Build an MCP client - Model Context Protocol](https://modelcontextprotocol.io/docs/develop/build-client)
