用FastAPI-MCP搭起分布式MCP网关从单进程到多节点【免费下载链接】fastapi_mcpExpose your FastAPI endpoints as Model Context Protocol (MCP) tools, with Auth!项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi_mcp假设业务团队要求把一套现成的 FastAPI 后端接进 MCP 客户端逐条端点手工注册成工具显然不现实。FastAPI-MCP 做的事情很直接自动把一个 FastAPI 应用的端点转成 MCP 服务省去了手动注册工具的步骤。本文按部署这条线展开——先用 30 秒跑通一个最小网关再把它拆成独立进程然后处理传输协议选型、客户端接入、多节点横向扩展最后过一遍认证、日志和上线前的检查项。 第1步30秒跑通一个最小网关先装依赖。官方推荐用 uv一个更快的 Python 包安装器传统 pip 同样可用环境要求 Python 3.10推荐 3.12uv add fastapi-mcp # 或者 pip install fastapi-mcp下面这段代码完成FastAPI 应用 → MCP 网关的最短路径四行核心逻辑from fastapi import FastAPI from fastapi_mcp import FastApiMCP app FastAPI(titleMCP网关示例) app.get(/items/{item_id}) async def read_item(item_id: int, q: str None): return {item_id: item_id, q: q} # FastApiMCP 扫描 app 的全部端点并生成对应的 MCP 工具 mcp FastApiMCP(app) # 挂载 HTTP 传输默认监听 8000 端口的 /mcp 路径 mcp.mount_http() if __name__ __main__: import uvicorn uvicorn.run(app, host0.0.0.0, port8000)跑起来之后http://localhost:8000/mcp就是一个可用的 MCP 服务端点。端点的请求模型、响应 schema 和 Swagger 里的文档描述都会保留到工具定义里这一步不需要任何额外配置。安装细节可以看安装文档。 第2步把网关拆成独立进程单进程形态适合起步但业务 API 和 MCP 端点混在同一个应用里两者只能一起发布、一起扩容。在分布式部署里更常见的做法是让 MCP 网关作为一个独立应用存在它引用业务服务做工具源自己只对外暴露 MCP 协议。仓库里的 examples/04_separate_server_example.py 演示了这种拆法from fastapi import FastAPI from fastapi_mcp import FastApiMCP # 1. 业务服务一个现成的 FastAPI 应用 from examples.shared.apps.items import app as items_api # 2. 网关只拿业务服务当工具源不暴露它的原始端点 mcp FastApiMCP(items_api) # 3. 网关是另一个独立的 FastAPI 应用 mcp_app FastAPI(title独立MCP网关) mcp.mount_http(mcp_app) # 4. 单独启动网关进程 if __name__ __main__: import uvicorn uvicorn.run(mcp_app, host0.0.0.0, port8000)注意这里的一个安全细节原始 API 不会被网关直接暴露外部只能经由 MCP 协议访问这相当于给后端加了一层协议边界。两个进程这样启动# 终端1业务服务端口 8001 uvicorn examples.shared.apps.items:app --host 0.0.0.0 --port 8001 # 终端2MCP 网关端口 8000 uvicorn --factory 或直接运行 examples/04_separate_server_example.py监听 0.0.0.0:8000拆分之后网关和业务服务可以独立扩缩容、独立发版。如果网关想挂到自定义路径下mount_http支持传入 router 和mount_path参数例如挂到/api/v1前缀的路由上更细的路由定制见配置定制文档。⚡ 第3步MCP传输协议二选一FastAPI-MCP 提供两种传输协议选择取决于客户端版本HTTP 传输推荐mcp.mount_http()实现最新的 MCP Streamable HTTP 规范会话管理和连接处理更完善默认端点是/mcp。SSE 传输向后兼容mcp.mount_sse()Server-Sent Events 长连接主要服务于旧版 MCP 客户端默认端点是/sse。两种协议都支持挂到自定义路由上写法一致只是换掉方法名mcp.mount_http(router, mount_path/my-http) # 或者 mcp.mount_sse(router, mount_path/my-sse)两个容易踩的点第一目前没有 WebSocket 传输有实时推送需求要另找方案第二做接口版本管理时建议在 URL 路径里带版本段如/api/v1/items不同大版本部署各自的网关实例而不是让一个网关混着两套语义。协议细节见传输协议文档。第4步接入 MCP 客户端客户端侧只关心一个 URL。按传输协议不同配置分别是{ mcpServers: { fastapi-mcp: { url: http://mcp-gateway:8000/mcp } } }若网关走 SSE 传输把 URL 换成http://mcp-gateway:8000/sse即可JSON 结构不变。如果第2步里改过mount_path这里的 URL 要同步成实际挂载路径——客户端不感知服务内部结构只认 URL这也是拆进程后配置最轻的地方。第5步横向扩展成多节点单机跑通之后扩展思路是标准的前置负载均衡 无共享状态的后端集群MCP 客户端 ──► 负载均衡器 ──► 网关实例 1 ─┐ ├──► 网关实例 2 ├──► FastAPI 后端服务集群 └──► 网关实例 3 ─┘每个网关实例只是把同一套 FastAPI 端点转成工具网关之间不需要互相通信直接水平复制即可。负载均衡器负责分发请求和做健康检查后端 FastAPI 服务同样可以按原有微服务方式组成集群。部署层面的完整讨论在部署文档。需要说明的边界网关目前不内置服务发现后端地址是静态配置的——通过环境变量或配置文件指定即可。服务多了之后版本管理、灰度切换这类事仍然要放在网关之外的编排层做。第6步上线前的检查清单生产环境的几件事按重要性排序认证FastAPI-MCP 直接复用应用里已有的 FastAPI 依赖Depends()做鉴权也就是说业务接口上挂的令牌校验会自动作用到对应的 MCP 工具上不需要写一套平行的认证逻辑。具体配置API 密钥、Auth0 等见认证文档和 examples/08_auth_example_token_passthrough.py。传输与限流对外入口始终走 HTTPS在负载均衡层配置请求速率限制挡住异常的刷量请求。日志仓库提供了一个现成的日志配置一行调用即可让 uvicorn 和 fastapi_mcp 两个 logger 输出统一的格式from examples.shared.setup import setup_logging setup_logging()它定义在 examples/shared/setup.py基于dictConfig默认 DEBUG 级别上线前建议按需调低根 logger 级别。指标侧可以接 Prometheus 采集网关的请求量与延迟。已知局限无 WebSocket 传输、无内置服务发现、网关自身不做请求缓存——这三点决定了网关应该被当作协议转换层来定位而不是全能的 API 网关。清单过完一套多节点、带认证的 MCP 网关就成型了。下一步可以做的事情给业务服务的每个大版本各挂一个网关实例做灰度或者把网关层纳入你现有的 CI/CD 流水线让端点变更自动触发 MCP 工具的重新生成。更多边角问题见FAQ。【免费下载链接】fastapi_mcpExpose your FastAPI endpoints as Model Context Protocol (MCP) tools, with Auth!项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi_mcp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
用FastAPI-MCP搭起分布式MCP网关从单进程到多节点【免费下载链接】fastapi_mcpExpose your FastAPI endpoints as Model Context Protocol (MCP) tools, with Auth!项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi_mcp假设业务团队要求把一套现成的 FastAPI 后端接进 MCP 客户端逐条端点手工注册成工具显然不现实。FastAPI-MCP 做的事情很直接自动把一个 FastAPI 应用的端点转成 MCP 服务省去了手动注册工具的步骤。本文按部署这条线展开——先用 30 秒跑通一个最小网关再把它拆成独立进程然后处理传输协议选型、客户端接入、多节点横向扩展最后过一遍认证、日志和上线前的检查项。 第1步30秒跑通一个最小网关先装依赖。官方推荐用 uv一个更快的 Python 包安装器传统 pip 同样可用环境要求 Python 3.10推荐 3.12uv add fastapi-mcp # 或者 pip install fastapi-mcp下面这段代码完成FastAPI 应用 → MCP 网关的最短路径四行核心逻辑from fastapi import FastAPI from fastapi_mcp import FastApiMCP app FastAPI(titleMCP网关示例) app.get(/items/{item_id}) async def read_item(item_id: int, q: str None): return {item_id: item_id, q: q} # FastApiMCP 扫描 app 的全部端点并生成对应的 MCP 工具 mcp FastApiMCP(app) # 挂载 HTTP 传输默认监听 8000 端口的 /mcp 路径 mcp.mount_http() if __name__ __main__: import uvicorn uvicorn.run(app, host0.0.0.0, port8000)跑起来之后http://localhost:8000/mcp就是一个可用的 MCP 服务端点。端点的请求模型、响应 schema 和 Swagger 里的文档描述都会保留到工具定义里这一步不需要任何额外配置。安装细节可以看安装文档。 第2步把网关拆成独立进程单进程形态适合起步但业务 API 和 MCP 端点混在同一个应用里两者只能一起发布、一起扩容。在分布式部署里更常见的做法是让 MCP 网关作为一个独立应用存在它引用业务服务做工具源自己只对外暴露 MCP 协议。仓库里的 examples/04_separate_server_example.py 演示了这种拆法from fastapi import FastAPI from fastapi_mcp import FastApiMCP # 1. 业务服务一个现成的 FastAPI 应用 from examples.shared.apps.items import app as items_api # 2. 网关只拿业务服务当工具源不暴露它的原始端点 mcp FastApiMCP(items_api) # 3. 网关是另一个独立的 FastAPI 应用 mcp_app FastAPI(title独立MCP网关) mcp.mount_http(mcp_app) # 4. 单独启动网关进程 if __name__ __main__: import uvicorn uvicorn.run(mcp_app, host0.0.0.0, port8000)注意这里的一个安全细节原始 API 不会被网关直接暴露外部只能经由 MCP 协议访问这相当于给后端加了一层协议边界。两个进程这样启动# 终端1业务服务端口 8001 uvicorn examples.shared.apps.items:app --host 0.0.0.0 --port 8001 # 终端2MCP 网关端口 8000 uvicorn --factory 或直接运行 examples/04_separate_server_example.py监听 0.0.0.0:8000拆分之后网关和业务服务可以独立扩缩容、独立发版。如果网关想挂到自定义路径下mount_http支持传入 router 和mount_path参数例如挂到/api/v1前缀的路由上更细的路由定制见配置定制文档。⚡ 第3步MCP传输协议二选一FastAPI-MCP 提供两种传输协议选择取决于客户端版本HTTP 传输推荐mcp.mount_http()实现最新的 MCP Streamable HTTP 规范会话管理和连接处理更完善默认端点是/mcp。SSE 传输向后兼容mcp.mount_sse()Server-Sent Events 长连接主要服务于旧版 MCP 客户端默认端点是/sse。两种协议都支持挂到自定义路由上写法一致只是换掉方法名mcp.mount_http(router, mount_path/my-http) # 或者 mcp.mount_sse(router, mount_path/my-sse)两个容易踩的点第一目前没有 WebSocket 传输有实时推送需求要另找方案第二做接口版本管理时建议在 URL 路径里带版本段如/api/v1/items不同大版本部署各自的网关实例而不是让一个网关混着两套语义。协议细节见传输协议文档。第4步接入 MCP 客户端客户端侧只关心一个 URL。按传输协议不同配置分别是{ mcpServers: { fastapi-mcp: { url: http://mcp-gateway:8000/mcp } } }若网关走 SSE 传输把 URL 换成http://mcp-gateway:8000/sse即可JSON 结构不变。如果第2步里改过mount_path这里的 URL 要同步成实际挂载路径——客户端不感知服务内部结构只认 URL这也是拆进程后配置最轻的地方。第5步横向扩展成多节点单机跑通之后扩展思路是标准的前置负载均衡 无共享状态的后端集群MCP 客户端 ──► 负载均衡器 ──► 网关实例 1 ─┐ ├──► 网关实例 2 ├──► FastAPI 后端服务集群 └──► 网关实例 3 ─┘每个网关实例只是把同一套 FastAPI 端点转成工具网关之间不需要互相通信直接水平复制即可。负载均衡器负责分发请求和做健康检查后端 FastAPI 服务同样可以按原有微服务方式组成集群。部署层面的完整讨论在部署文档。需要说明的边界网关目前不内置服务发现后端地址是静态配置的——通过环境变量或配置文件指定即可。服务多了之后版本管理、灰度切换这类事仍然要放在网关之外的编排层做。第6步上线前的检查清单生产环境的几件事按重要性排序认证FastAPI-MCP 直接复用应用里已有的 FastAPI 依赖Depends()做鉴权也就是说业务接口上挂的令牌校验会自动作用到对应的 MCP 工具上不需要写一套平行的认证逻辑。具体配置API 密钥、Auth0 等见认证文档和 examples/08_auth_example_token_passthrough.py。传输与限流对外入口始终走 HTTPS在负载均衡层配置请求速率限制挡住异常的刷量请求。日志仓库提供了一个现成的日志配置一行调用即可让 uvicorn 和 fastapi_mcp 两个 logger 输出统一的格式from examples.shared.setup import setup_logging setup_logging()它定义在 examples/shared/setup.py基于dictConfig默认 DEBUG 级别上线前建议按需调低根 logger 级别。指标侧可以接 Prometheus 采集网关的请求量与延迟。已知局限无 WebSocket 传输、无内置服务发现、网关自身不做请求缓存——这三点决定了网关应该被当作协议转换层来定位而不是全能的 API 网关。清单过完一套多节点、带认证的 MCP 网关就成型了。下一步可以做的事情给业务服务的每个大版本各挂一个网关实例做灰度或者把网关层纳入你现有的 CI/CD 流水线让端点变更自动触发 MCP 工具的重新生成。更多边角问题见FAQ。【免费下载链接】fastapi_mcpExpose your FastAPI endpoints as Model Context Protocol (MCP) tools, with Auth!项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi_mcp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
