Pydantic AI 项目中MCP SSE模式连接失败的排查与解决

问题背景

在使用Pydantic AI项目进行模型上下文协议(MCP)开发时，开发者遇到了一个典型的技术问题：当尝试运行官方提供的SSE(Server-Sent Events)模式示例代码时，客户端连接服务器返回了HTTP 503服务不可用错误，而同样的服务在stdio模式下却能正常工作。

现象描述

开发者按照官方文档示例，使用Node.js的npx工具启动了一个MCP服务器，监听在localhost:3001端口。通过curl测试验证服务端SSE端点可以正常响应，返回200状态码和正确的SSE头信息。然而，当使用Python客户端代码通过MCPServerHTTP类连接时，却遭遇了503错误。

技术分析

网络协议差异

深入排查后发现，问题的根源在于IPv4和IPv6的网络协议栈差异。具体表现为：

1. 服务端(npx启动)默认只监听IPv6地址(::1)
2. Python客户端(httpx库)默认优先尝试IPv4连接(127.0.0.1)
3. 这种协议栈不匹配导致了连接失败

环境特异性

这个问题在特定环境下显现：

• 操作系统：macOS Sequoia 15.3.2
• 硬件平台：Apple M1芯片
• Python版本：3.11.11
• 相关库版本：pydantic-ai 0.0.46

解决方案

项目维护者提供了两种解决途径：

1. 升级到Deno运行时：项目正在从npx迁移到Deno，使用Deno运行MCP服务器可以避免此问题，因为Deno实现的服务器能正确处理IPv4和IPv6连接

2. 客户端配置调整：虽然没有在issue中明确说明，但理论上可以通过以下方式解决：

   • 强制客户端使用IPv6地址([::1])
   • 配置服务端同时监听IPv4和IPv6
   • 使用主机名解析策略调整

技术启示

这个案例为我们提供了几个重要的技术经验：

1. 网络协议兼容性：在现代开发中，IPv4/IPv6双栈支持仍然是一个需要注意的细节问题

2. 环境差异性：即使是官方示例，在不同环境下也可能表现出不同行为，特别是在网络栈实现方面

3. 工具链演进：从npx到Deno的迁移反映了现代JavaScript/TypeScript工具链的演进趋势

最佳实践建议

对于使用Pydantic AI MCP功能的开发者，建议：

1. 优先采用项目推荐的Deno运行方式
2. 在跨平台开发时，明确测试网络连接协议
3. 对于关键业务系统，实现协议栈的fallback机制
4. 保持对项目更新和issue跟踪的关注

这个问题虽然表面上是一个简单的连接失败，但深入分析后揭示了现代软件开发中网络协议栈处理的重要细节，值得开发者重视。