使用 Logto 為你的 MCP 應用程式啟用驗證 (Authentication)

提示:

探索 Logto 的 AI 解決方案：為 MCP 伺服器、AI agent 和應用程式提供驗證 (Authentication) 與授權 (Authorization)。

本指南將帶你透過 mcp-auth 與 MCP 官方 SDK v2，將 Logto 整合進你的 MCP 伺服器，讓你能驗證使用者並安全地從存取權杖 (Access token) 讀取其經過驗證的身分資訊。

你將學會：

將 Logto 設定為 MCP 伺服器的授權伺服器 (Authorization server)。
在 MCP 伺服器中設置「whoami」工具，回傳當前使用者的身分宣告 (Claims)。
使用 VS Code（MCP 用戶端）測試整個流程。

完成本教學後，你的 MCP 伺服器將能：

在你的 Logto 租戶中驗證使用者。
驗證由 Logto 簽發的 JWT 存取權杖（簽章、簽發者 (Issuer)、受眾 (Audience) 及過期時間）。
在「whoami」工具被呼叫時，回傳經過驗證的身分宣告（sub、iss、aud 等）。

整合完成後，你可以將 VS Code 替換為你自己的 MCP 用戶端（如網頁應用程式），以存取 MCP 伺服器所提供的工具與資源。

範例程式碼:

本指南的完整可執行範例程式碼可在 mcp-auth/js 儲存庫中找到：

whoami-express：本指南中的 "whoami" 伺服器，基於 Node.js 與 Express。
whoami：相同伺服器，採用 fetch-native（網頁標準 Request / Response，搭配 Hono），可部署至 Cloudflare Workers。

先決條件

一個 Logto Cloud（或自託管）租戶
Node.js >= 20 執行環境

瞭解架構

MCP 伺服器 (MCP server)：對 MCP 用戶端 (MCP clients) 提供工具與資源的伺服器。根據最新 MCP 規範，它作為 OAuth 2.0 資源伺服器，驗證由 Logto 簽發的存取權杖 (Access token)。
MCP 用戶端 (MCP client)：用於啟動驗證流程並測試整合的用戶端。本指南將以 VS Code（內建 MCP 支援）作為用戶端。
Logto：作為 OpenID Connect 提供者（授權伺服器），管理使用者身分，並為你的 MCP 伺服器簽發受眾綁定的 JWT 存取權杖 (Access token)。

以下是一個非標準的時序圖，說明整體流程：

備註:

由於 MCP 發展迅速，上述圖表可能未完全反映最新狀態。請參考 mcp-auth 文件以取得最新資訊。

在 Logto 建立應用程式

你的 MCP 用戶端需先在 Logto 註冊為應用程式，才能啟動授權流程。本指南將以 VS Code 作為用戶端進行註冊：

登入你的 Logto Console。
前往 應用程式 (Applications) → 建立應用程式 (Create application) → 不使用框架建立應用程式 (Create app without framework)。
選擇類型：原生應用程式 (Native app)。
輸入應用程式名稱（例如「VS Code」）及其他必要欄位，然後點擊 建立應用程式 (Create application)。
在 設定 (Settings) / 重新導向 URI (Redirect URIs) 區段，新增以下 VS Code 的重新導向 URI，並儲存變更：
```
http://127.0.0.1
https://vscode.dev/redirect
```
儲存並複製 App ID 及 簽發者端點 (Issuer endpoint)。

設定 MCP 伺服器

我們將使用 MCP 官方 SDK v2 和 mcp-auth 建立一個 MCP 伺服器，並實作一個 "whoami" 工具，回傳目前使用者的身分宣告 (claims)。

建立專案並安裝相依套件

mkdir mcp-server
cd mcp-server
npm init -y
npm pkg set type="module"
npm pkg set main="whoami.js"
npm pkg set scripts.start="node whoami.js"
npm install @modelcontextprotocol/server @modelcontextprotocol/express @modelcontextprotocol/node express mcp-auth

@modelcontextprotocol/server 是 MCP SDK v2 核心，採用網頁標準的 Request / Response。
@modelcontextprotocol/express 和 @modelcontextprotocol/node 讓其能在 Node.js 的 Express 上運作。
mcp-auth 提供權杖驗證器與 MCP SDK 所需的 OAuth 探索中繼資料。

備註:

MCP SDK v2 和 mcp-auth 僅支援 ESM，且需 Node.js >= 20。

將 MCP 伺服器註冊為 API 資源

最新 MCP 規範要求存取權杖 (Access token) 必須綁定於其所簽發的資源（RFC 8707），而 mcp-auth 會強制執行此規則：權杖的 aud 宣告 (Claim) 必須與你的 MCP 伺服器資源識別符一致。在 Logto 中，這可透過建立一個 API 資源，其資源標示符 (Resource indicator) 與你的 MCP 伺服器 URL 相符來實現：

登入 Logto Console。
前往 API 資源 (API resources) → 建立 API 資源 (Create API resource)。
填寫相關資訊，然後點擊 建立 API 資源 (Create API resource)：
- API 名稱 (API name)：輸入名稱，例如 "Who am I"。
- API 識別符 (API identifier)：輸入 http://localhost:3001/。這必須與稍後在 MCP 伺服器設定的資源識別符一致。

資源標示符需有結尾斜線:

資源標示符 (Resource indicator) 請務必加上結尾斜線（/）。由於 MCP 官方 SDK 目前的 bug，使用該 SDK 的客戶端在發起驗證請求時會自動於資源識別符後加上斜線。若你的資源標示符未包含結尾斜線，這些客戶端的資源驗證將會失敗。

使用 Logto 設定 MCP Auth

將你的 MCP 伺服器宣告為受保護資源：指定其資源識別符與信任的授權伺服器。請將 <your-logto-issuer-endpoint> 替換為你先前複製的簽發者端點（可在應用程式詳細頁的 Endpoints & Credentials 下找到，例如 https://my-project.logto.app/oidc）。

於 whoami.js：

import { MCPAuth } from 'mcp-auth';

const authIssuer = '<your-logto-issuer-endpoint>';

const mcpAuth = new MCPAuth({
  protectedResourceMetadata: {
    // 資源識別符，必須與 Logto 註冊的 API 資源標示符一致
    resource: 'http://localhost:3001/',
    // 此 MCP 伺服器信任的授權伺服器
    authorizationServer: { issuer: authIssuer, type: 'oidc' },
  },
});

授權伺服器的中繼資料會在首次需要時延遲取得，並快取於後續使用。MCPAuth 實例會根據 Logto 的 JWKS 驗證 JWT 存取權杖 (Access token)——包含簽章、簽發者 (Issuer)、受眾 (Audience) 及過期時間等，無需手動撰寫權杖驗證邏輯。

實作 "whoami" 工具

接下來，實作 "whoami" 工具，從已驗證的存取權杖 (Access token) 回傳目前使用者的身分宣告 (claims)。使用 getAuthInfo 讀取 mcp-auth 已驗證的授權資訊。

import { McpServer } from '@modelcontextprotocol/server';
import { getAuthInfo } from 'mcp-auth';

// 工廠函式建立 MCP 伺服器實例
// 每個請求都會有自己的伺服器實例，確保請求隔離
const createMcpServer = () => {
  const mcpServer = new McpServer({
    name: 'WhoAmI',
    version: '0.0.0',
  });

  // 在伺服器上註冊一個工具，回傳目前使用者資訊
  mcpServer.registerTool(
    'whoami',
    {
      description: '取得目前使用者資訊',
    },
    (context) => {
      const { claims } = getAuthInfo(context);
      return {
        content: [{ type: 'text', text: JSON.stringify(claims) }],
      };
    }
  );

  return mcpServer;
};

啟動伺服器

最後，提供 OAuth 探索文件（RFC 9728 / RFC 8414），讓 MCP 客戶端能找到你的授權伺服器，並用 SDK 的 Bearer 權杖驗證中介軟體保護 MCP 端點。

import {
  createMcpExpressApp,
  mcpAuthMetadataRouter,
  requireBearerAuth,
} from '@modelcontextprotocol/express';
import { toNodeHandler } from '@modelcontextprotocol/node';
import { createMcpHandler } from '@modelcontextprotocol/server';

const PORT = 3001;

// MCP handler 採用網頁標準 Request / Response；`toNodeHandler` 讓其能用於 Express
const mcpNodeHandler = toNodeHandler(createMcpHandler(createMcpServer));

const app = createMcpExpressApp();

// 提供 OAuth 探索文件（`/.well-known/...`），預設公開
app.use(mcpAuthMetadataRouter(await mcpAuth.getAuthMetadataOptions()));

app.all(
  '/',
  // 需要有效的 Bearer 權杖；驗證後的授權資訊會透過 `req.auth` 傳遞給 handler
  requireBearerAuth(mcpAuth.getBearerAuthOptions()),
  // `createMcpExpressApp` 會套用 `express.json()`，會消耗請求串流，因此解析後的 body 需明確傳遞
  async (request, response) => mcpNodeHandler(request, response, request.body)
);

app.listen(PORT);

啟動伺服器：

npm start

測試整合流程

啟動 MCP 伺服器：
```
npm start
```
將 VS Code 連接到你的 MCP 伺服器：
1. 按下 Command + Shift + P（macOS）或 Ctrl + Shift + P（Windows / Linux）開啟命令面板 (Command Palette)。
2. 輸入 MCP: Add Server... 並選擇它。
3. 選擇 HTTP 作為伺服器類型。
4. 輸入 MCP 伺服器網址：http://localhost:3001/
5. 當 OAuth 流程啟動時，VS Code 會提示輸入 Client ID：貼上你先前複製的 App ID。
6. 由於這是公開用戶端，沒有 app secret，直接按 Enter 跳過密碼。
7. 在瀏覽器中完成登入流程。
登入後，在 VS Code 執行 whoami 工具。

你應該會看到來自存取權杖 (Access token) 的驗證宣告 (Claims)，例如：

{
  "iss": "https://my-project.logto.app/oidc",
  "sub": "user_XXXX",
  "aud": "http://localhost:3001/",
  "client_id": "<your-app-id>"
}

延伸閱讀

你的 MCP 伺服器現在已能驗證傳入的存取權杖 (Access token)。下一步，請了解如何讓它能安全地代表使用者呼叫下游商業 API，而不需權杖直傳或遺失使用者上下文：

MCP 伺服器如何代表使用者呼叫你的 API：生產環境權杖策略

先決條件​

瞭解架構​

在 Logto 建立應用程式​

設定 MCP 伺服器​

建立專案並安裝相依套件​

將 MCP 伺服器註冊為 API 資源​

使用 Logto 設定 MCP Auth​

實作 "whoami" 工具​

啟動伺服器​

測試整合流程​

延伸閱讀​