Skip to main content
Glama

MCP 閘道

指令以 package.json 的 scripts 與 wrangler.jsonc 為準。

Deploy to Cloudflare 按鈕部署完還沒結束:還要自己加服務綁定、設定 SERVICES,否則閘道沒有任何 tool,清單見〈部署〉的方式一。

一個放在獨立網域的 Cloudflare Worker,讓 AI client(Claude Code、claude.ai、Claude Desktop、ChatGPT、Cursor 等)透過 MCP(Model Context Protocol)操作自建的各種服務。

  • 對外:提供 MCP 端點 /mcp。

  • 授權:內建 OAuth 2.1 授權伺服器,負責使用者本人的登入,並由使用者逐一勾選每個 client 能用哪些服務、哪些權限。

  • 對內:依授權範圍呼叫各個服務。閘道不保存任何服務的資料,程式裡也不寫任何服務的 tool:有哪些服務、每個服務能做什麼,由服務自己回報。

架構

AI client ──OAuth / MCP──▶ MCP 閘道 Worker(<閘道網域>)
                            ・OAuth 授權伺服器:登入、同意、發 token
                            ・MCP server:依 token 範圍提供 tools
                               │                         │
                     服務綁定 RPC                   HTTPS + HMAC
                (同一個 Cloudflare 帳號)     (其他帳號或非 Cloudflare)
                               ▼                         ▼
                      同帳號的自建服務            其他自建服務(規劃中)

一次呼叫的流程:

  1. client 第一次連 /mcp 收到 401,依 OAuth metadata 動態註冊並走授權流程。

  2. 使用者在閘道登入,在同意頁勾選這個 client 的授權範圍。

  3. client 取得 access token,之後帶 token 呼叫 tools/list、tools/call。

  4. 閘道檢查範圍後,透過服務綁定呼叫該服務的 call(),再把結果包成 MCP 回應。

Related MCP server: mcp-app-server

串接的服務

閘道的程式與設定不含任何實際服務的資訊(串接範例見〈範例:串接書籤服務〉)。有哪些服務、每個服務有哪些 tool 與授權範圍,執行時才知道:

  • 服務清單:secret SERVICES 列出服務綁定的 binding 名稱,多個以逗號分隔。binding 宣告在 wrangler 設定的 services;repo 裡的 wrangler.jsonc 不含任何服務,實際的綁定寫在不進版控的 wrangler.local.jsonc。

  • tool 與範圍:每個服務的 RPC entrypoint 提供 describe(),回傳它在同意頁顯示的名稱、授權範圍,以及每個 tool 的名稱、說明、參數的 JSON Schema、標註、需要的範圍。

  • 執行:tools/call 轉給該服務的 call(tool, args, caller),回傳值成為 MCP 的 tool 結果。

  • 服務名稱:binding 名稱的小寫,例如 NOTES 是 notes。服務只能宣告 notes: 開頭的範圍與 notes_ 開頭的 tool,tool 用到的範圍也要是它自己宣告的;不符合的閘道會丟掉,一個服務冒用不了另一個服務的權限。

  • 更新:describe() 的結果在同一個 isolate 留 60 秒。服務改了 tool 或範圍,部署後最多一分鐘生效,閘道不必重新部署。

閘道替每個 tool 做的事:

  • tools/list 依 token 的範圍過濾;沒授權的範圍看不到對應的 tool,直接 tools/call 也會被拒絕。

  • 執行前依服務宣告的 JSON Schema 驗參數。

  • 沒標 readOnlyHint 的 tool 套用頻率限制。

  • 每次呼叫記一筆稽核紀錄。

  • 服務丟出例外時只回固定的說明文字。

連線方式目前只有同一個 Cloudflare 帳號的服務綁定 + WorkerEntrypoint RPC,不經公網。其他帳號或非 Cloudflare 的服務規劃用 HTTPS + HMAC(每個服務一把金鑰 SVC_<服務>_KEY),還沒有實作。

服務端要提供的契約,以及新增、修改、移除服務串接的步驟,見 README.dev.md。

專案結構

wrangler.jsonc          通用設定(Deploy Button 與測試用):kv_namespaces(OAUTH_KV)、d1_databases(DB)、assets(public/);不含服務,複製成 wrangler.local.jsonc 後填服務綁定
migrations/             閘道 D1:稽核紀錄、登入失敗計數、帳號與授權事件、tool 頻率限制、記住的勾選
src/index.ts            OAuthProvider 的 default export,組合 auth 與 mcp
src/auth.ts             登入、登出、同意頁、設定頁(授權列表、撤銷、記住的勾選、稽核紀錄)的路由
src/ui.ts               上面這些頁面與提示訊息的標記,結構照 Jerry UI 元件規格
public/                 頁面用的靜態檔:jerry-ui.css、jerry-ui.js、jerry.png(元件庫,整檔不改)、app.css(稽核紀錄表)
src/session.ts          閘道自己的登入 Session,只用在授權頁與設定頁
src/throttle.ts         登入失敗節流、tool 的頻率限制
src/mcp.ts              MCP server:依 token 範圍組出 tools
src/permissions.ts      權限判斷的唯一來源(tools/list 與 tools/call 共用)
src/audit.ts            稽核紀錄的寫入與保留
src/events.ts           帳號與授權事件(登入、登出、同意、拒絕、撤銷)的寫入與保留
src/mailer.ts           通知信:即時通知與每日統計信
src/consents.ts         記住同意頁的勾選,算出重新授權時要預先勾選的範圍
src/services/index.ts   讀 SERVICES、呼叫各服務的 describe() 與 call()、檢查回傳形狀與名稱前綴
scripts/dev.sh          本機開發:閘道與 .dev.services 列出的服務一起跑
scripts/deploy.sh       部署:先套 D1 migration 再部署;有 wrangler.local.jsonc 就用它
test/                   Vitest 測試;test/fixtures/services.js 是範例服務,掛成 auxiliary worker 經服務綁定呼叫

不進版控、只存在本機的檔案:wrangler.local.jsonc(實際的服務綁定)、.dev.vars(機密與 SERVICES)、.dev.services(本機要一起跑的服務)。

主要依賴:@cloudflare/workers-oauth-provider、agents(無狀態 createMcpHandler,不需要 Durable Objects)、hono、zod。

架設

需要的東西

  • Cloudflare 帳號,要串接的服務也部署在同一個帳號。

  • Node.js 與 Wrangler CLI。

  • 給閘道用的網域:可以先用 workers.dev 的預設網址,之後再綁自訂網域。

本機開發

npm install
npm test          # 測試:接 repo 內的範例服務,不需要 wrangler.local.jsonc,也不需要任何實際的服務
npm run typecheck # 型別檢查

要在本機接實際的服務,先準備三個不進版控的檔案:

cp wrangler.jsonc wrangler.local.jsonc      # 在 services 填入服務綁定:binding(服務名大寫)、service(Worker 名稱)、entrypoint
cp .dev.vars.example .dev.vars             # 至少填 GATEWAY_PASS;SERVICES 填 binding 名稱,多個以逗號分隔
echo '<服務的 wrangler 設定檔路徑>' >> .dev.services   # 一行一個,本機要一起跑的服務
npm run dev                                # 閘道與 .dev.services 列出的服務一起跑

npm run dev 的限制:一起跑的服務如果有一律連遠端的 binding(例如 ai),Cloudflare 帳號不只一個時,非互動環境會啟動失敗。遇到時替那個服務準備一份拿掉該 binding 的暫時設定檔,改列在 .dev.services;各 Worker 共用同一個 --persist-to 目錄,D1 migration 對該目錄各套一次。

驗證:用 MCP Inspector 連 http://localhost:<port>/mcp,走一次授權流程,再逐一呼叫 tools。

部署

兩種方式擇一。不論哪一種,要串接的服務都要先部署在同一個 Cloudflare 帳號,並帶著提供 describe() 與 call() 的 RPC entrypoint,否則閘道問不到它的 tool。

方式一:Deploy Button

Deploy to Cloudflare

按鈕只部署出一個沒有服務的閘道,部署完還要自己做這幾件事,漏掉的話 AI client 連上後一個 tool 都沒有:

  • 要串接的服務已部署在同一個 Cloudflare 帳號,並帶著 describe() 與 call() 的 RPC entrypoint

  • 在 Cloudflare 幫你建的那份 repo,於 wrangler.jsonc 加上 services,push 後等 Workers Builds 重新部署(下面第 4 步)

  • 在 Worker 的 Settings → Variables and Secrets 設定 SERVICES,值是上一步的 binding 名稱

  • 要收通知信的話:設定 MAIL_FROM、MAIL_TO,並完成 Email Routing 的網域與收件地址驗證(見〈部署之後〉)

  • 用 AI client 連上 /mcp 走一次授權,確認同意頁列出服務的權限

  1. 按上面的按鈕,選 Cloudflare 帳號與 Git 帳號。Cloudflare 會在你的 GitHub 或 GitLab 建一份這個 repo,並接上 Workers Builds:之後每次 push 都會重新部署。

  2. 部署畫面會自動建立 KV(OAUTH_KV)與 D1(DB),並請你填 .dev.vars.example 列出的 secret:

    • GATEWAY_PASS:必填,閘道登入密碼。用 openssl rand -base64 24 產生並自己存好。

    • SERVICES、MAIL_FROM、MAIL_TO:選用,還沒有服務、不寄信就留空。

  3. 部署指令是 npm run deploy(scripts/deploy.sh):先套 D1 migration,再部署 Worker。

  4. 加上服務:服務綁定沒辦法在部署畫面設定,也不能在 Cloudflare 後台手動加(下次部署會被設定檔蓋掉)。到 Cloudflare 幫你建的那份 repo,在 wrangler.jsonc 加 services:

    "services": [{ "binding": "NOTES", "service": "<服務的 Worker 名稱>", "entrypoint": "<WorkerEntrypoint 類別名稱>" }],

    push 之後 Workers Builds 會自動重新部署。再到 Cloudflare 後台 Worker 的 Settings → Variables and Secrets,把 SERVICES 設成 binding 名稱(例如 NOTES)。那份 repo 會寫進你的服務名稱,想保密就設成 private。

方式二:從本機部署

npm install
npx wrangler login
cp wrangler.jsonc wrangler.local.jsonc        # 在 services 填入服務綁定;這份不進版控
  1. 首次部署:D1 要等第一次 deploy 才會建立,所以第一次先單獨部署,再套 migration。wrangler.local.jsonc 不寫 KV 與 D1 的 id,首次 deploy 依 binding 自動建立,之後沿用。

    npx wrangler deploy -c wrangler.local.jsonc
    npm run deploy                              # 套 D1 migration 後再部署一次
  2. 設定閘道的機密:密碼設好之前,登入、同意、設定頁都回 503,/mcp 回 401。

    openssl rand -base64 24                                         # 產生一組密碼,自己存好
    npx wrangler secret put GATEWAY_PASS -c wrangler.local.jsonc    # 閘道登入密碼,貼上剛才那組
    npx wrangler secret put SERVICES -c wrangler.local.jsonc        # 服務綁定的 binding 名稱,多個以逗號分隔
    npx wrangler secret put SVC_<服務>_KEY -c wrangler.local.jsonc  # 只有走 HMAC 的服務需要
    npx wrangler secret put MAIL_FROM -c wrangler.local.jsonc       # 選用:通知信的寄件地址
    npx wrangler secret put MAIL_TO -c wrangler.local.jsonc         # 選用:通知信的收件地址,多個以逗號分隔
  3. 之後更新:npm run deploy。它有 wrangler.local.jsonc 就用它,先套新的 migration 再部署;KV、D1 與已設定的機密都會沿用。多串一個服務時,在 wrangler.local.jsonc 加服務綁定、重新設定 SERVICES,再部署。

帳號不只一個時:在自己的終端機執行,wrangler 會列出帳號讓你選,選服務所在的那一個。腳本或其他非互動環境選不了,要在指令前加 CLOUDFLARE_ACCOUNT_ID=<帳號 id>;id 用 npx wrangler whoami 查。

部署之後

  • SERVICES 沒設定時閘道照常運作,只是沒有任何 tool,同意頁也沒有權限可勾。

  • 通知信走 Email Routing:MAIL_FROM 的網域要啟用 Email Routing,MAIL_TO 的每個地址都要加進 Destination addresses 並點過驗證信。兩個任一個沒設定就不寄信,其他功能不受影響。確認方式:登入一次設定頁,紀錄頁出現「登入成功」,信箱收到同名的通知信;沒收到時看 npx wrangler tail 裡的 mail failed。

  • 自訂網域(選用):在 Cloudflare 後台替 Worker 綁定。換網域後 OAuth 的網址跟著變,所有 client 要重新授權。日後若加入 Passkey 登入,Passkey 也綁這個 hostname,換網域就要重新註冊。

  • 關掉用不到的網址(建議):綁好自訂網域後,在 Worker 的 Settings → Domains & Routes 關掉 workers.dev 與 Preview URLs,只留一個入口。

範例:串接書籤服務

lazyjerry/bookmark-shelf 是照 README.dev.md〈服務端的契約〉實作的服務,可以拿來走一次完整的串接。它的 RPC entrypoint 是 BookmarkRpc(在它的 src/rpc.ts),Worker 名稱是 bookmark-shelf。

  1. 部署書籤服務:照它 README 的〈部署〉,用它的 Deploy Button 或手動部署,部署到與閘道同一個 Cloudflare 帳號。部署時改了 Worker 名稱的話,下一步的 service 要填改過的名稱。

  2. 在閘道加服務綁定:按鈕部署的改 Cloudflare 幫你建的那份 repo 裡的 wrangler.jsonc,本機部署的改 wrangler.local.jsonc:

    "services": [{ "binding": "BOOKMARKS", "service": "bookmark-shelf", "entrypoint": "BookmarkRpc" }],

    按鈕部署的 push 後等 Workers Builds 重新部署;本機部署的執行 npm run deploy。

  3. 設定 SERVICES:值是 BOOKMARKS。按鈕部署的到 Worker 的 Settings → Variables and Secrets 設定;本機部署的執行 npx wrangler secret put SERVICES -c wrangler.local.jsonc。服務名稱是 binding 的小寫 bookmarks,所以書籤服務只能宣告 bookmarks: 開頭的範圍與 bookmarks_ 開頭的 tool。

  4. 選用:在書籤服務設定 APP_URL(書籤服務自己的網址)。經閘道新增書籤時,通知信裡的連結會用它。

  5. 確認:AI client 連上 /mcp 走授權。同意頁的「書籤收藏櫃」分組應該列出兩個權限:

    • 查詢書籤(bookmarks:read,預設勾選):可以用 bookmarks_search、bookmarks_get、bookmarks_overview

    • 新增書籤(bookmarks:write,預設不勾):可以用 bookmarks_add,不能修改或刪除

    只勾查詢的話,tools/list 看不到 bookmarks_add,直接呼叫也會被拒絕。

範圍與 tool 由書籤服務的 describe() 決定,以它的 repo 為準;它改了 tool 後,閘道最多一分鐘就會跟上,不必重新部署。

接上 AI client

  • Claude Code:

    claude mcp add --transport http <名稱> https://<閘道網域>/mcp

    第一次使用時會開瀏覽器走授權流程;沒有自動開的話,在 Claude Code 輸入 /mcp,選這個 server 按 Authenticate。

  • Codex:

    codex mcp add <名稱> --url https://<閘道網域>/mcp
    codex mcp login <名稱>     # 開瀏覽器授權;沒有自動開就加 --no-browser,照印出的網址操作
    codex mcp list             # 確認已列出且已登入

    設定寫在 ~/.codex/config.toml 的 [mcp_servers.<名稱>]。要移除時先 codex mcp logout <名稱> 再 codex mcp remove <名稱>,閘道那邊的授權另外到設定頁撤銷。

  • claude.ai、Claude Desktop、ChatGPT:在 connector 設定加入 https://<閘道網域>/mcp。

每個 client 在閘道上各自授權、各勾各的權限,設定頁會分開列出,可以分開撤銷。

使用

第一次授權

  1. client 連上 /mcp 後會開瀏覽器到閘道的登入頁,輸入 GATEWAY_PASS。

  2. 同意頁列出這個 client 的名稱、同意後會導回的網址,以及可勾選的權限。名稱是 client 自己填的,以導回的網址為準,不認得就按拒絕。

  3. 勾選要給的權限後按同意。權限依服務分組,每一項的名稱、說明與預設有沒有勾選,都由該服務宣告;通常只有查詢類預設勾選。

授權的有效期是 30 天,到期後 client 會再開一次瀏覽器。要改權限就撤銷後重新授權。

重新授權時,同意頁會照這個 client 上次的勾選預先勾好;上次沒列出的權限(例如新串的服務)照服務的預設。撤銷授權不會清掉上次的勾選,要回到預設就到設定頁清除。client 重新註冊、換了 client_id 時,當成第一次授權。

管理已授權的 client

登入 https://<閘道網域>/settings:

  • 已授權的 client:列出每個 client 的名稱、權限與授權時間。按「撤銷」後,那個 client 的 token 立刻失效。

  • 記住的勾選:列出每個 client 上次勾選的權限、最近一次同意的時間、來源 IP 與 User-Agent。按「清除記住的勾選」後,那個 client 下次授權時同意頁回到服務的預設。

  • 稽核紀錄(/settings/logs):最近 200 筆 tool 呼叫,欄位是時間、client、tool、結果(ok/forbidden/throttled/error)、處理時間。保留 30 天。

  • 帳號與授權(同一頁的第二張表):最近 200 筆登入成功、登入失敗、登入被擋、登出、同意授權、拒絕授權、撤銷授權,欄位是時間、事件、client、範圍、來源 IP 與 User-Agent。保留 30 天。

  • 通知信(設定了 MAIL_FROM 與 MAIL_TO 才有):登入成功、同意授權、撤銷授權每次寄一封;登入被擋時,同一個來源 IP 每 15 分鐘只寄一封。登入失敗、登出、拒絕授權不即時寄,每天 UTC 00:00(台灣 08:00)彙整過去 24 小時的次數與登入失敗的來源寄一封,沒有資料就不寄。

  • 登出:頁面上方的按鈕。沒登出的話,登入狀態 12 小時後過期。

常見狀況

狀況

原因與處理

登入頁、設定頁回 503

還沒設定 GATEWAY_PASS,照〈部署〉設定 GATEWAY_PASS

登入回 429「密碼錯誤次數過多」

同一個來源 IP 15 分鐘內試了超過 5 次。等 15 分鐘,或執行 npx wrangler d1 execute mcp-gateway --remote --command "DELETE FROM login_attempts" 清掉計數

AI 說沒有某個 tool,或回「沒有…的授權範圍」

授權時沒勾對應的權限。到設定頁撤銷,讓 client 重新授權

AI 完全沒有 tool,同意頁沒有任何權限可勾

SERVICES 沒設定、binding 名稱與 wrangler 設定的 services 對不上,或服務的 describe() 失敗。看 npx wrangler tail 裡的 service binding missing、service manifest invalid、service describe failed

某個服務少了幾個 tool 或權限

名稱不是該服務名稱開頭,被閘道丟掉。log 有 service manifest entries dropped

稽核紀錄出現 forbidden

有 client 呼叫了它沒被授權的 tool;呼叫沒有執行

AI 回「3 秒內只能執行一次寫入動作…請排隊」,稽核紀錄出現 throttled

同一個 client 距離上一次寫入類 tool 不到 3 秒,這次沒有執行。等 3 秒再送,一次只送一個。服務標了 readOnlyHint 的 tool 不受限。間隔在 src/throttle.ts 的 TOOL_LIMIT

要換登入密碼

重新執行 npx wrangler secret put GATEWAY_PASS。已發出的 token 不會失效,懷疑密碼外流時要到設定頁把 client 逐一撤銷

安全

  • 登入:閘道有自己的密碼登入(GATEWAY_PASS,等時比較);沒設定時整個授權流程回 503。Passkey 登入列在後續規劃。

  • 登入失敗節流:每個來源 IP 15 分鐘內最多驗 5 次密碼,計數存閘道的 D1。

  • /mcp 的驗證:只認 OAuth access token,不認登入 Cookie。

  • 權限檢查兩次:tools/list 依範圍過濾,tools/call 執行前再檢查一次。

  • 服務之間的隔離:服務只能宣告自己名稱開頭的 tool 與範圍,回傳的形狀不對整個服務就不採用。SERVICES 與服務綁定都只有部署的人改得到。

  • 參數驗證兩次:閘道依服務宣告的 JSON Schema 驗一次,服務自己再驗一次;JSON Schema 表達不了的規則只有服務擋得到。

  • tool 的頻率限制:同一個 OAuth client 兩次寫入類 tool 之間至少隔 3 秒,讀取類不限(依服務有沒有替 tool 標 readOnlyHint 判斷);還在間隔內的呼叫不執行,回 tool 錯誤結果請 client 排隊。時間戳存閘道的 D1,被範圍擋下或參數不合法的呼叫不佔名額。

  • 撤銷:設定頁 /settings 列出已授權的 client,可以逐一撤銷。更換 GATEWAY_PASS 不會讓已發出的 token 失效。

  • CSRF:同意頁與設定頁的表單都帶 CSRF token。

  • 稽核紀錄:存閘道的 D1,保留 30 天,在 /settings/logs 查看;只記 OAuth client、tool、結果狀態、處理時間,不記請求內容。

  • 帳號與授權事件:同樣存閘道的 D1、保留 30 天;記事件種類、來源 IP、User-Agent(最多 200 字),授權事件另記 client 與範圍。不記密碼、token、授權碼。

  • 通知信:內容只有事件種類、時間、client、範圍、來源 IP、User-Agent;寄信失敗只留 log,不影響登入與授權。

  • 錯誤訊息:回給 client 的錯誤只有說明文字,不含堆疊與內部路徑。

開發

開發規則見 AGENTS.md;服務端的契約與新增、修改、移除服務串接的步驟見 README.dev.md。

授權

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables existing apps to expose their users and data to external AI agents via MCP with OAuth 2.1 authentication and scoped tools.
      21 npm
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables production-hardened MCP tool serving with OAuth 2.1 audience-restricted tokens, purpose-bound tools, human-in-the-loop approvals, containment, and audit trails for AI agents.
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Provides a single MCP server endpoint that lets AI agents connect to many real third-party services through OAuth, with user approvals, activity logs, scoped read/write grants, and one-tap access removal.
      AGPL 3.0