TypeError: Server.streamable_http_app() got an unexpected keyword argument ‘session_idle_timeout’

快速结论：该报错发生在通过 MCP Python SDK 的高级 API streamable_http_app() 配置会话空闲超时参数时，由于该参数未在高层接口中透传，导致函数调用直接抛出 TypeError。优先排查思路是检查是否使用了 StreamableHTTPSessionManager 手动构建会话管理器，或升级 SDK 至包含修复的版本。

适用环境：MCP Python SDK（modelcontextprotocol/python-sdk），涉及 mcp.server.Server（lowlevel）和 MCPServer 模块；Issue 中未明确说明操作系统、Python 版本或显卡信息，无法确认具体环境。

最快修复方案：暂无确认的一步修复方案。Issue 已提出修复 PR（#2457），但在官方合并前，可先绕过 streamable_http_app() 接口，直接实例化 StreamableHTTPSessionManager 并手动配置 session_idle_timeout，以解决参数无法传入的问题。

注意事项：手动构建会话管理器仅解决参数透传问题，无法规避第二个 Bug——空闲超时可能取消正在执行的请求。建议为耗时较长的请求设置宽松的超时值，或等待修复版本发布后再启用该功能。

问题场景

用户在使用 MCP Python SDK 构建 Streamable HTTP 服务时，尝试通过官方推荐的高层 API Server.streamable_http_app() 或 MCPServer.streamable_http_app() 传入 session_idle_timeout 参数，以配置空闲会话回收策略。调用时立即触发 TypeError，导致服务无法启动。

报错原文

TypeError: Server.streamable_http_app() got an unexpected keyword argument 'session_idle_timeout'

原因分析

可能原因：session_idle_timeout 功能在 StreamableHTTPSessionManager 中已实现并接受该参数，但高层封装 streamable_http_app() 方法在定义时未声明此参数，也未将其转发给底层会话管理器。这导致参数在传递时被 Python 解释器判定为未知关键字参数而抛出 TypeError。同时，该 SDK 实现存在另一个关联 Bug：空闲超时通过 anyio.CancelScope 包裹整个请求处理流程，但没有在请求执行期间挂起超时计时，导致慢速处理程序可能在执行中途被取消。

环境排查

确认 MCP Python SDK 版本，检查是否已合入修复 PR（#2457）或相关补丁。
检查 mcp.server.lowlevel.server.Server 和 mcp.server.mcpserver.server.MCPServer 中 streamable_http_app() 的方法签名，确认是否包含 session_idle_timeout 参数。
如已使用 StreamableHTTPSessionManager，确认 anyio 版本及并发请求场景下 CancelScope 行为。

解决步骤

绕过高层 API（可优先尝试）：不使用 streamable_http_app()，改为直接创建 StreamableHTTPSessionManager 实例，手动传入 session_idle_timeout 参数并配置 ASGI 应用。
检查修复状态：查看 SDK 仓库的最新 release 或 main 分支，确认 Issue #2455 是否已关闭并合入修复代码；若未修复，可关注 PR #2457 的合并进度。
临时规避第二个 Bug：如必须使用空闲回收功能，为 session_idle_timeout 设置远大于处理器最大耗时的值，避免慢请求被中途取消。
等待官方修复：合入的修复方案将透传参数并在请求执行期间挂起空闲计时，届时可直接在 streamable_http_app() 中使用该参数。

验证方法

尝试在 streamable_http_app() 调用中加入 session_idle_timeout=30 参数，若不再抛出 TypeError 即表示参数已正确透传；再模拟一个耗时长于超时值的工具处理程序，确认请求能完整返回结果而非被取消。更稳妥的方式是运行 SDK 自带回归测试（如 tests/server/test_streamable_http_manager.py 中的相关用例）。