跳轉到主要內容

教學：打造一個待辦事項管理器 (Tutorial: Build a todo manager)

Python SDK available

MCP Auth 也支援 Python！請參考 Python SDK repository 以取得安裝與使用方式。

在本教學中，我們將建立一個具備使用者驗證 (Authentication) 與授權 (Authorization) 的待辦事項 MCP 伺服器。根據最新 MCP 規範，我們的 MCP 伺服器將作為 OAuth 2.0 資源伺服器 (Resource Server)，負責驗證存取權杖 (Access tokens) 並執行基於權限範圍 (Scope) 的權限控管。

完成本教學後，你將會：

  • ✅ 基本瞭解如何在 MCP 伺服器中設定角色型存取控制 (RBAC, Role-based access control)
  • ✅ 擁有一個作為資源伺服器 (Resource Server) 的 MCP 伺服器，能消耗由授權伺服器 (Authorization Server) 發出的存取權杖 (Access tokens)
  • ✅ 實作基於權限範圍 (Scope) 的待辦事項操作權限控管

概覽 (Overview)​

本教學將包含以下元件：

  • MCP 用戶端 (VS Code)：一個內建 MCP 支援的程式碼編輯器，作為 OAuth 2.0 / OIDC 用戶端。它會啟動授權流程，向授權伺服器取得存取權杖 (Access tokens) 以驗證對 MCP 伺服器的請求。
  • 授權伺服器 (Authorization Server)：一個 OAuth 2.1 或 OpenID Connect 提供者，負責管理使用者身分、驗證使用者並向授權的用戶端發放帶有適當權限範圍 (Scopes) 的存取權杖 (Access tokens)。
  • MCP 伺服器 (資源伺服器 Resource Server)：根據最新 MCP 規範，MCP 伺服器在 OAuth 2.0 架構中作為資源伺服器 (Resource Server)。它會驗證授權伺服器發出的存取權杖，並根據權限範圍 (Scopes) 控管待辦事項操作。

此架構遵循標準 OAuth 2.0 流程：

  • VS Code 代表使用者請求受保護資源
  • 授權伺服器 (Authorization Server) 驗證使用者並發出存取權杖
  • MCP 伺服器 (Resource Server) 驗證權杖並根據授權權限提供受保護資源

以下是這些元件互動的高階流程圖：

瞭解你的授權伺服器 (Understand your authorization server)​

具備權限範圍 (Scopes) 的存取權杖 (Access tokens)​

若要在 MCP 伺服器中實作 角色型存取控制 (RBAC)，你的授權伺服器需支援發放帶有權限範圍 (Scopes) 的存取權杖。權限範圍代表使用者被授予的權限。

Logto 透過其 API 資源 (API resources)（符合 RFC 8707: Resource Indicators for OAuth 2.0）與角色 (Roles) 功能支援 RBAC。設定方式如下：

  1. 登入 Logto Console（或你的自架 Logto Console）

  2. 建立 API 資源與權限範圍 (Scopes)：

    • 前往「API 資源」
    • 建立一個名為「Todo Manager」的新 API 資源
    • 新增以下權限範圍：
      • create:todos：「建立新的待辦事項」
      • read:todos：「讀取所有待辦事項」
      • delete:todos：「刪除任意待辦事項」

  3. 建立角色（建議以便管理）：

    • 前往「角色」
    • 建立「Admin」角色並指派所有權限範圍（create:todos、read:todos、delete:todos）
    • 建立「User」角色並僅指派 create:todos 權限範圍

  4. 指派權限：

    • 前往「使用者」
    • 選擇一位使用者
    • 你可以：
      • 在「角色」分頁指派角色（建議）
      • 或直接在「權限」分頁指派權限範圍

這些權限範圍會以空格分隔字串的形式包含在 JWT 存取權杖的 scope 宣告 (Claim) 中。

權杖驗證與權限檢查 (Validating tokens and checking permissions)​

根據最新 MCP 規範，MCP 伺服器在 OAuth 2.0 架構中作為 資源伺服器 (Resource Server)。作為資源伺服器，MCP 伺服器需負責：

  1. 權杖驗證：驗證從 MCP 用戶端收到的存取權杖的真實性與完整性
  2. 權限範圍檢查：從存取權杖中擷取並驗證權限範圍，以判斷用戶端可執行哪些操作
  3. 資源保護：僅在用戶端提供有效且具足夠權限的權杖時，才提供受保護資源（執行工具）

當 MCP 伺服器收到請求時，會執行以下驗證流程：

  1. 從 Authorization 標頭擷取存取權杖（Bearer 權杖格式）
  2. 驗證存取權杖的簽章與有效期限
  3. 從已驗證的權杖中擷取權限範圍與使用者資訊
  4. 檢查權杖是否具備執行該操作所需的權限範圍

例如，若使用者要建立新的待辦事項，其存取權杖必須包含 create:todos 權限範圍。以下為資源伺服器驗證流程：

動態用戶端註冊 (Dynamic Client Registration)​

本教學不強制需要動態用戶端註冊，但若你想自動化 MCP 用戶端在授權伺服器的註冊流程，可參考 是否需要動態用戶端註冊？ 以取得更多資訊。

瞭解待辦事項管理器中的 RBAC (Understand RBAC in todo manager)​

為了示範，我們會在待辦事項 MCP 伺服器中實作一個簡單的角色型存取控制 (RBAC) 系統。這將讓你瞭解 RBAC 的基本原理，同時保持實作簡潔。

註解

雖然本教學以 RBAC 為基礎進行權限範圍管理，但需注意並非所有驗證 (Authentication) 提供者都透過角色來管理權限範圍。部分提供者可能有自己獨特的存取控制與權限管理機制。

工具與權限範圍 (Tools and scopes)​

我們的待辦事項 MCP 伺服器提供三個主要工具：

  • create-todo：建立新的待辦事項
  • get-todos：列出所有待辦事項
  • delete-todo：依 ID 刪除待辦事項

為控管這些工具的存取，我們定義以下權限範圍：

  • create:todos：允許建立新的待辦事項
  • delete:todos：允許刪除現有待辦事項
  • read:todos：允許查詢並取得所有待辦事項清單

角色與權限 (Roles and permissions)​

我們將定義兩種不同存取層級的角色：

角色 (Role)create:todosread:todosdelete:todos
Admin✅✅✅
User✅
  • User：一般使用者，可建立待辦事項，僅能檢視或刪除自己的待辦事項
  • Admin：管理員，可建立、檢視並刪除所有待辦事項，不論擁有者為誰

資源擁有權 (Resource ownership)​

雖然上表明確列出每個角色被指派的權限範圍，但還有一個重要的資源擁有權原則：

  • User 沒有 read:todos 或 delete:todos 權限範圍，但仍可：
    • 讀取自己的待辦事項
    • 刪除自己的待辦事項
  • Admin 具備完整權限（read:todos 與 delete:todos），可：
    • 檢視系統中所有待辦事項
    • 刪除任何待辦事項，不論擁有者為誰

這展現了 RBAC 系統中常見的模式：資源擁有權會隱含授予使用者對自己資源的權限，而管理角色則獲得對所有資源的明確權限。

深入學習

想更深入瞭解 RBAC 概念與最佳實踐，請參閱 Mastering RBAC: A Comprehensive Real-World Example。

在你的提供者中設定授權 (Configure authorization in your provider)​

要實作上述存取控制系統，你需要在授權伺服器中設定所需的權限範圍。不同提供者的設定方式如下：

Logto 透過 API 資源與角色功能支援 RBAC。設定方式如下：

  1. 登入 Logto Console（或你的自架 Logto Console）

  2. 建立 API 資源與權限範圍：

    • 前往「API 資源」
    • 建立名為「Todo Manager」的新 API 資源，並將 http://localhost:3001/ 設為資源標示符 (Resource indicator)。
      • 重要：資源標示符必須與你的 MCP 伺服器 URL 相符。本教學使用 http://localhost:3001/，因 MCP 伺服器運行於 3001 埠。正式環境請使用實際 MCP 伺服器 URL（如 https://your-mcp-server.example.com/）。
    • 建立以下權限範圍：
      • create:todos：「建立新的待辦事項」
      • read:todos：「讀取所有待辦事項」
      • delete:todos：「刪除任意待辦事項」

  3. 建立角色（建議以便管理）：

    • 前往「角色」
    • 建立「Admin」角色並指派所有權限範圍（create:todos、read:todos、delete:todos）
    • 建立「User」角色並僅指派 create:todos 權限範圍
    • 在「User」角色詳細頁切換到「一般」分頁，將「User」設為「預設角色」

  4. 管理使用者角色與權限：

    • 新使用者：
      • 會自動獲得「User」角色（因已設為預設角色）
    • 現有使用者：
      • 前往「使用者管理」
      • 選擇一位使用者
      • 在「角色」分頁指派角色
程式化角色管理

你也可以透過 Logto 的 Management API 程式化管理使用者角色。這對自動化使用者管理或建立管理後台特別有用。

請求存取權杖時，Logto 會根據使用者角色權限將權限範圍包含於權杖的 scope 宣告中。

資源標示符結尾斜線

資源標示符請務必加上結尾斜線（/）。由於 MCP 官方 SDK 目前有一個 bug，使用該 SDK 的用戶端在發起驗證請求時會自動於資源標示符後加上斜線。若你的資源標示符未包含斜線，這些用戶端的資源驗證將會失敗。（VS Code 不受此 bug 影響。）

設定好授權伺服器後，使用者將會收到包含其授權權限範圍的存取權杖。MCP 伺服器會根據這些權限範圍判斷：

  • 使用者是否能建立新待辦事項（create:todos）
  • 使用者是否能檢視所有待辦事項（read:todos）或僅能檢視自己的
  • 使用者是否能刪除任意待辦事項（delete:todos）或僅能刪除自己的

建立 MCP 伺服器 (Set up the MCP server)​

我們將使用 MCP 官方 SDK 來建立待辦事項 MCP 伺服器。

建立新專案 (Create a new project)​

建立一個新的 Node.js 專案：

mkdir mcp-server
cd mcp-server
npm init -y # 或使用 `pnpm init`
npm pkg set type="module"
npm pkg set main="todo-manager.ts"
npm pkg set scripts.start="node --experimental-strip-types todo-manager.ts"
註解

我們範例中使用 TypeScript，因 Node.js v22.6.0+ 原生支援 --experimental-strip-types 執行 TypeScript。若你使用 JavaScript，程式碼大致相同，只需確保 Node.js 版本為 v22.6.0 或以上。詳情請參閱 Node.js 官方文件。

安裝 MCP SDK 與相依套件 (Install the MCP SDK and dependencies)​

npm install @modelcontextprotocol/sdk express zod

或使用你偏好的套件管理工具，如 pnpm 或 yarn。

建立 MCP 伺服器 (Create the MCP server)​

建立名為 todo-manager.ts 的檔案並加入以下程式碼：

（原始程式碼同上，請依指示複製）

啟動伺服器：

npm start

與授權伺服器整合 (Integrate with your authorization server)​

完成本節需考慮以下幾點：

你的授權伺服器的簽發者 (Issuer) URL

通常是你的授權伺服器基礎 URL，例如 https://auth.example.com。部分提供者可能為 https://example.logto.app/oidc，請查閱提供者文件確認。

如何取得授權伺服器中繼資料
如何在授權伺服器註冊 MCP 用戶端
瞭解權杖請求參數

向不同授權伺服器請求存取權杖時，指定目標資源與權限的方式可能不同，主要有：

  • 基於資源標示符 (Resource indicator based)：

    • 使用 resource 參數指定目標 API（參見 RFC 8707: Resource Indicators for OAuth 2.0）
    • 現代 OAuth 2.0 常見
    • 範例請求： 
      {
  "resource": "http://localhost:3001/",
  "scope": "create:todos read:todos"
}
    • 伺服器會發出專屬於該資源的權杖

  • 基於受眾 (Audience based)：

    • 使用 audience 參數指定權杖接收者
    • 與資源標示符類似但語意不同
    • 範例請求： 
      {
  "audience": "todo-api",
  "scope": "create:todos read:todos"
}

  • 純權限範圍 (Pure scope based)：

    • 僅依賴權限範圍，不帶 resource/audience 參數
    • 傳統 OAuth 2.0 作法
    • 範例請求： 
      {
  "scope": "todo-api:create todo-api:read openid profile"
}
    • 常見於簡單 OAuth 2.0 實作，會用前綴命名空間
    • 權限控管較粗略
最佳實踐
  • 查閱提供者文件以確認支援哪些參數
  • 有些提供者同時支援多種方式
  • 資源標示符可提升安全性（限制受眾）
  • 建議有支援時優先使用資源標示符

每個提供者可能有不同細節，以下步驟將引導你整合 VS Code 與 MCP 伺服器，並進行提供者專屬設定。

註冊 MCP 用戶端為第三方應用 (Register MCP client as a third-party app)​

將待辦事項管理器整合至 Logto 很簡單，因其為支援資源標示符與權限範圍的 OpenID Connect 提供者，可用 http://localhost:3001/ 作為資源標示符保護你的 todo API。

由於 Logto 尚未支援動態用戶端註冊，你需手動將 MCP 用戶端（VS Code）註冊為 Logto 租戶中的第三方應用：

  1. 登入 Logto Console（或你的自架 Logto Console）。
  2. 前往 應用程式 > 第三方應用，點擊「建立應用程式」。
  3. 選擇 原生應用 (Native App) 作為應用程式類型。
  4. 填寫應用程式資訊：
    • 應用程式名稱：如 "MCP Client"
    • 描述：如 "MCP client for VS Code"
  5. 為 VS Code 設定以下 Redirect URI： 
    http://127.0.0.1
https://vscode.dev/redirect
  6. 點擊「儲存變更」。
  7. 前往應用程式的 權限 分頁，在 User 區段，新增你先前建立的 Todo Manager API 資源中的 create:todos、read:todos、delete:todos 權限。
  8. 在頂部卡片可看到「App ID」值，複製以備後用。

設定 MCP Auth (Set up MCP Auth)​

首先，在 MCP 伺服器專案中安裝 MCP Auth SDK。

pnpm add mcp-auth

接著初始化 MCP Auth。以受保護資源模式，你需設定資源中繼資料，包括授權伺服器。

有兩種設定授權伺服器的方式：

  • 預先擷取（建議）：使用 fetchServerConfig() 於初始化 MCPAuth 前先取得中繼資料，確保啟動時即驗證設定。
  • 隨需探索：僅提供 issuer 與 type，首次需要時才擷取中繼資料。適合無法在頂層 async fetch 的 edge runtime（如 Cloudflare Workers）。

設定受保護資源中繼資料 (Configure protected resource metadata)​

首先，取得你的授權伺服器簽發者 (Issuer) URL：

在 Logto，可於 Logto Console 的應用程式詳細頁「端點與憑證 / Issuer endpoint」區找到 issuer URL，格式如 https://my-project.logto.app/oidc。

現在，於建立 MCP Auth 實例時設定受保護資源中繼資料：

（原始程式碼同上，請依指示複製）

更新 MCP 伺服器 (Update MCP server)​

快完成了！現在要將 MCP Auth 路由與中介軟體 (middleware) 套用到 MCP 伺服器，並根據使用者權限範圍實作待辦事項工具的權限控管。

首先，套用受保護資源中繼資料路由，讓 MCP 用戶端能從 MCP 伺服器取得預期的資源中繼資料。

（原始程式碼同上，請依指示複製）

接著，將 MCP Auth 中介軟體套用到 MCP 伺服器。此中介軟體會處理所有進來請求的驗證 (Authentication) 與授權 (Authorization)，確保只有授權使用者能存取待辦事項工具。

（原始程式碼同上，請依指示複製）

現在可以更新待辦事項工具的實作，讓其利用 MCP Auth 中介軟體進行驗證與授權。

（原始程式碼同上，請依指示複製）

接著，建立上述程式碼中用到的「Todo service」：

建立 todo-service.ts 檔案：

（原始程式碼同上，請依指示複製）

恭喜！你已成功實作一個具備驗證 (Authentication) 與授權 (Authorization) 的完整 MCP 伺服器！

資訊

完整 MCP 伺服器（OIDC 版本）程式碼請參考 MCP Auth Node.js SDK repository。

檢查點：執行 todo-manager 工具 (Checkpoint: Run the todo-manager tools)​

重啟 MCP 伺服器並用 VS Code 連線。連線並驗證的步驟如下：

  1. 在 VS Code 按下 Command + Shift + P（macOS）或 Ctrl + Shift + P（Windows/Linux）開啟指令面板
  2. 輸入 MCP: Add Server... 並選擇
  3. 選擇 HTTP 作為伺服器類型
  4. 輸入 MCP 伺服器 URL：http://localhost:3001
  5. 當 OAuth 請求啟動時，VS Code 會提示你輸入 App ID，請輸入你從授權伺服器複製的 App ID
  6. 因為我們沒有 App Secret（屬於公開用戶端），直接按 Enter 跳過
  7. 在瀏覽器完成登入流程

登入並返回 VS Code 後，重複前一檢查點的操作以執行待辦事項工具。這次你將以已驗證的使用者身分使用這些工具，工具行為會依你被指派的角色與權限而異：

  • 若你以 User（僅有 create:todos 權限範圍）登入：

    • 可用 create-todo 工具建立新待辦事項
    • 只能檢視與刪除自己的待辦事項
    • 無法看到或刪除其他使用者的待辦事項

  • 若你以 Admin（擁有所有權限範圍：create:todos、read:todos、delete:todos）登入：

    • 可建立新待辦事項
    • 可用 get-todos 工具檢視系統所有待辦事項
    • 可用 delete-todo 工具刪除任何待辦事項，不論擁有者

你可以透過以下方式測試不同權限層級：

  1. 斷開 MCP 伺服器連線（於 VS Code 移除伺服器設定）
  2. 以不同角色／權限的帳號登入
  3. 再次嘗試相同工具，觀察行為如何隨使用者權限變化

這實際展示了角色型存取控制 (RBAC) 的運作，不同使用者對系統功能有不同存取層級。

資訊

完整 MCP 伺服器（OIDC 版本）程式碼請參考 MCP Auth Node.js SDK repository。

結語 (Closing notes)​

恭喜！你已順利完成本教學。讓我們回顧一下：

  • 建立具備待辦事項工具（create-todo、get-todos、delete-todo）的基本 MCP 伺服器
  • 實作使用者與管理員不同權限層級的角色型存取控制 (RBAC)
  • 透過 MCP Auth 將 MCP 伺服器與授權伺服器整合
  • 設定 VS Code 以驗證使用者並用帶有權限範圍的存取權杖呼叫工具

歡迎參閱其他教學與文件，充分發揮 MCP Auth 的強大功能。