1. 为什么要把 FastAPI 应用变成 MCP 服务器如果你手上已经有一套跑得好好的 FastAPI 服务接口文档齐全、Swagger 能打开、业务逻辑也稳定那它现在的服务对象基本还是「传统客户端」——前端页面、定时脚本、内部调用方。但这两年 AI 工具Cline、Cursor、Claude Desktop 这类开始需要一个统一的方式来「发现并调用」你的能力这个统一方式就是 MCPModel Context Protocol。MCP 解决的核心问题是AI 工具不再靠人肉写死每个接口的调用方式而是通过协议自动发现「有哪些工具可用、参数长什么样、返回什么结构」。FastAPI-MCP 这个库做的事情很直接——它把你 FastAPI 里已经注册好的路由自动转换成 MCP 工具挂载到一个/mcp路径下。你几乎不用改业务代码一行add_mcp_server就能让整套 API 被 AI 代理识别。这篇面向的是「已有 FastAPI 服务、希望被 AI 工具调用」的开发者。我会给出可复制的挂载代码、TaoToken 统一 Key 的config.toml配置骨架以及用 Cline 发起一次真实工具调用并核对返回结果的完整动作。适合谁手里有 FastAPI 项目、想让 Cline/Cursor 直接调用自己接口、又不想为每个接口单独写适配层的人。需要提前说清楚一个边界FastAPI-MCP 负责的是「暴露」它不负责模型推理。真正让 AI 工具理解并调用你的接口还需要一个稳定的模型通道。下面会用到 TaoToken 作为统一 Key 的接入通道把模型调用和 MCP 工具调用串起来。2. TaoToken 前置统一 Key 与 API 通道准备在动手挂载 MCP 之前先把模型通道准备好否则后面 Cline 里工具能发现、但对话跑不起来。TaoToken 在这里的角色是「统一 Key 统一 API 通道」你只需要一个 Key就能在 Cline、Cursor、Claude Code 这类工具里配置模型访问不用每个工具单独申请。第一步去控制台创建 API Key。打开 https://taotoken.net/console 登录后在 API Keys 页面新建一个 Key复制出来先存好。这个 Key 后面会写进config.toml。第二步确认 API 基地址。TaoToken 的 API 入口是 https://taotoken.net/api 注意这个地址不带任何查询参数配置时直接填这个即可。很多工具要求填base_url填错成带 UTM 的官网地址会连不上这是新手最容易踩的坑。第三步如果你打算长期用 Cline 做编码和 Agent 任务可以顺手看一下 Coding Plan 页面 https://taotoken.net/coding-plan 它面向的是持续性的编码场景比按次调用更适合日常开发。模型对话的入口在 https://taotoken.net/models 接入文档在 https://taotoken.net/doc 排障时这两个页面能省不少时间。注意Key 属于敏感凭证不要提交到 Git 仓库也不要在公开截图里露出。建议用环境变量或本地配置文件管理。到这里前置就绪一个 Key、一个 API 基地址。接下来进入 FastAPI-MCP 的挂载。3. 可复制配置FastAPI-MCP 挂载与 config.toml 骨架3.1 安装 FastAPI-MCP推荐用 uv速度更快依赖隔离也干净uv add fastapi-mcp如果你习惯 pippip install fastapi-mcp安装完成后确认版本能正常导入python -c import fastapi_mcp; print(fastapi_mcp.__version__)能打印出版本号就说明装好了。3.2 最小挂载代码假设你已有一个 FastAPI 应用比如下面这个带两个接口的服务from fastapi import FastAPI from fastapi_mcp import add_mcp_server app FastAPI(titleOrder Service) app.get(/orders/{order_id}) async def get_order(order_id: int): 根据订单号查询订单详情 return {order_id: order_id, status: paid, amount: 199.0} app.get(/health) async def health(): 健康检查 return {status: ok} # 关键一行挂载 MCP 服务器 mcp_server add_mcp_server( app, mount_path/mcp, nameOrder Service MCP, describe_all_responsesTrue, describe_full_response_schemaTrue, )describe_all_responsesTrue会把所有可能的响应模式都描述出来describe_full_response_schemaTrue提供完整 JSON Schema。这两个开关对 LLM 理解返回结构帮助很大尤其是返回字段多、有嵌套对象的时候建议打开。启动服务uvicorn main:app --host 0.0.0.0 --port 8000启动后MCP 服务器就在http://127.0.0.1:8000/mcp上。原来的 Swagger 文档依然在/docs两者互不影响。3.3 扩展自定义 MCP 工具除了自动转换的路由你还能手动加工具。比如加一个返回服务器时间的工具mcp_server.tool() async def get_server_time() - str: 获取服务器当前时间 from datetime import datetime return datetime.now().isoformat()这个工具不会出现在 FastAPI 的路由里但会出现在 MCP 工具列表中AI 工具能直接调用。3.4 TaoToken 统一 Key 的 config.toml 骨架Cline 这类工具支持用配置文件管理模型通道。下面是一个config.toml骨架把 TaoToken 的 Key 和 API 地址填进去# TaoToken 统一 Key 配置骨架 [provider] name taotoken base_url https://taotoken.net/api api_key sk-你的TaoToken密钥 model claude-sonnet-4-20250514 [mcp_servers.order_service] # FastAPI-MCP 暴露的地址 url http://127.0.0.1:8000/mcp transport sse [settings] timeout 60 max_retries 2几个要点base_url必须是https://taotoken.net/api不要带 UTM 参数api_key换成你在控制台创建的那个transport用sse因为 FastAPI-MCP 默认走 SSE。如果你的客户端不支持 SSE后面排障章节会讲 mcp-proxy 的替代方案。提示model字段按你实际可用的模型名填写具体可用模型可以在 https://taotoken.net/models 查看。4. 验证请求用 Cline 发起一次工具调用并核对结果配置写好了得验证它真的能跑通。这一步用 Cline 发起一次工具调用看返回结果对不对。4.1 确认 MCP 服务器已暴露先用 curl 探一下 MCP 端点是否活着curl -N http://127.0.0.1:8000/mcp如果返回 SSE 事件流能看到event:或data:开头的行说明 MCP 服务器正常。如果返回 404检查mount_path是否写对、服务是否真的启动在 8000 端口。4.2 在 Cline 中配置并连接打开 Cline 的 MCP 设置添加一个 SSE 类型的服务器URL 填http://127.0.0.1:8000/mcp。保存后 Cline 会自动拉取工具列表。正常情况下你应该能看到get_order、health、get_server_time这几个工具。如果工具列表是空的先确认 FastAPI 服务在跑再确认 Cline 里填的 URL 没有多余斜杠。4.3 发起一次真实调用在 Cline 对话框里输入帮我调用 get_order 工具查询订单号 1001 的状态Cline 会识别到get_order这个工具构造参数order_id1001发起调用。预期返回{ order_id: 1001, status: paid, amount: 199.0 }核对三个点order_id是不是 1001、status是不是paid、amount是不是 199.0。三个都对说明从 FastAPI 路由到 MCP 工具再到 AI 调用的整条链路是通的。4.4 再验证一个自定义工具接着输入调用 get_server_time 工具告诉我服务器当前时间返回应该是一个 ISO 格式的时间字符串比如2025-06-01T10:23:45.123456。这个工具不在 FastAPI 路由里能调通说明自定义扩展也生效了。到这里验证动作完成MCP 服务器暴露正常、工具自动发现正常、自定义工具正常、AI 调用返回结果正确。5. 本篇常见错排查5.1 挂载后访问 /mcp 返回 404最常见的原因是mount_path和实际访问路径不一致。add_mcp_server(app, mount_path/mcp)意味着访问地址是http://host:port/mcp不是/mcp/也不是/api/mcp。另外确认服务是用uvicorn main:app启动的main是文件名、app是 FastAPI 实例名写错会导致路由根本没注册。5.2 Cline 里工具列表为空先 curl 确认/mcp有 SSE 响应。如果 curl 正常但 Cline 空多半是 URL 填错或 transport 类型选错。FastAPI-MCP 默认 SSECline 里要选 SSE 而不是 stdio。还有一种情况是 Cline 缓存了旧的工具列表重启 Cline 或重新加载 MCP 服务器即可。5.3 模型调用报 401 或鉴权失败检查config.toml里的api_key是否完整、有没有多余空格。base_url必须是https://taotoken.net/api如果误填成带 UTM 的官网地址会鉴权失败。Key 如果泄露过去控制台重新生成一个。5.4 客户端不支持 SSE 怎么办Claude Desktop 这类客户端只支持 stdio这时用 mcp-proxy 做一层转换uv tool install mcp-proxy然后在claude_desktop_config.json里配置{ mcpServers: { order-service-proxy: { command: mcp-proxy, args: [http://127.0.0.1:8000/mcp] } } }MacOS 下command要填 mcp-proxy 的完整路径用which mcp-proxy查出来。配置完重启 Claude Desktop它会自动发现所有 API 端点。5.5 工具调用超时默认超时可能偏短尤其是接口内部有数据库查询或外部请求时。在config.toml的[settings]里把timeout调大比如 120。同时确认 FastAPI 接口本身没有阻塞操作必要时改成异步。5.6 返回结构 LLM 看不懂如果 AI 工具拿到返回后不知道怎么解析检查是否打开了describe_all_responses和describe_full_response_schema。这两个开关会把响应模式完整暴露给 LLM字段多、嵌套深的时候尤其重要。6. 把模型通道和 MCP 工具串起来整条链路跑通后你会发现分工其实很清晰FastAPI-MCP 负责把已有接口「翻译」成 AI 能理解的工具TaoToken 负责提供稳定的模型通道。两者配合你的 FastAPI 服务就从一个「只能被传统客户端调用」的后端变成了「AI 代理能直接调用」的智能服务。如果你只是偶尔验证一下模型返回用模型对话页面就够了https://taotoken.net/models 。如果你打算长期用 Cline 做编码和 Agent 任务建议走 Coding Planhttps://taotoken.net/coding-plan 持续性场景下更省心。接入过程中遇到鉴权或配置问题先看接入文档https://taotoken.net/doc 大部分报错在里面都有对应说明。Key 管理和新建在控制台https://taotoken.net/api-keys 。最后留一个实操建议先把最小挂载代码跑通确认/mcp能返回 SSE再去 Cline 里配工具。很多人一上来就把自定义工具、复杂配置全堆上去结果出问题时分不清是挂载错了还是配置错了。分步验证每步都 curl 一下排障成本会低很多。