跳轉到主要內容

開始使用

MCP 授權 (Authorization) 規範支援

本版本支援 MCP 授權 (Authorization) 規範（2025-06-18 版）。

Python SDK 已推出

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

選擇相容的 OAuth 2.1 或 OpenID Connect 提供者​

MCP 規範對授權 (Authorization) 有特定要求。其授權機制基於既有規範，實作其中精選子集功能，以確保安全性與互通性，同時維持簡潔：

這些規範共同提供 MCP 實作安全且標準化的授權 (Authorization) 框架。

你可以查閱 MCP 相容提供者清單 以確認你的提供者是否支援。

安裝 MCP Auth SDK​

pnpm add mcp-auth

初始化 MCP Auth​

第一步是定義你的資源標示符，並設定將被信任用於驗證 (Authentication) 的授權伺服器。MCP Auth 現在以資源伺服器模式運作，符合新版 MCP 規範，要求支援 OAuth 2.0 受保護資源中繼資料（RFC 9728）。

若你的提供者符合：

你可以使用內建函式擷取中繼資料並初始化 MCP Auth 實例：

import { MCPAuth, fetchServerConfig } from 'mcp-auth';

// 1. 定義你的資源標示符，並擷取其信任授權伺服器的設定。
const resourceIdentifier = 'https://api.example.com/notes';
const authServerConfig = await fetchServerConfig('https://auth.logto.io/oidc', { type: 'oidc' });

// 2. 以資源伺服器模式初始化 MCPAuth。
// `protectedResources` 可為單一物件或多個資源的陣列。
const mcpAuth = new MCPAuth({
  protectedResources: {
    metadata: {
      resource: resourceIdentifier,
      authorizationServers: [authServerConfig],
      scopesSupported: ['read:notes', 'write:notes'],
    },
  },
});

如果你使用如 Cloudflare Workers 等 edge 執行環境，無法在頂層進行 async fetch，請改用隨需發現：

const authServerConfig = { issuer: 'https://auth.logto.io/oidc', type: 'oidc' };

如需其他授權伺服器中繼資料設定方式（包含自訂中繼資料 URL、資料轉換或手動指定），請參閱 其他 MCP Auth 設定方式。

掛載受保護資源中繼資料端點​

為符合新版 MCP 規範，MCP Auth 會將 OAuth 2.0 受保護資源中繼資料端點（RFC 9728）掛載到你的 MCP 伺服器。此端點讓用戶端可發現：

  • 哪些授權伺服器可為你的受保護資源簽發有效權杖
  • 每個資源支援哪些權限範圍 (Scopes)
  • 權杖正確驗證所需的其他中繼資料

端點路徑會依據你的資源標示符的路徑自動決定：

  • 無路徑：https://api.example.com → /.well-known/oauth-protected-resource
  • 有路徑：https://api.example.com/notes → /.well-known/oauth-protected-resource/notes

MCP 伺服器現在作為資源伺服器，負責驗證權杖並提供其受保護資源的中繼資料，並完全依賴外部授權伺服器進行驗證 (Authentication) 與授權 (Authorization)。

你可以使用 SDK 提供的方法掛載此端點：

import express from 'express';

const app = express();

// 掛載路由以提供受保護資源中繼資料。
// 資源 "https://api.example.com" → 端點：/.well-known/oauth-protected-resource
// 資源 "https://api.example.com/notes" → 端點：/.well-known/oauth-protected-resource/notes
app.use(mcpAuth.protectedResourceMetadataRouter());

使用 Bearer 驗證 (Auth) 中介軟體​

初始化 MCP Auth 實例後，你可以套用 Bearer 驗證 (Auth) 中介軟體來保護 MCP 路由。此中介軟體現在需指定端點所屬資源，以便正確驗證權杖：

受眾 (Audience) 驗證

OAuth 2.0 規範要求 audience 參數以確保權杖驗證安全。不過，目前為了相容尚未支援資源標示符的授權伺服器，audience 為選填。出於安全考量，請盡可能務必填寫 audience 參數。未來版本將強制要求受眾 (Audience) 驗證，以完全符合規範。

請務必驗證權限範圍 (Scopes)

在 OAuth 2.0 中，權限範圍 (Scopes) 是主要的權限控制機制。即使權杖 (token) 具有正確的 audience，也不代表使用者就有執行某操作的權限——授權伺服器可能會簽發權限範圍為空或受限的權杖。

請務必使用 requiredScopes 來強制檢查權杖是否包含每個操作所需的權限。切勿假設有效的權杖就代表擁有完整存取權。

import express from 'express';

const app = express();

// 掛載路由以提供受保護資源中繼資料。
app.use(mcpAuth.protectedResourceMetadataRouter());

// 以資源專屬政策保護 API 端點。
app.get(
  '/notes',
  mcpAuth.bearerAuth('jwt', {
    resource: resourceIdentifier,
    audience: resourceIdentifier,  // 啟用受眾 (Audience) 驗證以提升安全性
    requiredScopes: ['read:notes'],
  }),
  (req, res) => {
    // 權杖驗證通過時，`req.auth` 會帶有其宣告 (Claims)。
    console.log('Auth info:', req.auth);
    res.json({ notes: [] });
  },
);

app.listen(3000);

如上例所示，我們指定 jwt 權杖類型與資源標示符。中介軟體會自動根據該資源所設定的信任授權伺服器驗證 JWT 權杖，並填入已驗證使用者資訊。

資訊

還沒聽過 JWT（JSON Web Token）嗎？別擔心，繼續閱讀文件即可，我們會在需要時說明。你也可以參考 Auth Wiki 取得快速介紹。

更多 Bearer 驗證 (Auth) 設定資訊，請參閱 設定 Bearer 驗證 (Auth)。

在 MCP 實作中取得驗證 (Auth) 資訊​

套用 Bearer 驗證 (Auth) 中介軟體後，你可以在 MCP 實作中存取已驗證使用者（或身分）的資訊：

工具處理函式的第二個參數會包含 authInfo 物件，內含已驗證使用者資訊：

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { z } from 'zod';

const server = new McpServer(/* ... */);

// 如前述範例初始化 MCP Auth
// ...

server.registerTool(
  'add',
  {
    description: '加總兩個數字',
    inputSchema: { a: z.number(), b: z.number() },
  },
  async ({ a, b }, { authInfo }) => {
    // 現在你可以使用 `authInfo` 物件存取驗證資訊
  }
);

下一步​

繼續閱讀，瞭解如何將 MCP Auth 與 MCP 伺服器整合的端到端範例，以及如何在 MCP 用戶端處理驗證 (Auth) 流程。