跳转到主要内容

在 MCP 服务器中配置 MCP Auth

根据最新的 MCP 规范 (2025-06-18)，你的 MCP 服务器作为资源服务器，用于验证由外部授权 (Authorization) 服务器颁发的访问令牌 (Access token)。

要配置 MCP Auth，你需要完成两个主要步骤：

  1. 配置授权 (Authorization) 服务器元数据 —— 定义哪些授权 (Authorization) 服务器可以为你的 MCP 服务器颁发有效令牌 (Access token)，并指导 MCP 客户端从哪里获取访问令牌 (Access token)
  2. 配置受保护资源元数据 —— 将你的 MCP 服务器定义为受保护资源，并声明支持的权限 (Scopes)

步骤 1：配置授权 (Authorization) 服务器元数据​

自动元数据获取​

配置授权 (Authorization) 服务器元数据最简单的方法是使用内置函数，从 well-known URL 自动获取元数据。如果你的提供方符合以下标准之一：

你可以通过提供 issuer URL，使用 fetchServerConfig 自动检索元数据：

import { fetchServerConfig } from 'mcp-auth';

// 获取授权 (Authorization) 服务器元数据
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。

按需发现​

如果你在 Cloudflare Workers 等边缘运行时环境中，无法在顶层使用 async fetch，可以使用按需发现。只需提供 issuer 和 type，首次需要时会自动获取元数据：

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

配置授权 (Authorization) 服务器元数据的其他方式​

自定义数据转译​

在某些情况下，提供方返回的元数据可能不符合预期格式。如果你确信提供方是合规的，可以使用 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 获取元数据​

如果你的提供方有特定的元数据 URL，而不是标准 URL，也可以类似地使用：

import { fetchServerConfigByWellKnownUrl } from 'mcp-auth';

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

从指定 URL 获取元数据并自定义数据转译​

在某些情况下，提供方响应可能格式不正确或不符合预期元数据格式。如果你确信提供方是合规的，可以通过配置项转译元数据：

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

手动提供元数据​

如果你的提供方不支持元数据获取，你可以手动提供元数据对象：

const authServerConfig = {
  metadata: {
    issuer: '<issuer-url>',
    // 元数据字段应为 camelCase
    authorizationEndpoint: '<authorization-endpoint-url>',
    // ... 其他元数据字段
  },
  type: 'oidc', // 或 'oauth'
};

步骤 2：配置受保护资源元数据​

配置好授权 (Authorization) 服务器元数据后，你需要通过定义受保护资源元数据，将 MCPAuth 初始化为资源服务器。

此步骤遵循 RFC 9728 (OAuth 2.0 受保护资源元数据) 规范，将你的 MCP 服务器描述为受保护资源：

import { MCPAuth } from 'mcp-auth';

// 定义你的资源标识符
const resourceIdentifier = 'https://api.example.com/notes';

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

对于多个资源，你可以提供受保护资源配置数组，每个资源有自己的元数据配置。

上述配置涵盖了基础设置。更多高级元数据参数，请参见 RFC 9728。

步骤 3：挂载受保护资源元数据端点​

挂载路由以提供受保护资源元数据端点。端点路径会根据你的资源标识符的路径部分自动确定：

  • 无路径：https://api.example.com → /.well-known/oauth-protected-resource
  • 有路径：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());