mcpo (MCP-to-OpenAPI)

為什麼要用

核心特性

即插即用：任何 stdio MCP 均可成為 HTTP + OpenAPI 服務
自動生成 /docs Swagger UI
工具輸入輸出的 JSON Schema
支援 OAuth（用戶端憑證 + JWT）
單一處理程序執行多個包裝的 MCP
輕量 Python（FastAPI），Apache 2.0

即時演示

實際使用效果

mcpo-openapi-mcp.replay ▶ 就緒

0/0

安裝

選擇你的客戶端

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mcpo-openapi-mcp": {
      "command": "uvx",
      "args": [
        "mcpo",
        "--",
        "uvx",
        "mcp-server-time"
      ]
    }
  }
}

開啟 Claude Desktop → Settings → Developer → Edit Config。儲存後重啟應用。

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "mcpo-openapi-mcp": {
      "command": "uvx",
      "args": [
        "mcpo",
        "--",
        "uvx",
        "mcp-server-time"
      ]
    }
  }
}

Cursor 使用與 Claude Desktop 相同的 mcpServers 格式。專案級設定優先於全域。

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "mcpo-openapi-mcp": {
      "command": "uvx",
      "args": [
        "mcpo",
        "--",
        "uvx",
        "mcp-server-time"
      ]
    }
  }
}

點擊 Cline 側欄中的 MCP Servers 圖示，然後選 "Edit Configuration"。

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "mcpo-openapi-mcp": {
      "command": "uvx",
      "args": [
        "mcpo",
        "--",
        "uvx",
        "mcp-server-time"
      ]
    }
  }
}

格式與 Claude Desktop 相同。重啟 Windsurf 生效。

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "mcpo-openapi-mcp",
      "command": "uvx",
      "args": [
        "mcpo",
        "--",
        "uvx",
        "mcp-server-time"
      ]
    }
  ]
}

Continue 使用伺服器物件陣列，而非映射。

~/.config/zed/settings.json

{
  "context_servers": {
    "mcpo-openapi-mcp": {
      "command": {
        "path": "uvx",
        "args": [
          "mcpo",
          "--",
          "uvx",
          "mcp-server-time"
        ]
      }
    }
  }
}

加入 context_servers。Zed 儲存後熱重載。

claude mcp add mcpo-openapi-mcp -- uvx mcpo -- uvx mcp-server-time

一行命令搞定。用 claude mcp list 驗證，claude mcp remove 移除。

使用場景

實戰用法： mcpo (MCP-to-OpenAPI)

如何從 curl / Postman / OpenAI function-calling 呼叫 MCP 伺服器

👤 執行環境尚不支援 MCP 的後端開發者 ⏱ ~15 min intermediate

何時使用： 你選了一個很棒的 MCP 伺服器，但正式環境的技術堆疊是 Python 服務 / OpenAI Assistants API / 需要 HTTP + JSON 的東西。

前置條件

你通常會啟動的 MCP 指令 — 例如 uvx mcp-server-time 或 npx -y @modelcontextprotocol/server-fetch

步驟

包裝

Run uvx mcpo --port 8000 -- uvx mcp-server-time and confirm /docs is up.✓ 已複製

→ Swagger UI 將工具顯示為端點
用 curl 呼叫

Show me a working curl that calls the time tool with timezone=America/Los_Angeles.✓ 已複製

→ 返回當前時間與時區資訊
連接 OpenAI

Generate a function-calling spec from /openapi.json that I can paste into the OpenAI API.✓ 已複製

→ 規格已輸出；快速測試呼叫成功

結果： 一個非 MCP 後端可以透過 HTTP 驅動的 MCP 伺服器。

注意事項

長時間執行的工具在預設 uvicorn 設定下逾時 — 傳入 --timeout-keep-alive 600 給 mcpo，或使用具備相符逾時設定的 nginx 前端

在一個 HTTP 服務後方執行多個 MCP

👤 整合多個 MCP 的平台工程師 ⏱ ~30 min intermediate

何時使用： 你想要一個 URL 分別在不同路徑前綴下托管 time、fetch 與 filesystem MCP。

步驟

組合

Write the mcpo config for 3 servers — time at /time, fetch at /fetch, filesystem at /fs.✓ 已複製

→ 含 3 個服務的 config.yaml；mcpo 正常提供服務
新增 OAuth

Configure JWT auth via the issuer of my Auth0 tenant. Endpoints require a valid token.✓ 已複製

→ 未帶 token 的呼叫返回 401

結果： 一個托管多個 MCP 的單一受保護 HTTP 進入點。

注意事項

兩個伺服器公開了相同名稱的工具 — mcpo 依前綴進行命名空間；工具衝突由 URL 路徑解決

在 HTTP 整合測試套件中使用 MCP

👤 QA / SDET 團隊 ⏱ ~25 min advanced

何時使用： 你想用標準 HTTP 測試工具驗證 MCP 伺服器的行為。

步驟

在 CI 中啟動

Add a GitHub Actions job that runs mcpo wrapping our MCP, then runs Playwright/pytest against it.✓ 已複製

→ Workflow 檔案已寫入；本地測試通過
Schema 斷言

Snapshot /openapi.json. Fail the build if the schema changes without an explicit change in the source.✓ 已複製

→ CI 中有 schema 差異守衛

結果： 將標準 HTTP 測試流程應用於 MCP 伺服器。

注意事項

底層 MCP 啟動時匯入大量依賴，導致不穩定 — 在測試執行前加入 /healthz 等待迴圈

搭配使用： github

組合

與其他 MCP 搭配，撬動十倍槓桿

mcpo-openapi-mcp + filesystem

將生成的 /openapi.json 持久化到版本庫以供審查

Save current /openapi.json to /api/contracts/$(date +%F).json.✓ 已複製

mcpo-openapi-mcp + github

OpenAPI 規格變更時開啟 PR

If the snapshot diff is non-empty, open a PR titled 'OpenAPI changed'.✓ 已複製

工具

此 MCP 暴露的能力

工具	輸入參數	何時呼叫	成本
GET /docs	(browser)	視覺化探索工具介面	free
GET /openapi.json	(none)	程式碼生成 / function-calling 規格	free
POST /<tool>	JSON body matching tool input schema	透過 HTTP 呼叫包裝後的 MCP 工具	1 underlying MCP call

成本與限制

運行它的成本

API 配額: 受限於包裝的 MCP 配額
每次呼叫 Token 數: 額外增加約 50 個 token
費用: 免費（Apache 2.0）
提示: 每個處理程序只包裝一次；不要在每次請求時啟動新的子處理程序

安全

權限、密鑰、影響範圍

憑證儲存： 透過環境變數傳遞給被包裝的 MCP；mcpo 本身不儲存任何內容

資料出站： 與被包裝的 MCP 的傳出目標一致

預設部署為未驗證——務必置於 OAuth 或私有網路後方

故障排查

常見錯誤與修復

/tool 返回 404

URL 中的工具名稱必須與 MCP 工具名稱完全相符（區分大小寫）

驗證： 在 /docs 中確認正確路徑

底層 MCP 崩潰

mcpo 預設會重新啟動，但會記錄錯誤——請查看 stderr

有效 token 卻返回 OAuth 401

確認 audience 與 issuer 與設定相符；常見錯誤是缺少結尾斜線

驗證： 在 jwt.io 解碼 JWT 並比對 aud/iss

替代方案