企业官网建设流程全解析

1. 为什么要把 FastAPI 应用变成 MCP 服务器

如果你手上已经有一套跑得好好的 FastAPI 服务，接口文档齐全、Swagger 能打开、业务逻辑也稳定，那它现在的服务对象基本还是「传统客户端」——前端页面、定时脚本、内部调用方。但这两年 AI 工具（Cline、Cursor、Claude Desktop 这类）开始需要一个统一的方式来「发现并调用」你的能力，这个统一方式就是 MCP（Model 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

如果你习惯 pip：

pip 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(title="Order 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", name="Order Service MCP", describe_all_responses=True, describe_full_response_schema=True, )

describe_all_responses=True会把所有可能的响应模式都描述出来，describe_full_response_schema=True提供完整 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_id=1001，发起调用。预期返回：

{ "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 默认 SSE，Cline 里要选 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 Plan：https://taotoken.net/coding-plan ，持续性场景下更省心。接入过程中遇到鉴权或配置问题，先看接入文档：https://taotoken.net/doc ，大部分报错在里面都有对应说明。Key 管理和新建在控制台：https://taotoken.net/api-keys 。

最后留一个实操建议：先把最小挂载代码跑通，确认/mcp能返回 SSE，再去 Cline 里配工具。很多人一上来就把自定义工具、复杂配置全堆上去，结果出问题时分不清是挂载错了还是配置错了。分步验证，每步都 curl 一下，排障成本会低很多。