1. 為什么要把 FastAPI 接口變成 MCP 服務如果你手里已經(jīng)有一堆跑得好好的 FastAPI 接口比如查用戶、查訂單、寫文檔、跑批處理現(xiàn)在想讓 Claude、Cursor 這類支持 MCP 的客戶端直接調(diào)用它們最直接的想法通常是「再寫一個 MCP Server 包一層」。但真動手就會發(fā)現(xiàn)工具描述要重寫、參數(shù) schema 要重寫、鑒權(quán)邏輯要重寫接口一改還得同步改兩處維護成本直接翻倍。FastAPI-MCP 解決的正是這個痛點。它是一個零配置工具能把你現(xiàn)有的 FastAPI 端點自動暴露成 MCP 兼容的工具保留原有的路由、參數(shù)模型和 OpenAPI 文檔不需要你重寫業(yè)務邏輯也不需要單獨維護一套工具定義。簡單說你原來怎么寫 FastAPI現(xiàn)在還怎么寫MCP 服務是「掛」上去的。它適合誰三類人最受益一是已經(jīng)有成熟 FastAPI 后端、想快速接入 AI 客戶端的后端工程師二是做 AI Agent、需要把內(nèi)部系統(tǒng)能力暴露給模型的開發(fā)者三是想用統(tǒng)一 Key 管理多家模型調(diào)用、又不想在 MCP 配置里到處填 Key 的人。這篇就聚焦一個完整鏈路用 FastAPI-MCP 把接口轉(zhuǎn)成 MCP 服務再用 TaoToken 的統(tǒng)一 Key 和 API 通道完成調(diào)用配置最后用一次真實工具調(diào)用驗證整條鏈路是通的。核心檢索詞先明確FastAPI-MCP 是什么、能做什么、適合誰。它是什么——把 FastAPI 端點轉(zhuǎn)成 MCP 工具的開源庫能做什么——自動轉(zhuǎn)換、保留架構(gòu)、可過濾端點、可獨立部署適合誰——有 FastAPI 存量接口、想接 MCP 客戶端的開發(fā)者。下面從環(huán)境準備一路走到驗證請求。2. TaoToken 前置準備統(tǒng)一 Key 與 Base URL 怎么填在動手寫 MCP 配置之前先把模型側(cè)的通道準備好。TaoToken 在這里的角色是統(tǒng)一 Key 和 API 通道你不需要在 MCP 客戶端里為每個模型單獨配一套 Key而是用同一個 Key、同一個 Base URL 去訪問不同模型。這對 MCP 場景特別友好因為 MCP 客戶端配置里通常只能填一組 Base URL 和 Key統(tǒng)一通道能省掉大量重復配置。第一步拿到你的 API Key。訪問 https://taotoken.net/api-keys 創(chuàng)建或復制一個 Key。這個 Key 就是后面所有配置里api_key字段的值注意不要把它提交到 Git 倉庫建議用環(huán)境變量或本地配置文件管理。第二步確認 Base URL。TaoToken 的 API 入口是 https://taotoken.net/api注意這個地址不帶任何查詢參數(shù)直接作為base_url使用。很多客戶端要求 Base URL 以/v1結(jié)尾具體看你用的客戶端文檔但 TaoToken 的入口就是上面這個不要自己拼多余的路徑。第三步確認你要用的 Model ID。這一步很關(guān)鍵因為 MCP 客戶端配置里必須寫全三件套Base URL、Key、Model ID。Model ID 要和你實際調(diào)用的模型一致比如你在模型對話里用的是哪個模型配置里就填哪個?？梢韵鹊?https://taotoken.net/models 或模型對話頁面確認可用模型列表避免填了一個不存在的 ID 導致 404。這里給一個通用的三件套對照方便你后面往不同客戶端里填配置項填寫值說明Base URLhttps://taotoken.net/api統(tǒng)一 API 入口不帶 UTMAPI Key你在 api-keys 頁面創(chuàng)建的 Key建議用環(huán)境變量注入Model ID你實際調(diào)用的模型標識與模型對話頁保持一致如果你后面要用 Claude Code 這類編碼工具或者用 Cline、Codex 這類支持 MCP 的客戶端三件套的填法是一致的區(qū)別只在配置文件的字段名。比如 Claude Code 的配置里會涉及ANTHROPIC_BASE_URL和ANTHROPIC_API_KEYCodex 的auth.json里則是另一套字段名但值都來自上面這張表。先把這三樣準備好后面配置就不會卡在「Key 填哪」這種問題上。注意TaoToken 是合規(guī)的 API 通道服務配置時只填官方給出的 Base URL不要自行拼接或使用來路不明的地址。Key 泄露后請立即在控制臺重置。3. 可復制配置FastAPI-MCP 注冊與客戶端接入這一節(jié)是全文的核心給你可以直接復制的配置片段。先裝依賴再寫 FastAPI 應用然后掛載 MCP最后把客戶端配置填好。先安裝 FastAPI-MCP。推薦用 uv速度快uv add fastapi-mcp如果你習慣 pippip install fastapi-mcp接著寫一個最小的 FastAPI 應用把 MCP 掛上去。注意operation_id一定要顯式寫否則 FastAPI 自動生成的名字會像read_user_users__user_id__get這種模型很難正確調(diào)用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。如果你只想暴露部分端點用過濾參數(shù)控制比如只暴露用戶相關(guān)接口mcp FastApiMCP( app, include_operations[get_user_info], include_tags[public], )接下來是客戶端配置。以支持 SSE 的客戶端為例MCP 配置片段如下注意這里把模型側(cè)的三件套也一并寫進去因為很多客戶端在調(diào)用工具后需要模型來決策下一步{ 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 填你實際調(diào)用的模型。Cline 的 MCP 配置也是類似結(jié)構(gòu)把mcpServers段填好即可。Codex 的auth.json里則要寫OPENAI_BASE_URL和OPENAI_API_KEY值同樣來自三件套。提示配置文件里的 Key 建議用環(huán)境變量引用比如${TAOTOKEN_API_KEY}避免明文寫死在 JSON 里。不同客戶端對環(huán)境變量的支持程度不同先查一下你用的客戶端文檔。配置寫完后重啟客戶端讓它重新加載 MCP 服務列表。正常情況下你能在工具列表里看到get_user_info和get_order_detail這兩個工具說明 FastAPI 端點已經(jīng)成功轉(zhuǎn)成了 MCP 工具。4. 驗證請求一次真實工具調(diào)用跑通鏈路配置寫完不算完得用一次真實調(diào)用證明鏈路是通的。這一步分兩段先直接驗證 MCP 服務本身能響應再通過客戶端觸發(fā)一次工具調(diào)用。先驗證 MCP 服務端點。啟動你的 FastAPI 應用后用 curl 探一下 MCP 的 SSE 端點是否活著curl -N http://localhost:8000/mcp如果返回的是 SSE 事件流而不是 404說明 MCP 服務已經(jīng)掛載成功。這一步能排除「服務沒起來」這類低級問題。接著在客戶端里發(fā)起一次工具調(diào)用。以支持 MCP 的客戶端為例你可以直接對模型說「幫我查一下 user_id 為 42 的用戶信息」。模型會先通過 MCP 發(fā)現(xiàn)get_user_info工具然后發(fā)起調(diào)用你的 FastAPI 端點收到請求并返回{user_id: 42, name: user_42}模型拿到結(jié)果后會把自然語言答案返回給你。整個過程你能在客戶端日志里看到工具調(diào)用的入?yún)⒑统鰠⑦@就是鏈路跑通的證據(jù)。如果你想更直接地驗證模型側(cè)通道可以單獨發(fā)一次請求確認 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 服務是兩條獨立的鏈路分開驗證能快速定位問題出在哪一側(cè)如果 curl 模型接口通、但客戶端工具調(diào)用失敗問題多半在 MCP 配置如果兩邊都不通先查 Key 和 Base URL。實測下來最容易出問題的不是代碼而是配置里的字段名和路徑。比如有的客戶端要求 SSE URL 帶/sse后綴有的直接用/mcp這個要以你客戶端文檔為準。FastAPI-MCP 默認掛載在/mcp如果你改了掛載路徑客戶端配置也要同步改。5. 本篇常見錯排查401、local proxy failed、reading choices這一節(jié)把幾個高頻報錯對照著講都是實際配置時會撞上的。401 Unauthorized。這個幾乎都是 Key 的問題。先確認你填的是 TaoToken 的 Key而不是別的平臺的再確認 Key 沒有多余空格JSON 里字符串不要帶換行最后確認 Base URL 是https://taotoken.net/api沒有拼錯。如果 Key 剛重置過舊 Key 會立即失效記得同步更新所有配置文件。local proxy failed / connection refused。這個通常出現(xiàn)在 MCP 客戶端連本地服務時。檢查你的 FastAPI 應用是否真的在localhost:8000上跑著端口有沒有被占用防火墻有沒有攔。如果你把 MCP 服務獨立部署在另一臺機器上base_url要改成那臺機器的實際地址不能還寫localhost。reading choices 報錯 / choices 字段為空。這個多半是模型側(cè)返回異常。先確認 Model ID 填對了填了一個不存在的模型會直接報錯再確認請求體格式符合 OpenAI 兼容規(guī)范messages是數(shù)組、model是字符串。如果返回里choices是空數(shù)組檢查一下是不是觸發(fā)了內(nèi)容過濾或參數(shù)越界。OAuth 相關(guān)報錯。有些客戶端在連遠程 MCP 服務時會走 OAuth 流程如果你用的是本地 SSE一般不需要 OAuth。如果客戶端強制要求 OAuth檢查它的 MCP 配置里transport是不是寫成了sse寫錯成http或streamable-http可能觸發(fā)不同的鑒權(quán)路徑。工具列表為空。MCP 服務起來了但客戶端看不到工具先檢查operation_id有沒有顯式寫。沒寫的話工具名是自動生成的可能被客戶端過濾掉。再檢查include_operations和include_tags有沒有把端點排除掉。最后確認客戶端重啟過很多客戶端不會熱加載 MCP 配置。改了接口但工具沒更新。FastAPI-MCP 創(chuàng)建后新增的端點不會自動出現(xiàn)需要調(diào)用mcp.setup_server()刷新。如果你是在運行中動態(tài)加路由記得在加完之后調(diào)一次這個方法。排障時建議按「模型通道 → MCP 服務 → 客戶端配置」的順序逐段驗證每段用 curl 或日志確認不要一上來就懷疑代碼。大部分問題都出在配置字段和路徑上而不是 FastAPI-MCP 本身。6. 把鏈路固定下來長期編碼與 Agent 場景的接入建議鏈路跑通之后下一步是把它固定成可復用的配置而不是每次手動改。如果你只是偶爾驗證一下模型用模型對話頁面就夠了但如果你要把這套 MCP 服務長期掛在編碼工具或 Agent 里用建議走 Coding Plan 這類長期方案把 Key 和通道管理集中起來避免每個項目單獨配一套。具體做法上我建議把三件套抽成環(huán)境變量在多個客戶端之間共享export TAOTOKEN_BASE_URLhttps://taotoken.net/api export TAOTOKEN_API_KEY你的_TaoToken_Key export TAOTOKEN_MODEL_ID你的_Model_ID然后在各客戶端的配置里引用這些變量。這樣換 Key 或換模型時只改一處不用滿倉庫找配置文件。FastAPI-MCP 那邊則把operation_id命名規(guī)范固定下來比如統(tǒng)一用動詞_資源的格式模型調(diào)用準確率會明顯提升。如果你要把 MCP 服務部署到測試環(huán)境給團隊用記得把base_url從localhost改成實際域名并且給 MCP 端點加上鑒權(quán)別讓內(nèi)部接口裸奔。FastAPI-MCP 支持獨立部署API 和 MCP 可以跑在不同端口這樣安全邊界更清晰。最后一步把驗證腳本也固化下來。寫一個verify.sh里面就兩件事curl 一次模型接口確認通道正常curl 一次 MCP 端點確認服務活著。每次改完配置跑一遍比在客戶端里點來點去快得多。這套流程跑順之后你新增一個 FastAPI 端點只要補上operation_id、調(diào)一次setup_server()客戶端就能直接用幾乎零額外成本。