클래스: MCPAuth

mcp-auth 라이브러리의 주요 클래스입니다. 보호된 리소스에 대한 인증 (Authentication) 정책을 생성하기 위한 팩토리이자 레지스트리 역할을 합니다.

서버 구성으로 초기화되며, 토큰 기반 인증 (Authentication)을 위한 Express 미들웨어를 생성하는 bearerAuth 메서드를 제공합니다.

예시

resource server 모드에서의 사용

신규 애플리케이션에 권장되는 접근 방식입니다.

옵션 1: Discovery config (엣지 런타임에 권장)

메타데이터를 필요할 때마다 가져오고 싶을 때 사용하세요. 이는 Cloudflare Workers와 같이 최상위 async fetch가 허용되지 않는 엣지 런타임에서 특히 유용합니다.

import express from 'express';
import { MCPAuth } from 'mcp-auth';

const app = express();
const resourceIdentifier = 'https://api.example.com/notes';

const mcpAuth = new MCPAuth({
  protectedResources: [
    {
      metadata: {
        resource: resourceIdentifier,
        // 발급자와 타입만 전달하면, 메타데이터는 첫 요청 시 가져옵니다
        authorizationServers: [{ issuer: 'https://auth.logto.io/oidc', type: 'oidc' }],
        scopesSupported: ['read:notes', 'write:notes'],
      },
    },
  ],
});

옵션 2: Resolved config (미리 가져온 메타데이터)

애플리케이션 시작 시 메타데이터를 미리 가져와 검증하고 싶을 때 사용하세요.

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

const app = express();
const resourceIdentifier = 'https://api.example.com/notes';
const authServerConfig = await fetchServerConfig('https://auth.logto.io/oidc', { type: 'oidc' });

const mcpAuth = new MCPAuth({
  protectedResources: [
    {
      metadata: {
        resource: resourceIdentifier,
        authorizationServers: [authServerConfig],
        scopesSupported: ['read:notes', 'write:notes'],
      },
    },
  ],
});

미들웨어 사용하기

// 보호된 리소스 메타데이터를 처리하는 라우터를 마운트합니다
app.use(mcpAuth.protectedResourceMetadataRouter());

// 구성된 리소스에 대해 API 엔드포인트를 보호합니다
app.get(
  '/notes',
  mcpAuth.bearerAuth('jwt', {
    resource: resourceIdentifier, // 이 엔드포인트가 속한 리소스를 지정
    audience: resourceIdentifier, // 선택적으로 'aud' 클레임을 검증
    requiredScopes: ['read:notes'],
  }),
  (req, res) => {
    console.log('Auth info:', req.auth);
    res.json({ notes: [] });
  },
);

authorization server 모드의 레거시 사용법 (더 이상 권장되지 않음)

이 방식은 하위 호환성을 위해 지원됩니다.

import express from 'express';
import { MCPAuth } from 'mcp-auth';

const app = express();
const mcpAuth = new MCPAuth({
  // Discovery config - 메타데이터를 필요할 때마다 가져옵니다
  server: { issuer: 'https://auth.logto.io/oidc', type: 'oidc' },
});

// 레거시 인가 (Authorization) 서버 메타데이터를 처리하는 라우터를 마운트합니다
app.use(mcpAuth.delegatedRouter());

// 기본 정책을 사용하여 엔드포인트를 보호합니다
app.get(
  '/mcp',
  mcpAuth.bearerAuth('jwt', { requiredScopes: ['read', 'write'] }),
  (req, res) => {
    console.log('Auth info:', req.auth);
    // 여기서 MCP 요청을 처리합니다
  },
);

생성자

생성자

new MCPAuth(config: MCPAuthConfig): MCPAuth;

MCPAuth 인스턴스를 생성합니다. 전체 구성을 사전에 검증하여 오류 발생 시 빠르게 실패하도록 합니다.

매개변수

config

MCPAuthConfig

인증 (Authentication) 구성입니다.

반환값

MCPAuth

속성

config

readonly config: MCPAuthConfig;

인증 (Authentication) 구성입니다.

메서드

bearerAuth()

호출 시그니처

bearerAuth(verifyAccessToken: VerifyAccessTokenFunction, config?: Omit<BearerAuthConfig, "issuer" | "verifyAccessToken">): RequestHandler;

요청의 Authorization 헤더에 있는 액세스 토큰 (Access token)을 검증하는 Bearer 인증 (Authentication) 핸들러 (Express 미들웨어)를 생성합니다.

매개변수

verifyAccessToken

VerifyAccessTokenFunction

액세스 토큰 (Access token)을 검증하는 함수입니다. 문자열로 액세스 토큰을 받아, 검증 결과로 resolve되는 promise (또는 값)를 반환해야 합니다.

참고

verifyAccessToken 함수의 타입 정의는 VerifyAccessTokenFunction에서 확인하세요.

config?

Omit<BearerAuthConfig, "issuer" | "verifyAccessToken">

Bearer 인증 (Authentication) 핸들러의 선택적 구성입니다.

참고

사용 가능한 구성 옵션은 BearerAuthConfig에서 확인하세요 (verifyAccessToken 및 issuer 제외).

반환값

RequestHandler

액세스 토큰 (Access token)을 검증하고, 검증 결과를 요청 객체 (req.auth)에 추가하는 Express 미들웨어 함수입니다.

참고

구현 세부사항 및 확장된 req.auth (AuthInfo) 객체 타입은 handleBearerAuth에서 확인하세요.

호출 시그니처

bearerAuth(mode: "jwt", config?: Omit<BearerAuthConfig, "issuer" | "verifyAccessToken"> & VerifyJwtConfig): RequestHandler;

미리 정의된 검증 모드를 사용하여 요청의 Authorization 헤더에 있는 액세스 토큰 (Access token)을 검증하는 Bearer 인증 (Authentication) 핸들러 (Express 미들웨어)를 생성합니다.

'jwt' 모드에서는 인가 (Authorization) 서버의 JWKS URI에서 JWK Set을 사용하여 JWT 검증 함수를 생성합니다.

매개변수

mode

"jwt"

액세스 토큰 (Access token) 검증 모드입니다. 현재는 'jwt'만 지원됩니다.

참고

사용 가능한 모드는 VerifyAccessTokenMode에서 확인하세요.

config?

Omit<BearerAuthConfig, "issuer" | "verifyAccessToken"> & VerifyJwtConfig

JWT 검증 옵션 및 원격 JWK set 옵션을 포함한 Bearer 인증 (Authentication) 핸들러의 선택적 구성입니다.

참고

• JWT 검증을 위한 구성 옵션은 VerifyJwtConfig에서 확인하세요.
• 사용 가능한 구성 옵션은 BearerAuthConfig에서 확인하세요 (verifyAccessToken 및 issuer 제외).

반환값

RequestHandler

액세스 토큰 (Access token)을 검증하고, 검증 결과를 요청 객체 (req.auth)에 추가하는 Express 미들웨어 함수입니다.

참고

구현 세부사항 및 확장된 req.auth (AuthInfo) 객체 타입은 handleBearerAuth에서 확인하세요.

예외

'jwt' 모드 사용 시 서버 메타데이터에 JWKS URI가 제공되지 않은 경우 예외가 발생합니다.

---

delegatedRouter()

delegatedRouter(): Router;

인스턴스에 제공된 메타데이터로 레거시 OAuth 2.0 인가 (Authorization) 서버 메타데이터 엔드포인트 (/.well-known/oauth-authorization-server)를 제공하는 delegated 라우터를 생성합니다.

반환값

Router

인스턴스에 제공된 메타데이터로 OAuth 2.0 인가 (Authorization) 서버 메타데이터 엔드포인트를 제공하는 라우터입니다.

더 이상 사용되지 않음

대신 protectedResourceMetadataRouter를 사용하세요.

예시

import express from 'express';
import { MCPAuth } from 'mcp-auth';

const app = express();
const mcpAuth: MCPAuth; // 초기화되어 있다고 가정
app.use(mcpAuth.delegatedRouter());

예외

resource server 모드에서 호출 시 예외가 발생합니다.

---

protectedResourceMetadataRouter()

protectedResourceMetadataRouter(): Router;

구성된 모든 리소스에 대해 OAuth 2.0 보호된 리소스 메타데이터 엔드포인트를 제공하는 라우터를 생성합니다.

이 라우터는 구성에 제공된 각 리소스 식별자에 대해 올바른 .well-known 엔드포인트를 자동으로 생성합니다.

반환값

Router

OAuth 2.0 보호된 리소스 메타데이터 엔드포인트를 제공하는 라우터입니다.

예외

authorization server 모드에서 호출 시 예외가 발생합니다.

예시

import express from 'express';
import { MCPAuth } from 'mcp-auth';

// mcpAuth가 하나 이상의 `protectedResources` 구성으로 초기화되어 있다고 가정
const mcpAuth: MCPAuth;
const app = express();

// 리소스 식별자에 따라 `/.well-known/oauth-protected-resource/...`에서 메타데이터를 제공합니다.
app.use(mcpAuth.protectedResourceMetadataRouter());