メインコンテンツにスキップ

クラス: MCPAuth

mcp-auth ライブラリのメインクラスです。保護されたリソースのための認証 (Authentication) ポリシーを作成するためのファクトリーおよびレジストリとして機能します。

サーバー構成で初期化され、トークンベースの認証 (Authentication) 用 Express ミドルウェアを生成する bearerAuth メソッドを提供します。

例​

resource server モードでの利用例​

新しいアプリケーションにはこの方法が推奨されます。

メタデータをオンデマンドで取得したい場合に使用します。特に 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,
        // issuer と type だけ渡せばOK。メタデータは初回リクエスト時に取得されます
        authorizationServers: [{ issuer: 'https://auth.logto.io/oidc', type: 'oidc' }],
        scopesSupported: ['read:notes', 'write:notes'],
      },
    },
  ],
});

オプション 2: Resolved 設定（メタデータを事前取得）​

起動時にメタデータを取得・検証したい場合に使用します。

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'],
      },
    },
  ],
});

ミドルウェアの利用​

// Protected Resource Metadata を処理するルーターをマウント
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 設定 - メタデータはオンデマンド取得
  server: { issuer: 'https://auth.logto.io/oidc', type: 'oidc' },
});

// レガシーな Authorization Server Metadata を処理するルーターをマウント
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) を検証する関数。文字列としてアクセス トークン (Access token) を受け取り、検証結果を解決する promise（または値）を返す必要があります。

参照

VerifyAccessTokenFunction — verifyAccessToken 関数の型定義。

config?​

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

Bearer 認証 (Authentication) ハンドラーのためのオプション設定。

参照

BearerAuthConfig — 利用可能な設定オプション（verifyAccessToken と issuer を除く）。

戻り値​

RequestHandler

アクセス トークン (Access token) を検証し、その検証結果をリクエストオブジェクト（req.auth）に追加する Express ミドルウェア関数。

参照​

handleBearerAuth — 実装詳細および req.auth（AuthInfo）オブジェクトの拡張型。

呼び出しシグネチャ​

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

リクエストの Authorization ヘッダー内の アクセス トークン (Access token) を、事前定義された検証モードで検証する Bearer 認証 (Authentication) ハンドラー（Express ミドルウェア）を作成します。

'jwt' モードでは、認可サーバーの JWKS URI から JWK Set を使って JWT 検証関数を作成します。

パラメーター​
mode​

"jwt"

アクセス トークン (Access token) の検証モード。現在サポートされているのは 'jwt' のみです。

参照

VerifyAccessTokenMode — 利用可能なモード。

config?​

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

JWT 検証オプションやリモート JWK set オプションを含む、Bearer 認証 (Authentication) ハンドラーのためのオプション設定。

参照

  • VerifyJwtConfig — JWT 検証のための利用可能な設定オプション。
  • BearerAuthConfig — 利用可能な設定オプション（verifyAccessToken と issuer を除く）。
戻り値​

RequestHandler

アクセス トークン (Access token) を検証し、その検証結果をリクエストオブジェクト（req.auth）に追加する Express ミドルウェア関数。

参照​

handleBearerAuth — 実装詳細および req.auth（AuthInfo）オブジェクトの拡張型。

例外​

'jwt' モード利用時にサーバーメタデータに JWKS URI が指定されていない場合。

delegatedRouter()​

delegatedRouter(): Router;

レガシー OAuth 2.0 認可サーバーメタデータエンドポイント （/.well-known/oauth-authorization-server）をインスタンスに提供されたメタデータで提供するためのデリゲートルーターを作成します。

戻り値​

Router

インスタンスに提供されたメタデータで OAuth 2.0 認可サーバーメタデータエンドポイントを提供するルーター。

非推奨​

代わりに 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 Protected Resource Metadata エンドポイントを提供するルーターを作成します。

このルーターは、構成で指定した各リソース識別子に基づいて、正しい .well-known エンドポイントを自動的に作成します。

戻り値​

Router

OAuth 2.0 Protected Resource Metadata エンドポイントを提供するルーター。

例外​

authorization server モードで呼び出された場合。

例​

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

// mcpAuth が 1 つ以上の `protectedResources` 設定で初期化されていると仮定
const mcpAuth: MCPAuth;
const app = express();

// 構成したリソース識別子に基づき、`/.well-known/oauth-protected-resource/...` でメタデータを提供
app.use(mcpAuth.protectedResourceMetadataRouter());