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