1. 为什么要把 FastAPI 接口变成 MCP 服务如果你手里已经有一堆跑得好好的 FastAPI 接口比如查用户、查订单、写文档、跑批处理现在想让 Claude、Cursor 这类支持 MCP 的客户端直接调用它们最直接的想法通常是「再写一个 MCP Server 包一层」。但真动手就会发现工具描述要重写、参数 schema 要重写、鉴权逻辑要重写接口一改还得同步改两处维护成本直接翻倍。FastAPI-MCP 解决的正是这个痛点。它是一个零配置工具能把你现有的 FastAPI 端点自动暴露成 MCP 兼容的工具保留原有的路由、参数模型和 OpenAPI 文档不需要你重写业务逻辑也不需要单独维护一套工具定义。简单说你原来怎么写 FastAPI现在还怎么写MCP 服务是「挂」上去的。它适合谁三类人最受益一是已经有成熟 FastAPI 后端、想快速接入 AI 客户端的后端工程师二是做 AI Agent、需要把内部系统能力暴露给模型的开发者三是想用统一 Key 管理多家模型调用、又不想在 MCP 配置里到处填 Key 的人。这篇就聚焦一个完整链路用 FastAPI-MCP 把接口转成 MCP 服务再用 TaoToken 的统一 Key 和 API 通道完成调用配置最后用一次真实工具调用验证整条链路是通的。核心检索词先明确FastAPI-MCP 是什么、能做什么、适合谁。它是什么——把 FastAPI 端点转成 MCP 工具的开源库能做什么——自动转换、保留架构、可过滤端点、可独立部署适合谁——有 FastAPI 存量接口、想接 MCP 客户端的开发者。下面从环境准备一路走到验证请求。2. TaoToken 前置准备统一 Key 与 Base URL 怎么填在动手写 MCP 配置之前先把模型侧的通道准备好。TaoToken 在这里的角色是统一 Key 和 API 通道你不需要在 MCP 客户端里为每个模型单独配一套 Key而是用同一个 Key、同一个 Base URL 去访问不同模型。这对 MCP 场景特别友好因为 MCP 客户端配置里通常只能填一组 Base URL 和 Key统一通道能省掉大量重复配置。第一步拿到你的 API Key。访问 https://taotoken.net/api-keys 创建或复制一个 Key。这个 Key 就是后面所有配置里api_key字段的值注意不要把它提交到 Git 仓库建议用环境变量或本地配置文件管理。第二步确认 Base URL。TaoToken 的 API 入口是 https://taotoken.net/api注意这个地址不带任何查询参数直接作为base_url使用。很多客户端要求 Base URL 以/v1结尾具体看你用的客户端文档但 TaoToken 的入口就是上面这个不要自己拼多余的路径。第三步确认你要用的 Model ID。这一步很关键因为 MCP 客户端配置里必须写全三件套Base URL、Key、Model ID。Model ID 要和你实际调用的模型一致比如你在模型对话里用的是哪个模型配置里就填哪个。可以先到 https://taotoken.net/models 或模型对话页面确认可用模型列表避免填了一个不存在的 ID 导致 404。这里给一个通用的三件套对照方便你后面往不同客户端里填配置项填写值说明Base URLhttps://taotoken.net/api统一 API 入口不带 UTMAPI Key你在 api-keys 页面创建的 Key建议用环境变量注入Model ID你实际调用的模型标识与模型对话页保持一致如果你后面要用 Claude Code 这类编码工具或者用 Cline、Codex 这类支持 MCP 的客户端三件套的填法是一致的区别只在配置文件的字段名。比如 Claude Code 的配置里会涉及ANTHROPIC_BASE_URL和ANTHROPIC_API_KEYCodex 的auth.json里则是另一套字段名但值都来自上面这张表。先把这三样准备好后面配置就不会卡在「Key 填哪」这种问题上。注意TaoToken 是合规的 API 通道服务配置时只填官方给出的 Base URL不要自行拼接或使用来路不明的地址。Key 泄露后请立即在控制台重置。3. 可复制配置FastAPI-MCP 注册与客户端接入这一节是全文的核心给你可以直接复制的配置片段。先装依赖再写 FastAPI 应用然后挂载 MCP最后把客户端配置填好。先安装 FastAPI-MCP。推荐用 uv速度快uv add fastapi-mcp如果你习惯 pippip install fastapi-mcp接着写一个最小的 FastAPI 应用把 MCP 挂上去。注意operation_id一定要显式写否则 FastAPI 自动生成的名字会像read_user_users__user_id__get这种模型很难正确调用from fastapi import FastAPI from fastapi_mcp import FastApiMCP app FastAPI() app.get(/users/{user_id}, operation_idget_user_info) async def read_user(user_id: int): return {user_id: user_id, name: fuser_{user_id}} app.get(/orders/{order_id}, operation_idget_order_detail) async def read_order(order_id: int): return {order_id: order_id, status: paid} mcp FastApiMCP( app, nameMy API MCP, descriptionMCP server for my FastAPI app, base_urlhttp://localhost:8000, ) mcp.mount() if __name__ __main__: import uvicorn uvicorn.run(app, host0.0.0.0, port8000)跑起来之后MCP 服务默认在http://localhost:8000/mcp。如果你只想暴露部分端点用过滤参数控制比如只暴露用户相关接口mcp FastApiMCP( app, include_operations[get_user_info], include_tags[public], )接下来是客户端配置。以支持 SSE 的客户端为例MCP 配置片段如下注意这里把模型侧的三件套也一并写进去因为很多客户端在调用工具后需要模型来决策下一步{ mcpServers: { my-fastapi-mcp: { url: http://localhost:8000/mcp, transport: sse } }, model: { base_url: https://taotoken.net/api, api_key: 你的_TaoToken_Key, model_id: 你的_Model_ID } }如果你用的是 Claude Code配置会落在 settings 里字段名不同但值一样。核心是三件套齐全Base URL 填https://taotoken.net/apiKey 填你在 api-keys 页面拿到的值Model ID 填你实际调用的模型。Cline 的 MCP 配置也是类似结构把mcpServers段填好即可。Codex 的auth.json里则要写OPENAI_BASE_URL和OPENAI_API_KEY值同样来自三件套。提示配置文件里的 Key 建议用环境变量引用比如${TAOTOKEN_API_KEY}避免明文写死在 JSON 里。不同客户端对环境变量的支持程度不同先查一下你用的客户端文档。配置写完后重启客户端让它重新加载 MCP 服务列表。正常情况下你能在工具列表里看到get_user_info和get_order_detail这两个工具说明 FastAPI 端点已经成功转成了 MCP 工具。4. 验证请求一次真实工具调用跑通链路配置写完不算完得用一次真实调用证明链路是通的。这一步分两段先直接验证 MCP 服务本身能响应再通过客户端触发一次工具调用。先验证 MCP 服务端点。启动你的 FastAPI 应用后用 curl 探一下 MCP 的 SSE 端点是否活着curl -N http://localhost:8000/mcp如果返回的是 SSE 事件流而不是 404说明 MCP 服务已经挂载成功。这一步能排除「服务没起来」这类低级问题。接着在客户端里发起一次工具调用。以支持 MCP 的客户端为例你可以直接对模型说「帮我查一下 user_id 为 42 的用户信息」。模型会先通过 MCP 发现get_user_info工具然后发起调用你的 FastAPI 端点收到请求并返回{user_id: 42, name: user_42}模型拿到结果后会把自然语言答案返回给你。整个过程你能在客户端日志里看到工具调用的入参和出参这就是链路跑通的证据。如果你想更直接地验证模型侧通道可以单独发一次请求确认 TaoToken 的 Base URL 和 Key 是有效的curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer 你的_TaoToken_Key \ -H Content-Type: application/json \ -d { model: 你的_Model_ID, messages: [{role: user, content: ping}] }返回里有choices字段就说明模型通道正常。这一步和 MCP 服务是两条独立的链路分开验证能快速定位问题出在哪一侧如果 curl 模型接口通、但客户端工具调用失败问题多半在 MCP 配置如果两边都不通先查 Key 和 Base URL。实测下来最容易出问题的不是代码而是配置里的字段名和路径。比如有的客户端要求 SSE URL 带/sse后缀有的直接用/mcp这个要以你客户端文档为准。FastAPI-MCP 默认挂载在/mcp如果你改了挂载路径客户端配置也要同步改。5. 本篇常见错排查401、local proxy failed、reading choices这一节把几个高频报错对照着讲都是实际配置时会撞上的。401 Unauthorized。这个几乎都是 Key 的问题。先确认你填的是 TaoToken 的 Key而不是别的平台的再确认 Key 没有多余空格JSON 里字符串不要带换行最后确认 Base URL 是https://taotoken.net/api没有拼错。如果 Key 刚重置过旧 Key 会立即失效记得同步更新所有配置文件。local proxy failed / connection refused。这个通常出现在 MCP 客户端连本地服务时。检查你的 FastAPI 应用是否真的在localhost:8000上跑着端口有没有被占用防火墙有没有拦。如果你把 MCP 服务独立部署在另一台机器上base_url要改成那台机器的实际地址不能还写localhost。reading choices 报错 / choices 字段为空。这个多半是模型侧返回异常。先确认 Model ID 填对了填了一个不存在的模型会直接报错再确认请求体格式符合 OpenAI 兼容规范messages是数组、model是字符串。如果返回里choices是空数组检查一下是不是触发了内容过滤或参数越界。OAuth 相关报错。有些客户端在连远程 MCP 服务时会走 OAuth 流程如果你用的是本地 SSE一般不需要 OAuth。如果客户端强制要求 OAuth检查它的 MCP 配置里transport是不是写成了sse写错成http或streamable-http可能触发不同的鉴权路径。工具列表为空。MCP 服务起来了但客户端看不到工具先检查operation_id有没有显式写。没写的话工具名是自动生成的可能被客户端过滤掉。再检查include_operations和include_tags有没有把端点排除掉。最后确认客户端重启过很多客户端不会热加载 MCP 配置。改了接口但工具没更新。FastAPI-MCP 创建后新增的端点不会自动出现需要调用mcp.setup_server()刷新。如果你是在运行中动态加路由记得在加完之后调一次这个方法。排障时建议按「模型通道 → MCP 服务 → 客户端配置」的顺序逐段验证每段用 curl 或日志确认不要一上来就怀疑代码。大部分问题都出在配置字段和路径上而不是 FastAPI-MCP 本身。6. 把链路固定下来长期编码与 Agent 场景的接入建议链路跑通之后下一步是把它固定成可复用的配置而不是每次手动改。如果你只是偶尔验证一下模型用模型对话页面就够了但如果你要把这套 MCP 服务长期挂在编码工具或 Agent 里用建议走 Coding Plan 这类长期方案把 Key 和通道管理集中起来避免每个项目单独配一套。具体做法上我建议把三件套抽成环境变量在多个客户端之间共享export TAOTOKEN_BASE_URLhttps://taotoken.net/api export TAOTOKEN_API_KEY你的_TaoToken_Key export TAOTOKEN_MODEL_ID你的_Model_ID然后在各客户端的配置里引用这些变量。这样换 Key 或换模型时只改一处不用满仓库找配置文件。FastAPI-MCP 那边则把operation_id命名规范固定下来比如统一用动词_资源的格式模型调用准确率会明显提升。如果你要把 MCP 服务部署到测试环境给团队用记得把base_url从localhost改成实际域名并且给 MCP 端点加上鉴权别让内部接口裸奔。FastAPI-MCP 支持独立部署API 和 MCP 可以跑在不同端口这样安全边界更清晰。最后一步把验证脚本也固化下来。写一个verify.sh里面就两件事curl 一次模型接口确认通道正常curl 一次 MCP 端点确认服务活着。每次改完配置跑一遍比在客户端里点来点去快得多。这套流程跑顺之后你新增一个 FastAPI 端点只要补上operation_id、调一次setup_server()客户端就能直接用几乎零额外成本。