三步搭出零配置MCP网关：FastAPI分布式部署实战
【免费下载链接】fastapi_mcpExpose your FastAPI endpoints as Model Context Protocol (MCP) tools, with Auth!项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi_mcp
3 个 FastAPI 服务，0 行胶水代码：FastAPI-MCP 会把每个端点自动转成 MCP 工具，把整套服务暴露成零配置的 MCP 网关，接管微服务通信的最后一公里。下面从装包到独立网关本地跑通，全程照着做即可。
5分钟跑通第一个MCP网关
先确认环境：Python 3.8 以上，FastAPI 0.100.0 以上。装包一条命令：
uv add fastapi-mcp # 或 pip install fastapi-mcp然后是完整的最小可运行示例：
from fastapi import FastAPI from fastapi_mcp import FastApiMCP app = FastAPI(title="商品服务") @app.get("/items/{item_id}") async def read_item(item_id: int, q: str | None = None): return {"item_id": item_id, "q": q} mcp = FastApiMCP(app) # 读完 OpenAPI，端点逐个变成 MCP 工具 mcp.mount_http() # 挂到默认路径 /mcp if __name__ == "__main__": import uvicorn uvicorn.run(app, host="0.0.0.0", port=8000)启动后用 MCP Inspector 验证：另开终端执行npx @modelcontextprotocol/inspector，地址填http://127.0.0.1:8000/mcp，Tools 面板点 List Tools，能看到read_item就说明链路通了。
从写完FastApiMCP(app)那一刻起，所有接口都已是 MCP 工具，你一行包装代码都不用写。
MCP网关在系统里的位置：三种部署模式对比
| 部署模式 | 做法 | 适合场景 |
|---|---|---|
| 单进程内嵌 | mount_http()不传参，网关与业务同进程 | 单服务、快速验证 |
| 独立网关 | FastApiMCP(业务app)后mount_http(mcp_app)，挂到新建的空应用上 | 聚合多个业务服务，业务 HTTP 接口不再直接对外 |
| 多实例 + 负载均衡 | 独立网关起多份，前面挂负载均衡器 | 生产环境高可用 |
独立模式有两个值得注意的细节。第一，默认情况下网关进程内通过 ASGI 直接调用业务应用的路由，不走网络往返，所以"分开部署"指的是分开两个 FastAPI 应用、分开两份配置，而不是必须拆成两台机器。第二，业务应用的原始 HTTP 接口不会随网关一起暴露出去，外部只能经 MCP 协议访问。完整写法见 独立部署示例。
需要真正跨机器调用远端服务时，给FastApiMCP传一个设置了base_url的httpx.AsyncClient，调用就会走真实网络。
SSE还是HTTP：一张表选明白
| 对比项 | mount_http() | mount_sse() |
|---|---|---|
| 协议规范 | MCP Streamable HTTP（最新） | SSE（旧版） |
| 默认挂载路径 | /mcp | /sse |
| 会话管理 | 支持可选会话，连接处理更健壮 | 长连接事件流 |
| 适合客户端 | 新版客户端，或mcp-remote桥接 | 只支持 SSE 的旧客户端 |
新项目直接选 HTTP；只有需要兼容旧客户端时才上 SSE。
挂载路径也可以自定义，挂到APIRouter上时mount_path会接在 router 的 prefix 后面：
from fastapi import APIRouter router = APIRouter(prefix="/api/v1") mcp.mount_http(router, mount_path="/my-mcp") # 最终路径 /api/v1/my-mcp app.include_router(router)客户端怎么接：两套JSON配置
主流 MCP 客户端（Claude Desktop、Cursor、Windsurf 等）用同一套mcpServers格式，只改 URL。HTTP 传输：
{ "mcpServers": { "fastapi-mcp": { "url": "http://localhost:8000/mcp" } } }SSE 传输把 URL 换成/sse：
{ "mcpServers": { "fastapi-mcp": { "url": "http://localhost:8000/sse" } } }客户端只支持 stdio、或需要走 OAuth 流程时，用npx mcp-remote做桥接，具体写法见 快速入门 里的 mcp-remote 一节。
MCP网关生产部署检查清单
- 启用 OAuth 认证：构造
AuthConfig传入FastApiMCP，字段含义见 认证文档；网关默认会把authorization头转发给业务接口，token 透传写法参考 Token 透传示例 - 前置 HTTPS 终结：把 TLS 交给网关前面的反向代理，网关实例之间走内网
- 配置请求限流：在负载均衡器或反向代理层按来源限流，挡住异常放大
- 接入指标与日志：Prometheus 采集网关指标，日志格式复用
examples/shared/setup.py里的setup_logging() - 处理会话粘连：HTTP 传输按会话管理连接，多实例部署时给负载均衡器开启粘滞路由
容易踩的坑：4个常见误区
- 误区：mount 之后再补端点，以为会自动注册。工具列表在
FastApiMCP(...)构造时一次性生成，之后不会跟着路由表更新。正解：把端点定义全部放在构造调用之前；确需后补的，调用mcp.setup_server()重建，见 工具重注册示例。 - 误区：以为网关能自动发现远端微服务。它只读取你传入的那个应用，默认还是进程内调用。正解：跨机器时在构造参数里注入带
base_url的httpx.AsyncClient。 - 误区：客户端 URL 与挂载路径不一致。HTTP 默认
/mcp、SSE 默认/sse，走APIRouter时 prefix 也是路径的一部分。正解：客户端url填完整最终路径，与网关日志里打印的监听路径逐字对齐。 - 误区：慢接口照跑不误。内置 HTTP 客户端超时偏短，长耗时接口会被掐断。正解：注入自定义客户端调超时，见 超时配置示例。
继续深入
- 快速入门：从零到客户端连通的完整流程，含 mcp-remote 用法
- 认证配置：
AuthConfig字段与 OAuth 代理的完整说明 - 部署指南：更多生产部署场景
- 贡献指南：想给项目提代码，从这里找入口
如果网关已经接上客户端，下一步建议读 工具命名规范，给多个服务统一一套工具命名；卡住的问题先翻 FAQ。
【免费下载链接】fastapi_mcpExpose your FastAPI endpoints as Model Context Protocol (MCP) tools, with Auth!项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi_mcp
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
