跳轉到主要內容

在 MCP 伺服器中設定 MCP Auth

根據最新的 MCP 規範 (2025-06-18)，你的 MCP 伺服器會作為資源伺服器 (Resource Server)，用來驗證由外部授權伺服器簽發的存取權杖 (Access tokens)。

設定 MCP Auth 需分為兩大步驟：

  1. 設定授權伺服器中繼資料 (Authorization Server Metadata) —— 定義哪些授權伺服器可以為你的 MCP 伺服器簽發有效權杖，並指引 MCP 用戶端去哪裡取得存取權杖 (Access token)
  2. 設定受保護資源中繼資料 (Protected Resource Metadata) —— 將你的 MCP 伺服器定義為受保護資源，並設定支援的權限範圍 (Scopes)

步驟 1：設定授權伺服器中繼資料 (Configure Authorization Server Metadata)​

自動抓取中繼資料 (Automatic metadata fetching)​

最簡單的設定方式是使用內建函式，從 well-known URL 自動抓取授權伺服器中繼資料。如果你的提供者符合下列標準之一：

你可以使用 fetchServerConfig，只需提供 issuer URL，即可自動取得中繼資料：

import { fetchServerConfig } from 'mcp-auth';

// 抓取授權伺服器中繼資料
const authServerConfig = await fetchServerConfig('https://auth.logto.io/oidc', { type: 'oidc' }); // 或 'oauth'

如果你的 issuer 包含路徑，OAuth 2.0 與 OpenID Connect 的行為略有不同：

  • OAuth 2.0：well-known URL 會加在 issuer 的網域後。例如，若 issuer 是 https://my-project.logto.app/oauth，well-known URL 會是 https://auth.logto.io/.well-known/oauth-authorization-server/oauth。
  • OpenID Connect：well-known URL 會直接加在issuer後。例如，若 issuer 是 https://my-project.logto.app/oidc，well-known URL 會是 https://auth.logto.io/oidc/.well-known/openid-configuration。

隨需探索 (On demand discovery)​

如果你使用如 Cloudflare Workers 這類 edge 執行環境，無法在頂層進行 async fetch，可以改用隨需探索。只需提供 issuer 與 type，首次需要時會自動抓取中繼資料：

const authServerConfig = { issuer: '<issuer-url>', type: 'oidc' }; // 或 'oauth'

其他設定授權伺服器中繼資料的方法 (Other ways to configure authorization server metadata)​

自訂資料轉換 (Custom data transpilation)​

有時提供者回傳的中繼資料格式不符預期。如果你確信該提供者是合規的，可以用 transpileData 選項在使用前修改中繼資料：

import { fetchServerConfig } from 'mcp-auth';

const authServerConfig = await fetchServerConfig('<auth-server-issuer>', {
  type: 'oidc',
  transpileData: (data) => ({ ...data, response_types_supported: ['code'] }), 
});

這讓你能在 MCP Auth 使用前，自由調整中繼資料物件。例如新增、移除欄位、修改值或轉換格式。

從指定 URL 抓取中繼資料 (Fetch metadata from a specific URL)​

如果你的提供者有專屬的中繼資料 URL（非標準 well-known），也可以這樣用：

import { fetchServerConfigByWellKnownUrl } from 'mcp-auth';

const authServerConfig = await fetchServerConfigByWellKnownUrl('<metadata-url>', { type: 'oidc' }); // 或 'oauth'

從指定 URL 並自訂資料轉換 (Fetch metadata from a specific URL with custom data transpilation)​

有時提供者回應格式不正確或不符預期。如果你確信該提供者合規，可透過 config 選項轉換中繼資料：

const authServerConfig = await fetchServerConfigByWellKnownUrl('<metadata-url>', {
  type: 'oidc',
  transpileData: (data) => ({ ...data, response_types_supported: ['code'] }), 
});

手動提供中繼資料 (Manually provide metadata)​

若你的提供者不支援自動抓取中繼資料，可手動提供中繼資料物件：

const authServerConfig = {
  metadata: {
    issuer: '<issuer-url>',
    // 中繼資料欄位請用 camelCase
    authorizationEndpoint: '<authorization-endpoint-url>',
    // ... 其他中繼資料欄位
  },
  type: 'oidc', // 或 'oauth'
};

步驟 2：設定受保護資源中繼資料 (Configure Protected Resource Metadata)​

設定好授權伺服器中繼資料後，你需要將 MCPAuth 初始化為資源伺服器 (Resource Server)，並定義你的受保護資源中繼資料。

這個步驟遵循 RFC 9728（OAuth 2.0 受保護資源中繼資料） 規範，將你的 MCP 伺服器描述為受保護資源：

import { MCPAuth } from 'mcp-auth';

// 定義你的資源標示符 (resource identifier)
const resourceIdentifier = 'https://api.example.com/notes';

// 以資源伺服器模式初始化 MCPAuth
const mcpAuth = new MCPAuth({
  protectedResources: {
    metadata: {
      resource: resourceIdentifier,
      authorizationServers: [authServerConfig], // 使用步驟 1 的 config
      scopesSupported: ['read:notes', 'write:notes'],
    },
  },
});

若有多個資源，可傳入受保護資源設定陣列，每個資源有自己的中繼資料設定。

上述設定涵蓋基本需求。若需進階中繼資料參數，請參閱 RFC 9728。

步驟 3：掛載受保護資源中繼資料端點 (Mount the protected resource metadata endpoint)​

掛載路由器以提供受保護資源中繼資料端點。端點路徑會根據你的資源標示符 (resource identifier) 的 path 自動決定：

  • 無 path：https://api.example.com → /.well-known/oauth-protected-resource
  • 有 path：https://api.example.com/notes → /.well-known/oauth-protected-resource/notes
import express from 'express';

const app = express();

const mcpAuth = new MCPAuth({/* ... */});

app.use(mcpAuth.protectedResourceMetadataRouter());