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

はじめに

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) のために信頼する認可 (Authorization) サーバーを設定することです。MCP Auth は現在リソースサーバーモードで動作し、OAuth 2.0 保護リソースメタデータ (RFC 9728) を必要とする最新の MCP 仕様に準拠しています。

プロバイダーが以下に準拠している場合：

組み込み関数を使ってメタデータを取得し、MCP Auth インスタンスを初期化できます：

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

// 1. リソース識別子を定義し、信頼する認可 (Authorization) サーバーの設定を取得します。
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、データ変換、手動メタデータ指定など、他の認可 (Authorization) サーバーメタデータ設定方法については MCP Auth の他の設定方法 をご覧ください。

保護リソースメタデータエンドポイントをマウントする​

最新の MCP 仕様に準拠するため、MCP Auth は OAuth 2.0 保護リソースメタデータエンドポイント (RFC 9728) を MCP サーバーにマウントします。このエンドポイントによりクライアントは以下を発見できます：

  • どの認可 (Authorization) サーバーが保護リソース用の有効なトークンを発行できるか
  • 各リソースでサポートされているスコープ
  • 適切なトークン検証に必要なその他のメタデータ

エンドポイントパスはリソース識別子のパスコンポーネントによって自動的に決定されます：

  • パスなし: https://api.example.com → /.well-known/oauth-protected-resource
  • パスあり: https://api.example.com/notes → /.well-known/oauth-protected-resource/notes

MCP サーバーはこれで リソースサーバー として機能し、トークンの検証や保護リソースのメタデータ提供を行い、認証 (Authentication) と認可 (Authorization) は完全に外部の認可 (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) 検証

audience パラメーターは安全なトークン検証のために OAuth 2.0 仕様で 必須 です。ただし、リソース識別子をまだサポートしていない認可 (Authorization) サーバーとの互換性維持のため、現在は オプション です。セキュリティのため、可能な限り audience パラメーターを必ず指定してください。今後のバージョンでは仕様準拠のため audience 検証が必須となります。

常にスコープ (Scope) を検証する

OAuth 2.0 では、スコープ (Scope) は権限 (Permission) 管理の主要なメカニズムです。正しい audience を持つ有効なトークンがあっても、ユーザーがアクションを実行する権限 (Permission) を持っているとは限りません — 認可 (Authorization) サーバーは、空または制限されたスコープ (Scope) でトークンを発行する場合があります。

各操作に必要な権限 (Permission) がトークンに含まれていることを強制するために、常に requiredScopes を使用してください。有効なトークンが完全なアクセス権を意味すると決して仮定しないでください。

import express from 'express';

const app = express();

// 保護リソースメタデータを提供するルーターをマウントします。
app.use(mcpAuth.protectedResourceMetadataRouter());

// リソース固有ポリシーで API エンドポイントを保護します。
app.get(
  '/notes',
  mcpAuth.bearerAuth('jwt', {
    resource: resourceIdentifier,
    audience: resourceIdentifier,  // セキュリティのためオーディエンス検証を有効化
    requiredScopes: ['read:notes'],
  }),
  (req, res) => {
    // トークンが有効な場合、`req.auth` にクレーム (Claims) が格納されます。
    console.log('Auth info:', req.auth);
    res.json({ notes: [] });
  },
);

app.listen(3000);

上記の例では、jwt トークンタイプとリソース識別子を指定しています。ミドルウェアは、そのリソース用に設定された信頼できる認可 (Authorization) サーバーに対して JWT トークンを自動的に検証し、認証 (Authentication) 済みユーザー情報を格納します。

情報

JWT (JSON Web Token) について聞いたことがない場合もご安心ください。ドキュメントを読み進める中で必要なタイミングで解説します。簡単な紹介は Auth Wiki もご覧いただけます。

Bearer 認証 (Authentication) 設定の詳細は Bearer 認証 (Authentication) の設定 をご覧ください。

MCP 実装で認証 (Authentication) 情報を取得する​

Bearer 認証 (Authentication) ミドルウェアを適用すると、MCP 実装内で認証 (Authentication) 済みユーザー（またはアイデンティティ）の情報にアクセスできます：

ツールハンドラーの第 2 引数には authInfo オブジェクトが含まれ、認証 (Authentication) 済みユーザー情報が格納されています：

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

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

// 先ほどの例のように MCP Auth で初期化
// ...

server.registerTool(
  'add',
  {
    description: '2 つの数値を加算します',
    inputSchema: { a: z.number(), b: z.number() },
  },
  async ({ a, b }, { authInfo }) => {
    // `authInfo` オブジェクトを使って認証 (Authentication) 情報にアクセスできます
  }
);

次のステップ​

この後は、MCP Auth を MCP サーバーに統合するエンドツーエンドの例や、MCP クライアントでの認証 (Authentication) フローの扱い方について学んでいきましょう。