FastAPI-MCPFastAPI 接口转 MCP 工具网关部署实践指南【免费下载链接】fastapi_mcpExpose your FastAPI endpoints as Model Context Protocol (MCP) tools, with Auth!项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi_mcp需要把已有的 FastAPI 接口暴露给大模型 Agent 直接调用时FastAPI-MCP 可以零配置地把每个端点转换成模型上下文协议MCP工具并支持挂载到同一应用或独立部署为 MCP 网关。这份指南从最小示例出发覆盖部署、传输协议选择与生产要点读完你可以跑通同应用挂载与独立网关两种部署理解 HTTP 与 SSE 传输的取舍依据配置工具白名单、认证与超时避开注册时机等常见坑项目定位与适用边界FastAPI-MCP 解决的问题很具体把一个现成的 FastAPI 应用自动生成为 MCP 服务器端点即工具请求/响应模型Schema与接口文档原样保留。它不做服务发现不提供负载均衡与路由能力也不能替代 API 网关这些仍由前置基础设施承担。关键特性零配置指向应用即生成工具原生认证复用 FastAPI 的Depends()ASGI 传输进程内调用无网络开销灵活部署同应用挂载或独立网关环境依赖与安装硬性依赖Python 3.10官方推荐 3.12FastAPI 0.100.0随fastapi-mcp自动安装mcp 1.12.0随fastapi-mcp自动安装主安装方式uvuv add fastapi-mcp备选方式pippip install fastapi-mcp核心实操最小示例把已有 FastAPI 应用接入 MCP下面的代码在一个已有接口上生成 MCP 服务器并用mount_http()挂载流式 HTTP 传输Streamable HTTP端点默认在/mcpfrom fastapi import FastAPI from fastapi_mcp import FastApiMCP app FastAPI(title物品服务) app.get(/items/{item_id}, operation_idget_item) async def read_item(item_id: int): 根据 ID 查询物品详情404 表示不存在 return {item_id: item_id} # 1. 用现有 FastAPI 应用生成 MCP 服务器 mcp FastApiMCP(app) # 2. 挂载 HTTP 传输端点位于 /mcp mcp.mount_http() if __name__ __main__: import uvicorn uvicorn.run(app, host0.0.0.0, port8000)启动后MCP 客户端连接http://localhost:8000/mcplist_tools返回get_item工具其描述来自接口的 docstring。工具被调用时请求通过 httpx 的 ASGI 传输直接打到应用的路由上不经过真实网络请求因此延迟很低。⚠️ 常见误区0.4.0 起旧的mount()方法已弃用必须显式使用mount_http()推荐或mount_sse()。旧代码升级后继续调用mount()会在未来版本直接报错。MCP 客户端侧的配置{ mcpServers: { fastapi-mcp: { url: http://localhost:8000/mcp } } }独立部署网关的完整步骤大型系统中建议把 MCP 网关与业务接口分离业务 API 不再对外暴露只通过 MCP 提供能力。步骤如下导入业务 FastAPI 应用用它构造 MCP 实例创建一个全新的网关应用用mount_http(mcp_app)把 MCP 挂到网关上分别以不同端口启动网关业务应用随网关进程内运行from fastapi import FastAPI from examples.shared.apps.items import app as items_api # 业务服务 from fastapi_mcp import FastApiMCP # 1. 业务应用只作为工具生成源 mcp FastApiMCP(items_api) # 2. 创建独立的网关应用 mcp_app FastAPI(title独立MCP网关) # 3. 挂到网关应用业务 REST 接口不暴露在网关上 mcp.mount_http(mcp_app) if __name__ __main__: import uvicorn uvicorn.run(mcp_app, host0.0.0.0, port8000)uvicorn mcp_gateway:mcp_app --host 0.0.0.0 --port 8000运行效果客户端只连得到/mcp端点业务 REST 路由不在网关应用中注册。⚠️ 所谓独立部署是独立的 ASGI 应用与端口不是跨进程 RPCFastApiMCP通过 ASGI 在进程内调用业务应用对象因此业务应用必须能被网关进程 import。两个服务无法分属不同主机后仅靠网络互通。HTTP 与 SSE 传输怎么选mount_http()实现的是 Streamable HTTP 规范带状态化会话管理0.4.0 起是默认推荐方式端点为/mcp。mount_sse()面向旧版客户端端点为/sse消息走{路径}/messages/子路由。新客户端一律选 HTTP仅当必须兼容不支持 Streamable HTTP 的旧客户端时才用 SSE。两者都支持传入自定义APIRouter并指定挂载路径from fastapi import APIRouter router APIRouter(prefix/api/v1) # 挂到自定义路径最终端点为 /api/v1/my-mcp-service mcp.mount_http(router, mount_path/my-mcp-service) app.include_router(router)工具清单的精细控制与注册时机工具集合在FastApiMCP(app)构造时一次性生成支持按 tag 或 operation_id 过滤两组参数各自互斥# 只暴露 items 标签的接口搜索接口不进工具列表 mcp FastApiMCP(items_api, include_tags[items])构造之后再新增的端点不会自动出现需要手动刷新app.get(/new/endpoint/, operation_idnew_endpoint) async def new_endpoint(): 构造后新增的端点 return {message: Hello, world!} # 重新生成工具列表新端点才会出现在 list_tools 中 mcp.setup_server()⚠️ 工具注册时机是最高频的坑忘记调用mcp.setup_server()时客户端会看到一份永远缺最新接口的工具列表且没有任何报错。配置与扩展能力只列有决策价值的配置项FastApiMCP构造参数配置项默认值说明适用场景include_tags/exclude_tagsNone按标签过滤工具二者互斥只暴露部分模块接口include_operations/exclude_operationsNone按 operation_id 过滤工具二者互斥精确到单个接口的取舍headers[authorization]工具调用时透传给后端的请求头白名单认证接口的身份传递http_clientASGI 传输超时 10 秒自定义httpx.AsyncClient慢接口调大超时如timeout20describe_all_responses/describe_full_response_schemaFalse是否把所有响应 Schema 写入工具描述提升模型对返回结构的推断auth_configNoneOAuth 2.0 配置dependencies、issuer、setup_proxies等对接企业级 OAuth 提供方mount_path/mcpHTTP//sseSSE挂载路径可配合自定义APIRouter多版本网关的路径规划auth_config依赖 OAuth 2.0 规范2025-03-26 版setup_proxiesTrue时会自动在你现有 OAuth 提供方周围生成 MCP 合规的代理端点并默认启用模拟动态客户端注册。生产落地要点高可用网关实例多副本部署在负载均衡之后0.4.0 引入有状态会话管理扩容前先验证同一客户端的会话是否会落到同一实例避免会话状态丢失。由于工具调用走进程内 ASGI网关与业务应用是同一进程整体扩容时以进程为单位整体复制无需为两者单独规划容量。安全给AuthConfig传入会抛出 401/403 的Depends()依赖这是触发 MCP 客户端发起 OAuth 流程的必要条件认证逻辑直接复用你 FastAPI 里现成的依赖。对外一律走 HTTPSheaders透传白名单保持最小化默认只透传authorization不要随意扩大。可观测启用examples/shared/setup.py提供的setup_logging()网关启动时会输出 MCP 挂载路径与监听状态方便确认注册结果。盯住工具调用的超时率与耗时内部调用受http_client超时默认 10 秒约束超时率突增是后端接口变慢的第一信号。排错速查现象原因解决方式客户端连/mcp返回 404/405使用了弃用的mount()或传输协议与路径不匹配改用mount_http()确认客户端指向/mcp新增接口不出现在工具列表工具列表在构造时一次性生成调用mcp.setup_server()重新注册慢接口调用报超时内部调用默认超时 10 秒传入httpx.AsyncClient(timeout20)构造时抛ValueErrorinclude与exclude两组过滤参数同时传入只保留一组过滤参数启用认证后客户端不触发 OAuth 流程AuthConfig.dependencies未配置无法返回 401传入抛出 401/403 的Depends()依赖收尾项目当前版本 0.4.0Streamable HTTP 传输为默认方式SSE 保留做向后兼容后续演进集中在 mcp SDK 版本跟进与有状态会话管理。深度阅读可从examples/目录的九组示例、docs/advanced/deploy.mdx独立部署文档以及CONTRIBUTING.md贡献指南入手。【免费下载链接】fastapi_mcpExpose your FastAPI endpoints as Model Context Protocol (MCP) tools, with Auth!项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi_mcp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考