Client Registration Fails with 502 Error When Connecting to Auth Server

快速结论：该报错通常出现在使用 MCP Python SDK 的 auth 客户端连接本地 auth 服务器时，客户端注册阶段返回 HTTP 502。优先排查 auth 服务器的 OAuth 注册端点是否正确处理了客户端的注册请求。

问题场景

用户在 GitHub 上使用 modelcontextprotocol/python-sdk 中的 auth 示例。先启动 auth 服务器（mcp-simple-auth），再运行 auth 客户端（mcp-simple-auth-client），客户端在连接时触发 httpx.HTTPStatusError: Registration failed: 502。

报错原文

httpx.HTTPStatusError: Registration failed: 502

客户端完整错误上下文：

❌ Failed to connect: unhandled errors in a TaskGroup (1 sub-exception)
httpx.HTTPStatusError: Registration failed: 502

服务器端日志显示：

INFO:     Uvicorn running on http://localhost:3001
INFO:     127.0.0.1:64473 - "GET /.well-known/oauth-authorization-server HTTP/1.1" 200 OK

另一个相似场景的报错（评论摘要）：

httpcore.ConnectError: All connection attempts failed

原因分析

可能原因：

服务器端注册逻辑静默拒绝：auth 服务器的 /.well-known/oauth-authorization-server 端点虽然返回 200（可访问），但实际接收客户端注册请求时可能因校验失败返回 502，且服务器日志未记录错误。
传输层配置不匹配：streamable-http 传输模式可能需要额外的握手或认证参数，导致客户端注册请求被服务器端错误处理。
OAuth 端点配置问题：注册端点可能无法正确处理客户端发送的有效载荷（payload），例如缺少必要字段或格式错误。
网络连接失败（评论场景）：在类似问题中，httpcore.ConnectError: All connection attempts failed 可能是客户端无法连接服务器端口，与 502 不同但值得注意。

环境排查

确认 Python 版本：3.10 或 3.12（Issue 中两者均出现）
确认 uv 版本：0.7.8（Issue 中使用的版本）
确认 mcp-simple-auth 和 mcp-simple-auth-client 是否为本地最新代码
检查服务器端口（默认 3001）是否被其他进程占用
确认客户端环境变量 MCP_SERVER_PORT 正确指向服务器端口

解决步骤

可能原因——服务器端注册逻辑问题（可优先尝试）：
- 在服务器端的注册处理函数中添加详细的日志输出，记录客户端请求的完整内容（headers、body、URL）。
- 检查 auth 服务器的注册端点是否返回了正确的响应格式（如 JSON 对象、状态码 200/201）。
- 验证客户端发送的注册请求是否符合 OAuth 2.0 规范（例如 client_metadata、redirect_uris 等字段）。
可能原因——传输配置问题：
- 检查客户端和服务器是否都使用了相同的 --transport streamable-http 参数。
- 确保客户端在初始化时没有传递额外的、服务器端不支持的 HTTP 头。
验证服务器是否可连接：
- 使用 curl -v http://localhost:3001/mcp 测试服务器是否正常响应（预期返回 401 或其他状态码，而非连接失败）。
- 如果 curl 也失败，检查服务器是否绑定到正确的地址（如 127.0.0.1 vs 0.0.0.0）。
检查 OAuth 端点路由：
- 确认 /.well-known/oauth-authorization-server 返回的 JSON 中指明了正确的注册端点 URL。
- 对比客户端实际请求的注册端点 URL 与服务器配置是否一致。
评论场景的补充（连接失败而非 502）：
- 如果遇到的是 ConnectError，检查防火墙、代理或本地网络配置。
- 确保服务器已完全启动并监听在正确的地址上。

验证方法

执行上述步骤后，重新运行客户端：

MCP_SERVER_PORT=3001 uv run mcp-simple-auth-client

观察输出是否仍出现 502 或 ConnectError。如果问题解决，客户端应能成功完成注册并开始 session 初始化。

或者，在服务器日志中应看到客户端注册请求的条目（非 502 状态码）。

参考来源

modelcontextprotocol/python-sdk #852

AI 工具推荐

想把多个 AI 模型放在一个入口？

GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型，适合写作、绘图、视频和日常 AI 工作流。

了解 GamsGo AI

推广链接：通过此链接购买，我可能获得佣金，不影响你的价格。

Client Registration Fails with 502 Error When Connecting to Auth Server