FastAPI-MCP 版本演进全解析从 0.1.0 到 0.4.0 的架构变迁与升级指南【免费下载链接】fastapi_mcpExpose your FastAPI endpoints as Model Context Protocol (MCP) tools, with Auth!项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi_mcpCHANGELOG 是理解一个开源项目技术走向最直接的入口。FastAPI-MCP 通过 CHANGELOG.md 完整记录了从 0.1.0 到 0.4.0 的每一次演进从最初为 FastAPI 生成 MCP 代码的代码生成器到直接挂载进 FastAPI 应用的运行时集成库从默认 SSE 传输到全面拥抱 MCP Streamable HTTP 规范从仅转发 Authorization 头到支持完整的 OAuth 2.1 授权流程。本文以 CHANGELOG 为骨架结合仓库源码与文档梳理这一演进脉络帮助你理解当前 API 设计背后的来龙去脉并为旧版本用户提供清晰的迁移路径。读完你将掌握各版本的能力边界、0.4.0 中mount_http()/mount_sse()的正确用法、AuthConfig 与端点过滤等核心配置的底层实现以及从旧 API 平滑升级到新 API 的具体步骤。版本演进总览一条从代码生成到原生集成的路线图将 CHANGELOG.md 的条目按时间线展开FastAPI-MCP 的演进可以归纳为四个阶段版本阶段主题核心变化0.1.x代码生成器时代提供 CLI 生成/运行/安装 MCP 服务器后重构为运行时直接集成0.2.x类 API 重构引入FastApiMCP类支持独立部署、setup_server()刷新、端点过滤0.3.x授权与传输优化ASGI 传输默认化移除base_url、OAuth 2.1 授权、可配置 header 转发0.4.0Streamable HTTP 时代新增mount_http()实现 MCP Streamable HTTP 规范支持有状态会话mount()弃用这一演进直接体现在 pyproject.toml 中项目当前版本为 0.4.0要求 Python 3.10依赖mcp1.12.0、fastapi0.100.0、httpx0.24.0等并采用 Semantic Versioning 语义化版本控制。0.4.0Streamable HTTP 传输成为推荐方案0.4.0 是 CHANGELOG 中最新、也最重要的一次版本发布。它带来了两项关键能力新增mount_http()实现 MCP Streamable HTTP 规范CHANGELOG 明确说明 HTTP transport 现已成为推荐方案与规范中以 HTTP 为标准、保留 SSE 兼容的定位一致。在源码 fastapi_mcp/server.py 中mount_http()通过FastApiHttpSessionManager定义于 fastapi_mcp/transport/http.py将请求委托给 mcp SDK 的StreamableHTTPSessionManager注册一个同时接受GET/POST/DELETE三种方法的api_routerouter.api_route( mount_path, methods[GET, POST, DELETE], include_in_schemaFalse, operation_idmcp_http, dependenciesdependencies, ) async def handle_mcp_streamable_http(request: Request): return await transport.handle_fastapi_request(request)使用方式非常简单直接替换原来的mount()即可from fastapi import FastAPI from fastapi_mcp import FastApiMCP app FastAPI() mcp FastApiMCP(app) # 使用 HTTP transport推荐 mcp.mount_http()默认挂载路径为/mcpmount_sse()默认路径为/sseMCP 客户端直接连接该 HTTP 端点{ mcpServers: { fastapi-mcp: { url: http://localhost:8000/mcp } } }有状态会话管理HTTP 与 SSE 双传输共享0.4.0 同时为 HTTP 和 SSE 两种传输引入了有状态会话Stateful Session管理。从 fastapi_mcp/transport/http.py 的实现可以看到FastApiHttpSessionManager在首个请求到达时惰性启动 session manager_ensure_session_manager_started()并以statelessFalse显式开启会话支持self._session_manager StreamableHTTPSessionManager( appself.mcp_server, event_storeself.event_store, json_responseself.json_response, statelessFalse, # Always support sessions, but theyre optional security_settingsself.security_settings, )这意味着 MCP 客户端可以与服务端维持跨请求的会话上下文而无需每次重新初始化握手。SSE 侧的会话则通过session_id查询参数关联见 fastapi_mcp/transport/sse.py 中handle_fastapi_post_message()对session_id的解析与_read_stream_writers查找逻辑。⚠️ 破坏性变更mount()弃用0.4.0 中mount()被标记为弃用deprecated将在未来版本移除。源码中它仍然向后兼容地默认走 SSE 传输但会抛出DeprecationWarning提示warnings.warn( mount() is deprecated and will be removed in a future version. Use mount_http() for HTTP transport (recommended) or mount_sse() for SSE transport instead., DeprecationWarning, stacklevel2, )迁移建议将现有代码中的mcp.mount()替换为mcp.mount_http()推荐或mcp.mount_sse()。注意mount()的transport参数目前仅支持sse传入其他值会直接抛出ValueError。官方文档 docs/advanced/transport.mdx 也系统对比了两种传输HTTP 具备更好的会话管理、更稳健的连接处理并与标准 HTTP 实践对齐SSE 仅为向后兼容保留。0.3.x从 Token 直通到完整 OAuth 授权0.3.x 系列是能力扩张最密集的区间CHANGELOG 记录的变更对应着当前仓库中最有辨识度的功能模块。0.3.1MCP 兼容的 OAuth 授权0.3.1 引入了符合 MCP 2025-03-26 规范OAuth 2.1的授权支持核心是AuthConfig配置类见 fastapi_mcp/types.py。它最大的特点是FastAPI 原生直接复用你熟悉的Depends()来做认证检查而非引入一套独立的认证体系from fastapi import Depends from fastapi_mcp import FastApiMCP, AuthConfig mcp FastApiMCP( app, nameMCP With OAuth, auth_configAuthConfig( issuerhttps://auth.example.com/, authorize_urlhttps://auth.example.com/authorize, oauth_metadata_urlhttps://auth.example.com/.well-known/oauth-authorization-server, audiencemy-audience, client_idmy-client-id, client_secretmy-client-secret, dependencies[Depends(verify_auth)], setup_proxiesTrue, ), ) mcp.mount_http()从 fastapi_mcp/server.py 的_setup_auth_2025_03_26()可以看到当配置setup_proxiesTrue时框架会自动在 FastAPI 应用中挂载三类代理端点实现在 fastapi_mcp/auth/proxy.pyOAuth metadata 代理将你的 OAuth 提供方的元数据端点转发到/.well-known/oauth-authorization-server默认metadata_path并可通过setup_fake_dynamic_registration默认True挂载一个静态返回 client_id / client_secret 的假动态注册端点以满足 RFC 7591 动态客户端注册要求——这是npx mcp-remote等主流桥接客户端所必需的authorize 代理在转发授权请求时自动补齐audience与default_scope默认openid profile email解决部分 MCP 客户端不发送这些参数导致 OAuth 提供方行为异常的问题。如果你已经有完全兼容 MCP 的 OAuth 服务器也可以直接用custom_oauth_metadata字典提供完整元数据issuer、token_endpoint、scopes_supported 等获得完全的控制权。注意AuthConfig的校验规则setup_proxiesTrue时必须提供client_id若同时开启假动态注册则必须提供client_secretissuer、custom_oauth_metadata、dependencies三者至少提供其一。0.3.6可配置的 HTTP Header 转发0.3.6 新增了可配置的 HTTP header 转发能力Issue #181。此前框架默认把原始 MCP 请求中的authorization头转发给工具调用现在通过FastApiMCP(headers[...])参数可以自定义转发白名单。源码 fastapi_mcp/server.py 中self._forward_headers {h.lower() for h in headers} # 默认 [authorization]在_execute_api_tool()中仅白名单内的 header 会被大小写不敏感地匹配并注入到对 FastAPI 端点的实际 HTTP 调用中if http_request_info and http_request_info.headers: for name, value in http_request_info.headers.items(): if name.lower() in self._forward_headers: headers[name] value这意味着你不做任何配置就能实现Basic Token Passthrough——只要 MCP 客户端发送Authorization头它就会原样到达你的 FastAPI 端点文档 docs/advanced/auth.mdx 中展示了如何用npx mcp-remote --header Authorization:${AUTH_HEADER}在客户端侧传递令牌。若想强制未认证请求被拒绝则通过AuthConfig(dependencies[Depends(verify_auth)])添加依赖即可。仓库中 examples/08_auth_example_token_passthrough.py 与 examples/09_auth_example_auth0.py 分别提供了两种模式的完整可运行示例。0.3.7修复 OAuth default_scope 缺陷0.3.7 修复了 OAuthdefault_scope相关的 bugIssue #123印证了default_scope参数在授权流程中的实际参与——它作为客户端未显式声明 scope 时的兜底值被发送给 OAuth 提供方。发布事故与版本纪律0.3.2 与 0.3.5CHANGELOG 诚实地记录了两次发布事故值得项目维护者引以为戒0.3.2 是损坏版本官方明确标注 This is a broken release and should not be used其问题basic token passthrough 无法简单配置在 0.3.3 中修复0.3.5 被跳过原因是 0.3.4 之后有一次失败的发布尝试因此直接从 0.3.4 跳到 0.3.6。此外 0.3.4 将mcp依赖锁定到 1.8.1规避了 mcp SDK 1.8.0 的破坏性变更Issue #1340.3.3 则修复了 OpenAPI 转换中param_desc缺失#107、#99与非 ASCII 字符支持#66两个关键问题——这些修复直接影响工具描述的完整性与多语言场景的可用性。0.3.0ASGI 传输默认化与base_url移除0.3.0 是一个有破坏性变更的里程碑MCP 服务器与 FastAPI 应用之间的通信默认改走ASGI 传输即直接通过 FastAPI 的 ASGI 接口对话不再发起真实 HTTP 请求。base_url参数被移除破坏性变更因为 ASGI 模式下无需外部可达的 base URL甚至不要求 FastAPI 服务器实际运行docs/advanced/asgi.mdx 明确说明 Its not even necessary that the FastAPI server will run超时默认值提高到 10 秒修复了短超时问题Issue #71。这一设计在当前源码中清晰可见。fastapi_mcp/server.py 的构造函数默认创建self._http_client httpx.AsyncClient( transporthttpx.ASGITransport(appself.fastapi, raise_app_exceptionsFalse), base_urlhttp://apiserver, timeout10.0, )工具执行时由_request()按 HTTP 方法分发GET/POST/PUT/DELETE/PATCH最终全部通过httpx.ASGITransport直接进入应用内部。如果你确实需要显式指定 base URL 或自定义超时可以注入自己的httpx.AsyncClientimport httpx from fastapi import FastAPI from fastapi_mcp import FastApiMCP app FastAPI() custom_client httpx.AsyncClient( base_urlhttps://api.example.com, timeout30.0 ) mcp FastApiMCP(app, http_clientcustom_client) mcp.mount_http()0.2.0从函数式 API 到类 API 的大重构0.2.0 是一次影响深远的破坏性重构奠定了当前 API 形态类 API 取代函数式 API引入FastApiMCP类创建与挂载显式分离——mcp FastApiMCP(app)之后调用mcp.mount()现在对应mount_http()/mount_sse()为独立部署等更灵活的路由选项提供了基础支持 MCP 服务器与 API 服务分离部署mount_*方法可以挂载到任意 FastAPI 应用或APIRouter上不要求与被创建的 app 相同支持动态刷新当你在 MCP 服务器创建后动态新增 FastAPI 路由时调用mcp.setup_server()即可重新生成工具列表修复 Issue #19。文档 docs/advanced/refresh.mdx 给出了完整示例from fastapi import FastAPI from fastapi_mcp import FastApiMCP app FastAPI() mcp FastApiMCP(app) mcp.mount_http() # 创建 MCP 服务器之后再新增端点 app.get(/new/endpoint/, operation_idnew_endpoint) async def new_endpoint(): return {message: Hello, world!} # 刷新 MCP 服务器以包含新端点 mcp.setup_server()新增端点过滤能力通过四个互斥参数控制暴露范围——include_operations/exclude_operations按 operationId 筛选与include_tags/exclude_tags按标签筛选。从 fastapi_mcp/server.py 的_filter_tools()实现可见框架先从 OpenAPI schema 构建tag - operationIds映射再求集合差集得到最终工具列表同时include_operations与exclude_operations互斥同时传入会抛出ValueErrortags 同理。注意筛选结果会同步裁剪operation_map确保执行阶段与工具列表一致移除函数式 API 与自定义工具装饰器add_mcp_server、create_mcp_server等函数以及mcp.tool()装饰器均在 0.2.0 中删除。0.1.x代码生成器如何走向直接集成CHANGELOG 还揭示了项目最早期0.1.00.1.2的一次根本性转向0.1.0 初始发布核心是 CLI 工具为 FastAPI 应用生成MCP 服务器代码generate / run / install 等命令自动发现端点、类型安全转换、文档保留、Claude 集成并通过 HTTP 请求调用 FastAPI 端点0.1.2 重大重构从代码生成器转变为直接集成库——移除全部 CLI 与代码生成功能MCP 服务器在运行时直接挂载到 FastAPI 应用对外只保留一个add_mcp_server函数同时支持添加自定义工具0.1.4 / 0.1.5 / 0.1.6修复了工具参数传递错误#8、工具动态创建#25、隐藏内部handle_mcp_connection工具#23等问题0.1.1支持 PEP 604 联合类型语法如str | None改善 Python 3.10 下的类型处理——这为后续 Pydantic 模型字段生成与 OpenAPI 转换的正确性打下了基础。这一历史解释了当前 README 中的定位描述FastAPI-native: Not just another OpenAPI - MCP converter——FastAPI-MCP 不是又一个 OpenAPI 转 MCP 的转换器而是 FastAPI 的原生扩展。从旧版本升级到 0.4.0 的迁移清单综合 CHANGELOG 中的破坏性变更从旧版本升级时请逐项核对mount()→mount_http()/mount_sse()0.4.0迁移后建议运行一次应用确认无DeprecationWarning输出SSE 客户端继续使用/sse端点HTTP 客户端改用/mcp端点移除base_url参数0.3.0删掉旧代码中的base_url...如需自定义 base URL 或超时改用http_clienthttpx.AsyncClient(...)注入函数式 API 迁移到类 API0.2.0add_mcp_server(app, ...)写法改为mcp FastApiMCP(app, ...)mcp.mount_http()需要保留的原端点过滤、header 转发等能力全部收敛到FastApiMCP构造函数参数中依赖版本确保mcp1.12.0、fastapi0.100.0、httpx0.24.0、pydantic2.0.0见 pyproject.toml若被旧版 mcp SDK 1.8.0 的破坏性变更困扰可参照 0.3.4 的做法锁定到 1.8.1动态新增路由后记得刷新调用mcp.setup_server()重新生成工具列表否则新端点不会出现在 MCP 工具中。结语FastAPI-MCP 的 CHANGELOG 是一部浓缩的架构演进史它用三次大版本完成了从代码生成器到FastAPI 原生 MCP 扩展的蜕变并在 0.4.0 全面转向 MCP Streamable HTTP 规范。理解这条演进路径不仅能帮你写出符合当前 API 规范的代码也能在遇到旧教程、旧代码时快速定位问题根源。如果你正准备接入建议直接以 examples/01_basic_usage_example.py 为起点配合 docs/advanced/transport.mdx 选择传输方式再按需参考 docs/advanced/auth.mdx 与 docs/advanced/refresh.mdx 解锁授权与动态刷新能力。【免费下载链接】fastapi_mcpExpose your FastAPI endpoints as Model Context Protocol (MCP) tools, with Auth!项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi_mcp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考