啟用第三方 AI agent 存取你的 MCP 伺服器

提示:

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

本指南將帶你透過 mcp-auth 與 MCP 官方 SDK v2，將 Logto 整合進你的 MCP 伺服器，讓第三方 AI agent 能在使用者同意下驗證 (Authentication) 並安全存取你的 MCP 伺服器。

你將學會：

將 Logto 設定為你的 MCP 伺服器的授權 (Authorization) 伺服器。
導入第三方 AI agent，可選擇註冊第三方應用程式，或啟用動態應用程式 (dynamic app)，讓任何 agent 都能無需預先註冊即可連線。
在 MCP 伺服器中設置「whoami」工具，回傳當前使用者的身分宣告 (Claims)。
使用第三方 AI agent（MCP client）測試整個流程。

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

在 Logto 租戶中驗證 (Authentication) 使用者，並取得使用者對第三方 AI agent 的同意。
驗證 Logto 簽發的 JWT 存取權杖 (Access token)（簽章、簽發者 (Issuer)、受眾 (Audience)、過期時間）。
在「whoami」工具被呼叫時，回傳已驗證的身分宣告（如 sub、iss、aud 等）。

範例程式碼:

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

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

第三方 AI agent（MCP client）與你自己的 MCP client 的差異

讓我們看一個例子。假設你是一名開發者，運行一個 MCP 伺服器來管理電子郵件存取與自動化。

官方郵件應用程式（你自己的 MCP client）

你提供一個官方郵件應用程式，讓使用者閱讀與管理他們的郵件。
運作方式：官方郵件應用程式透過 Logto 連接你的 MCP 伺服器進行使用者驗證 (Authentication)。當 Alice 登入時，會自動取得她的郵件存取權，無需額外的授權頁面，因為這是你信任的應用程式。

第三方 AI agent（第三方 MCP client）

你希望圍繞 MCP 伺服器建立生態系，因此另一位開發者打造了「SmartMail AI」（一個能自動摘要郵件並排程會議的 AI 助理），並將其作為第三方 client 整合。
運作方式：SmartMail AI（第三方 MCP client）希望透過你的 MCP 伺服器存取使用者郵件。當 Alice 使用她的帳號登入 SmartMail AI 時：
- 她會看到一個使用者授權頁面 (Consent screen)，詢問是否允許 SmartMail AI 讀取她的郵件與行事曆。
- Alice 可以選擇允許或拒絕這個存取。
- 只有她同意的資料會分享給 SmartMail AI，SmartMail AI 無法在未經明確同意下存取其他資料。

這種存取（權限）控制確保了使用者資料的安全。即使 MCP 伺服器管理所有資料，第三方應用程式如 SmartMail AI 也只能存取使用者明確允許的部分。這個流程無法被繞過，因為它由你在 MCP 伺服器中的存取控制實作所強制執行。

總結

Client type	Example	Consent required?	Who controls it?
官方郵件應用程式	你自己的郵件應用程式	否	你（開發者）
第三方 AI agent	SmartMail AI 助理	是	其他開發者

備註:

如果你想將 MCP 伺服器與你自己的 AI agent 或應用程式整合，請參考為你的 MCP 應用程式啟用 Logto 驗證 (Authentication) 指南。

先決條件

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

瞭解架構

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

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

備註:

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

在 Logto 設定第三方 AI agent

若要讓第三方 AI agent 存取你的 MCP server，你需要在 Logto 中建立一個第三方應用程式（third-party app）。這個應用程式將代表 AI agent，並取得驗證 (Authentication) 與授權 (Authorization) 所需的憑證。

什麼是第三方應用程式？:

第三方應用程式（third-party app） 是由外部開發者（非資源擁有者）建立的應用程式，需要使用者同意才能存取受保護資源。與第一方應用程式（你自己的應用程式）不同，第三方應用程式會顯示使用者授權頁面（consent screen），要求使用者在存取資料前同意特定權限。這確保使用者能掌控與外部服務分享哪些資料。

想了解更多，請參閱第三方應用程式。

有三種方式可導入 AI agent：

在 Console 手動建立應用程式，適合測試或少數已知 agent。
透過 Management API 建立註冊服務，若你想控管誰能取得憑證。
啟用動態應用程式（dynamic app），若任何 agent 都可能連線且不需註冊步驟。

允許開發者在 Logto 建立第三方應用程式

如果你正在打造市集或想讓開發者能在 Logto 建立第三方應用程式，可以利用 Logto Management API 以程式方式建立第三方應用程式。這讓開發者能註冊他們的應用程式並取得驗證 (Authentication) 所需的憑證。

你需要自行架設服務來處理 client 註冊流程。該服務會與 Logto Management API 互動，代表開發者建立第三方應用程式。

你也可以在 Logto Console 手動建立第三方應用程式，以熟悉整個流程。

讓任何 AI agent 免預先註冊即可連線

在開放的 MCP 生態系中，你通常無法預先知道所有 agent。動態應用程式（dynamic app）省略了註冊步驟：agent 以公開 HTTPS URL（提供自身 client metadata 文件）作為 client_id，Logto 在收到授權請求時自動解析。

你仍可透過授予動態應用程式的權限來控管 agent 可請求的內容，且每次授權都會經過使用者授權頁面（consent screen）。

在 Logto 手動建立第三方應用程式

你可以在 Logto Console 手動建立第三方應用程式，適合測試或臨時整合。這在你想快速測試整合、尚未實作完整 client 註冊流程時特別有用。

登入你的 Logto Console。
前往 應用程式（Applications） → 建立應用程式（Create application） → 第三方應用程式（Third-party app） -> OIDC。
輸入應用程式名稱及其他必要欄位，然後點擊 建立應用程式（Create application）。
點選 權限（Permissions） 分頁，為應用程式授予權限（permissions）：
- 使用者（User） 區段：如 profile、email 等使用者資料權限，用於基本身分宣告（claims）。
- API 資源（API resource） 區段：你在 Logto 定義的 API 資源權限（權限範圍，scopes），例如代表你的 MCP server 的 API 資源。
- 組織（Organization） 區段：若你有使用 Logto 組織，則可設定組織權限。
在第三方應用程式中，設定 scopes 以請求你授予的權限，例如 openid profile email 加上 API 資源的權限範圍。

注意：openid 為 OIDC 必填。若要取得綁定 API 資源的存取權杖 (Access token)，應用程式還必須在授權請求中帶上 resource 參數。符合最新 MCP 規範的 MCP client 會根據受保護資源 metadata 自動處理。
根據需求設定第三方應用程式的 redirect URI，並記得同步更新 Logto 內的 redirect URI。

在底層，第三方應用程式是一個標準的 OAuth 2.0 / OIDC 用戶端。這表示你（或第三方開發者）可以使用任何 OAuth 2.0 / OIDC 函式庫或框架來整合 Logto。

幾點注意事項：

建立第三方應用程式時，請根據應用架構選擇合適的應用程式類型：
- 傳統網頁 (Traditional web)：使用 client secret 進行驗證。
- 單頁應用程式 / 原生應用程式 (Single page app / Native)：使用 PKCE 進行安全授權，無需 client secret。
我們的大多數快速入門指南是針對第一方應用程式撰寫，但你仍可將其作為第三方應用程式整合的參考。
主要差異在於第三方應用程式會顯示使用者授權頁面 (Consent screen)，請求使用者明確授權存取其資料。

完整整合指南請參閱第三方應用程式 (Third-party applications)。

設定 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 伺服器。
讓第三方 AI agent 連接你的 MCP 伺服器並呼叫 whoami 工具。
agent 會收到 401 Unauthorized 回應，透過 MCP 伺服器的受保護資源中繼資料發現 Logto，並將使用者導向 Logto 進行驗證 (Authentication)。
使用者登入並檢視授權頁面 (Consent screen)，確認 agent 請求的權限，然後同意（或拒絕）存取。
agent 取得綁定受眾 (Audience) 的 JWT 存取權杖 (Access token)，並再次呼叫該工具。
MCP 伺服器根據 Logto 的 JWKS 驗證存取權杖，並將已驗證的身分宣告回傳給 agent。

延伸閱讀

你的 MCP 伺服器現在已能驗證來自第三方 AI agent 的存取權杖 (Access token)。下一步，學習如何讓它能安全地代表使用者呼叫下游業務 API，而不需權杖直傳或遺失使用者上下文：

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

第三方 AI agent（MCP client）與你自己的 MCP client 的差異​

先決條件​

瞭解架構​

在 Logto 設定第三方 AI agent​

允許開發者在 Logto 建立第三方應用程式​

讓任何 AI agent 免預先註冊即可連線​

在 Logto 手動建立第三方應用程式​

設定 MCP 伺服器​

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

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

使用 Logto 設定 MCP Auth​

實作 "whoami" 工具​

啟動伺服器​

測試整合流程​

延伸閱讀​