FastAPI-MCP 把既有 FastAPI 路由轉成 AI 可呼叫的 MCP 工具。你已經有 API、想讓 Codex 查訂單狀態時很適合;從零寫幾個 Python 工具,直接用 MCP SDK 或 FastMCP 比較簡單。這裡指的是 Tadata 的 fastapi-mcp 套件。
本文用同一個 API 示範「公開查詢、排除管理操作」,並在 Codex 內真的查一筆訂單與一個不存在的編號。
安裝:獨立環境固定相容版本
需要 uv、Python 3.12 與 Codex CLI。在空專案的 PowerShell 執行:
uv venv --python 3.12 .venv
uv pip install --python .venv\Scripts\python.exe fastapi-mcp==0.4.0 mcp==1.30.0 uvicorn==0.54.0
SDK 1.30.0 是這次驗證的相容組合。不要把它裝進另一個使用 SDK 2 的教學環境。
將以下完整程式存成 app.py:
from fastapi import FastAPI, HTTPException
from fastapi_mcp import FastApiMCP
app = FastAPI()
@app.get('/orders/{order_id}', operation_id='read_order')
def read_order(order_id: int):
"""Read a sample order status without modifying it."""
if order_id != 1:
raise HTTPException(status_code=404, detail='Order not found')
return {'order_id':1, 'status':'processing', 'total_cents':20000}
@app.post('/internal/reset', operation_id='internal_reset')
def internal_reset():
"""Placeholder administrative operation excluded from MCP."""
return {'status':'not implemented'}
mcp = FastApiMCP(app, include_operations=['read_order'])
mcp.mount_http()
operation_id 決定穩定的工具名稱;include_operations 只把 read_order 暴露給 MCP。先定義路由,再建立與掛載 MCP。
啟動伺服器並讓視窗保持運作:
.venv\Scripts\python.exe -m uvicorn app:app --host 127.0.0.1 --port 8000
接上 Codex 與 Claude Code
另開 PowerShell,切到相同專案:
codex mcp add fastapi --url http://127.0.0.1:8000/mcp
codex mcp list
開新的 Codex 對話,就可以要求呼叫 read_order。
Claude Code:
claude mcp add fastapi --scope project --transport http http://127.0.0.1:8000/mcp
claude mcp list
健康檢查應顯示 Connected。Cursor 的 URL 型設定請看官方文件,同樣指向這個 /mcp HTTP 位址。
三個可以直接貼上的用途
1. 查詢訂單狀態
只用 fastapi MCP 呼叫 read_order,order_id=1。
回報實際 order_id、status、total_cents,不要自行推算狀態。
回傳訂單 1、processing、total_cents=20000。金額使用分作單位,別直接把 20000 當成 20000 元。
2. 確認不存在的訂單怎麼回應
呼叫 read_order,order_id=999。保留工具回傳的錯誤與狀態碼,
告訴我它是「查無訂單」還是「整個伺服器無法連線」。
這次工具回應為 Status code: 404、Order not found。這是正常的業務錯誤路徑,與連線失敗不同。
3. 檢查管理操作有沒有出現在工具清單
列出 fastapi MCP 目前暴露的工具名稱,核對是否只有 read_order,
以及 internal_reset 是否不存在。不要呼叫管理操作。
應只有 read_order。include_operations 限制的是 MCP 工具清單;原本的 REST 路由仍在 FastAPI 中,正式服務的存取控制仍須放在 API 層處理。
常見錯誤
Server.init 參數錯誤
原環境曾因安裝到 MCP SDK 2.3.0 而與 FastAPI-MCP 0.4.0 不相容。用上面的獨立環境固定 mcp==1.30.0,再核對 uv pip freeze --python .venv\Scripts\python.exe 的實際版本。
MCP 連線找不到,或 transport 不合
本文使用 mount_http() 和 HTTP 客戶端。不要混用舊 mount()/SSE 範例;先確認 Uvicorn 還在執行,且 URL 是完整的 /mcp。8000 被占用時,換埠後兩個客戶端 URL 也要一起改。
路由存在,工具卻沒出現
核對 operation_id 拼字與 include_operations 是否一致,並確保路由定義在 MCP 建立之前。改完這份最小範例後重啟 Uvicorn、重連客戶端,再讀新的工具清單。
呼叫被 approval policy 擋住
這次早先的 read_order 曾被客戶端以 MCP tool call requires approval, but approval policy is never 拒絕。伺服器能連線不代表每種工作階段都允許呼叫;檢查客戶端權限,不要改掉 API 的存取控制來解決客戶端問題。
限制、費用與工具選擇
套件採 MIT,本機 adapter 不額外收費;模型、API 本身與部署環境的成本分開計算。這份無認證範例只綁定 loopback,適合練習工具曝光與錯誤回傳。工具白名單不是 REST 存取控制,也不會替正式 API 自動設計身分認證。
既有 FastAPI 路由要接 MCP,可以用這個 adapter;想直接設計 Python MCP 工具,可看 FastMCP 或 MCP Python SDK。FastMCP 也有 FastAPI 整合,請先辨別套件與範例 API,別把兩套名稱混用。
FAQ
FastAPI-MCP 和 FastMCP 是同一個套件嗎?
不是。本文安裝 fastapi-mcp,匯入 fastapi_mcp.FastApiMCP;FastMCP 是另一套專案。兩者都有 FastAPI 整合能力,選擇時先看你要保留既有路由,還是另外設計 MCP 工具。
可以只公開部分 API 嗎?
可以,使用 include_operations 指定 operation ID。本文的管理操作沒有出現在 MCP 清單,但它的 REST 路由仍然存在,因此還要處理 API 本身的權限。
404 代表 MCP 壞了嗎?
要看錯誤來源。範例訂單 999 的 404 是 API 回傳查無資料,MCP 已把它傳回客戶端;如果 Uvicorn 未啟動,才是另一種連線問題。
這個範例能直接部署嗎?
它沒有認證,只設計給本機 loopback 練習。正式部署前需要驗證 API 權限、工具曝光、錯誤處理與網路存取範圍,不是單改 host 就完成。
官方來源與我們測了什麼
Tadata 原始碼、套件與版本、Claude Code MCP、Codex MCP。查閱:2026-11-16。
Windows、Python 3.12、FastAPI-MCP 0.4.0、SDK 1.30.0、Uvicorn 0.54.0、Codex CLI 0.169.0。 真正啟動 loopback HTTP,由 Codex 呼叫訂單 1 得 processing/20000 分,訂單 999 得 404;管理工具未曝光。Claude Code add/list Connected。 Cursor、正式認證、遠端部署、寫入 API 與負載測試未測。