跳转到主要内容

入门

MCP 授权 (Authorization) 规范支持

此版本支持 MCP 授权 (Authorization) 规范（2025-06-18 版本）。

Python SDK 可用

MCP Auth 也支持 Python！请查看 Python SDK 仓库 了解安装和用法。

选择兼容的 OAuth 2.1 或 OpenID Connect 提供方​

MCP 规范对授权 (Authorization) 有具体要求。授权 (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 等边缘运行时环境下，无法使用顶层 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 认证 (Authentication) 中间件​

一旦初始化 MCP Auth 实例，你就可以应用 Bearer 认证 (Authentication) 中间件来保护你的 MCP 路由。该中间件现在需要指定端点所属的资源，以实现正确的令牌验证：

受众 (Audience) 验证

OAuth 2.0 规范要求 audience 参数用于安全的令牌验证。但目前为保持与尚未支持资源标识符的授权服务器兼容，该参数为可选。出于安全考虑，请尽可能始终包含 audience 参数。未来版本将强制要求受众 (Audience) 验证，以完全符合规范。

始终校验权限 (Scopes)

在 OAuth 2.0 中，权限 (Scopes) 是权限控制的主要机制。一个具有正确 audience 的有效令牌并不保证用户有执行某个操作的权限 —— 授权 (Authorization) 服务器可能会签发带有空或受限权限 (Scope) 的令牌。

始终使用 requiredScopes 来强制令牌包含每个操作所需的权限 (Permissions)。切勿假设一个有效令牌就意味着完全访问权限。

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 认证 (Authentication) 配置的更多信息，请查看 配置 Bearer 认证 (Authentication)。

在 MCP 实现中获取认证 (Authentication) 信息​

应用 Bearer 认证 (Authentication) 中间件后，你可以在 MCP 实现中访问已认证用户（或身份）的信息：

工具处理器的第二个参数将包含 authInfo 对象，其中包括已认证用户的信息：

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

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

// 按前述示例初始化 MCP Auth
// ...

server.registerTool(
  'add',
  {
    description: 'Add two numbers',
    inputSchema: { a: z.number(), b: z.number() },
  },
  async ({ a, b }, { authInfo }) => {
    // 现在你可以使用 `authInfo` 对象访问认证 (Authentication) 信息
  }
);

下一步​

继续阅读，了解如何将 MCP Auth 与 MCP 服务器集成的端到端示例，以及如何在 MCP 客户端中处理认证 (Authentication) 流程。