クラス: MCPAuth

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

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

例

resource server モードでの利用例

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

オプション 1: Discovery 設定（エッジランタイム推奨）

メタデータをオンデマンドで取得したい場合に使用します。特に 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());