Allow customization of the Starlette app (middleware, routes, etc)

问题场景

用户在使用 FastMCP 并指定 transport="sse" 时，希望向内部的 Starlette 应用添加自定义中间件、路由（如健康检查端点）或扩展超时设置。但在旧版 SDK 中，Starlette 应用被封装在 run_sse_async 方法内，无法直接访问和修改。此外，当服务器部署在非根路径（例如 /some/path/to/sse）时，SseServerTransport 的消息 URL 拼接可能出现截断问题。

报错原文

# 报错不在 Issue 中直接出现，但代表了需要自定义时的限制
# 用户期望类似：
app = mcp_server._create_sse_app()
app.add_route(...)
app.add_middleware(...)
# 但旧版 SDK 未暴露此方法

# URL 拼接 Bug 表现：
# 如果服务器路径为 http://localhost:8000/some/path/to/sse
# SseServerTransport("/messages/") 将错误输出 http://localhost:8000/messages
# 正确应为 http://localhost:8000/some/path/to/messages

原因分析

SDK 早期设计将 Starlette 应用的创建内嵌在 run_sse_async 方法中，未提供外部访问接口，导致用户无法自定义中间件或路由。同时，SseServerTransport 的路径拼接实现使用了 urllib.urljoin，其行为会忽略基路径中的路径部分（如 /some/path/to/sse），仅保留主机和端口，导致消息 URL 被截断。

环境排查

• 确认 MCP Python SDK 版本（v2 之前存在此限制）。
• 检查服务器部署的根路径是否有自定义（非 /）。
• 若使用自定义中间件或路由，确认是否已升级到 v2。
• 如有超时问题，检查客户端 sse_client 的 read_timeout 参数（默认 5 秒）。

解决步骤

1. 升级 SDK 到 v2 或更高版本：官方已在 v2 中通过 PR #312 开放了 Starlette 应用的自定义能力，可直接在 FastMCP 对象上添加中间件/路由（具体 API 请参考新版文档）。
2. 临时方案（无法升级时）：参考社区方案，创建一个独立的 FastAPI 或 Starlette 服务器，手动集成 MCP SSE 处理端点。示例仓库：fastapi_mcp_sse 或 starlette_mcp_sse。在该服务器中，用户可以自由添加健康检查路由、中间件等。
3. 修复 URL 拼接 Bug（旧版）：在实例化 SseServerTransport 时，去掉消息路径的前导斜杠：SseServerTransport("messages/")，或者确保基路径以斜杠结尾并正确拼接。
4. 调整超时：若请求超时，在客户端创建 SSE 连接时传递 read_timeout 参数（如 sse_client(url, read_timeout=30)）。

验证方法

成功添加自定义路由后，可通过 HTTP 客户端访问该端点（如 GET /health）返回预期响应。同时确认 SSE 消息流功能正常——MCP 工具调用能正确执行。URL 拼接 Bug 修复后，可通过打印实际消息 URL 验证路径正确。

参考来源

modelcontextprotocol/python-sdk #194

AI 工具推荐

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

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

了解 GamsGo AI

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