第三方工具更新 2026.11.22

FastAPI-MCP 教學:Windows 接 Codex,只公開指定 API 工具

用 FastAPI-MCP 在 Windows 只曝光指定 API,接上 Codex HTTP。包含相容 SDK 版本、完整訂單查詢程式、真實 404 回應與工具白名單限制。

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 與負載測試未測。

訂閱 AI 工具精選與使用建議

有值得推薦的新工具、實測發現或重要更新時,寄到你的信箱。

訂閱後先寄給你一份每月更新的 AI 工具與 Skill 清單。有值得推薦的工具、實測發現或重要更新時才寄信,隨時可以退訂。隱私權說明

快完成了,請到信箱收確認信點信裡的按鈕確認訂閱,就會收到工具清單的下載連結。沒看到的話,看一下垃圾郵件或「促銷內容」分頁。

看過去幾期

也可以在這些平台追蹤: