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

チュートリアル: Todo マネージャーを構築する

Python SDK available

MCP Auth は Python でも利用可能です！インストール方法や使い方は Python SDK リポジトリ をご覧ください。

このチュートリアルでは、ユーザー認証 (Authentication) と認可 (Authorization) を備えた todo マネージャー MCP サーバーを構築します。最新の MCP 仕様に従い、MCP サーバーは OAuth 2.0 リソースサーバー (Resource Server) として動作し、アクセス トークンを検証し、スコープベースの権限を強制します。

このチュートリアルを完了すると、次のことができるようになります：

  • ✅ MCP サーバーでロールベースのアクセス制御 (RBAC) を設定する基本的な理解
  • ✅ 認可サーバーが発行したアクセス トークンを利用するリソースサーバーとしての MCP サーバー
  • ✅ Todo 操作に対するスコープベースの権限強制の実装

概要​

このチュートリアルでは、以下のコンポーネントを扱います：

  • MCP クライアント (VS Code)：MCP サポートを内蔵したコードエディタで、OAuth 2.0/OIDC クライアントとして動作します。認可サーバーと認可フローを開始し、MCP サーバーへのリクエスト認証のためにアクセス トークンを取得します。
  • 認可サーバー (Authorization Server)：OAuth 2.1 または OpenID Connect プロバイダーで、ユーザーアイデンティティの管理、ユーザー認証 (Authentication)、および認可されたクライアントへの適切なスコープ付きアクセス トークンの発行を行います。
  • MCP サーバー (リソースサーバー)：最新の MCP 仕様に従い、MCP サーバーは OAuth 2.0 フレームワークのリソースサーバー (Resource Server) として動作します。認可サーバーが発行したアクセス トークンを検証し、todo 操作に対してスコープベースの権限を強制します。

このアーキテクチャは、標準的な OAuth 2.0 フローに従います：

  • VS Code がユーザーの代理で保護されたリソースをリクエスト
  • 認可サーバー (Authorization Server) がユーザーを認証 (Authentication) し、アクセス トークンを発行
  • MCP サーバー がトークンを検証し、付与された権限に基づいて保護されたリソースを提供

これらのコンポーネント間のやり取りを示すハイレベルな図は以下の通りです：

認可サーバーを理解する​

スコープ付きアクセス トークン​

MCP サーバーで ロールベースのアクセス制御 (RBAC) を実装するには、認可サーバーがスコープ付きアクセス トークンの発行をサポートしている必要があります。スコープは、ユーザーに付与された権限を表します。

Logto は、API リソース（RFC 8707: OAuth 2.0 のリソースインジケーター に準拠）とロール機能を通じて RBAC をサポートしています。設定方法は以下の通りです：

  1. Logto Console（またはセルフホストの Logto Console）にサインイン

  2. API リソースとスコープを作成：

    • 「API リソース」へ移動
    • 「Todo Manager」という名前の新しい API リソースを作成
    • 以下のスコープを追加：
      • create:todos: "新しい todo アイテムの作成"
      • read:todos: "すべての todo アイテムの閲覧"
      • delete:todos: "任意の todo アイテムの削除"

  3. ロールを作成（管理を簡単にするため推奨）：

    • 「ロール」へ移動
    • 「Admin」ロールを作成し、すべてのスコープ（create:todos, read:todos, delete:todos）を割り当て
    • 「User」ロールを作成し、create:todos スコープのみ割り当て

  4. 権限を割り当てる：

    • 「ユーザー」へ移動
    • ユーザーを選択
    • 「ロール」タブでロールを割り当てる（推奨）
    • または「権限」タブで直接スコープを割り当てる

スコープは JWT アクセス トークンの scope クレームにスペース区切りの文字列として含まれます。

トークンの検証と権限チェック​

最新の MCP 仕様によると、MCP サーバーは OAuth 2.0 フレームワークの リソースサーバー (Resource Server) として動作します。リソースサーバーとして、MCP サーバーには以下の責任があります：

  1. トークン検証：MCP クライアントから受け取ったアクセス トークンの真正性と完全性を検証
  2. スコープ強制：アクセス トークンからスコープを抽出し、クライアントが実行を許可されている操作を判定
  3. リソース保護：クライアントが有効なトークンと十分な権限を持っている場合のみ保護リソース（ツールの実行）を提供

MCP サーバーがリクエストを受け取った際の検証プロセスは以下の通りです：

  1. Authorization ヘッダーからアクセス トークンを抽出（Bearer トークン形式）
  2. アクセス トークンの署名と有効期限を検証
  3. 検証済みトークンからスコープとユーザー情報を抽出
  4. リクエストされた操作に必要なスコープがトークンに含まれているか確認

例えば、ユーザーが新しい todo アイテムを作成したい場合、そのアクセス トークンには create:todos スコープが含まれている必要があります。リソースサーバーの検証フローは以下の通りです：

Dynamic Client Registration​

このチュートリアルでは Dynamic Client Registration は必須ではありませんが、認可サーバーで MCP クライアント登録を自動化したい場合に便利です。詳細は Dynamic Client Registration は必要ですか？ をご覧ください。

Todo マネージャーにおける RBAC を理解する​

デモ目的で、todo マネージャー MCP サーバーにシンプルなロールベースのアクセス制御 (RBAC) システムを実装します。これにより、RBAC の基本原則をシンプルな実装で学べます。

メモ

このチュートリアルでは RBAC ベースのスコープ管理を紹介していますが、すべての認証 (Authentication) プロバイダーがロールによるスコープ管理を実装しているわけではありません。プロバイダーによっては独自のアクセス制御や権限管理の仕組みを持つ場合があります。

ツールとスコープ​

Todo マネージャー MCP サーバーは、主に次の 3 つのツールを提供します：

  • create-todo: 新しい todo アイテムの作成
  • get-todos: すべての todo の一覧取得
  • delete-todo: ID で todo を削除

これらのツールへのアクセスを制御するため、以下のスコープを定義します：

  • create:todos: 新しい todo アイテムの作成を許可
  • delete:todos: 既存の todo アイテムの削除を許可
  • read:todos: すべての todo アイテムの一覧取得を許可

ロールと権限​

異なるアクセスレベルを持つ 2 つのロールを定義します：

ロールcreate:todosread:todosdelete:todos
Admin✅✅✅
User✅
  • User：自分の todo の作成・閲覧・削除のみ可能な一般ユーザー
  • Admin：すべての todo の作成・閲覧・削除が可能な管理者

リソース所有権​

上記の権限テーブルは各ロールに明示的に割り当てられたスコープを示していますが、リソース所有権の重要な原則も考慮する必要があります：

  • User は read:todos や delete:todos スコープを持っていませんが、次のことが可能です：
    • 自分の todo アイテムの閲覧
    • 自分の todo アイテムの削除
  • Admin は完全な権限（read:todos および delete:todos）を持ち、次のことが可能です：
    • システム内のすべての todo アイテムの閲覧
    • 所有者に関係なく任意の todo アイテムの削除

これは、RBAC システムでよく見られるパターンで、リソース所有者には自分のリソースに対する暗黙的な権限が付与され、管理者ロールにはすべてのリソースに対する明示的な権限が付与されることを示しています。

詳しく学ぶ

RBAC の概念やベストプラクティスについてさらに深く知りたい場合は、Mastering RBAC: A Comprehensive Real-World Example をご覧ください。

プロバイダーで認可を設定する​

前述のアクセス制御システムを実装するには、認可サーバーで必要なスコープをサポートするよう設定する必要があります。プロバイダーごとの設定方法は以下の通りです：

Logto は、API リソースとロール機能を通じて RBAC をサポートしています。設定方法は以下の通りです：

  1. Logto Console（またはセルフホストの Logto Console）にサインイン

  2. API リソースとスコープを作成：

    • 「API リソース」へ移動
    • 「Todo Manager」という名前の新しい API リソースを作成し、リソースインジケーターに http://localhost:3001/ を使用
      • 重要：リソースインジケーターは MCP サーバーの URL と一致する必要があります。このチュートリアルでは MCP サーバーがポート 3001 で動作するため http://localhost:3001/ を使用します。本番環境では実際の MCP サーバー URL（例：https://your-mcp-server.example.com/）を使用してください。
    • 以下のスコープを作成：
      • create:todos: "新しい todo アイテムの作成"
      • read:todos: "すべての todo アイテムの閲覧"
      • delete:todos: "任意の todo アイテムの削除"

  3. ロールを作成（管理を簡単にするため推奨）：

    • 「ロール」へ移動
    • 「Admin」ロールを作成し、すべてのスコープ（create:todos, read:todos, delete:todos）を割り当て
    • 「User」ロールを作成し、create:todos スコープのみ割り当て
    • 「User」ロールの詳細ページで「一般」タブに切り替え、「User」ロールを「デフォルトロール」として設定

  4. ユーザーのロールと権限を管理：

    • 新規ユーザーの場合：
      • デフォルトロールとして「User」ロールが自動的に割り当てられます
    • 既存ユーザーの場合：
      • 「ユーザー管理」へ移動
      • ユーザーを選択
      • 「ロール」タブでユーザーにロールを割り当て
プログラムによるロール管理

Logto の Management API を使ってユーザーロールをプログラムで管理することも可能です。自動化や管理画面構築時に便利です。

アクセス トークンをリクエストする際、Logto はユーザーのロール権限に基づいてスコープをトークンの scope クレームに含めます。

リソースインジケーターの末尾スラッシュ

リソースインジケーターには必ず末尾スラッシュ（/）を含めてください。現在の MCP 公式 SDK のバグにより、SDK を利用するクライアントは認証リクエスト時にリソース識別子へ自動的に末尾スラッシュを付加します。リソースインジケーターに末尾スラッシュがない場合、これらのクライアントでリソース検証が失敗します（VS Code にはこのバグの影響はありません）。

認可サーバーの設定後、ユーザーは付与されたスコープを含むアクセス トークンを受け取ります。MCP サーバーはこれらのスコープを使って次のことを判定します：

  • 新しい todo の作成が可能か（create:todos）
  • すべての todo の閲覧（read:todos）または自分の todo のみ閲覧可能か
  • 任意の todo の削除（delete:todos）または自分の todo のみ削除可能か

MCP サーバーのセットアップ​

公式 MCP SDK を使って todo マネージャー MCP サーバーを作成します。

新しいプロジェクトを作成​

新しい Node.js プロジェクトをセットアップします：

mkdir mcp-server
cd mcp-server
npm init -y # または `pnpm init`
npm pkg set type="module"
npm pkg set main="todo-manager.ts"
npm pkg set scripts.start="node --experimental-strip-types todo-manager.ts"
メモ

サンプルでは TypeScript を使用しています。Node.js v22.6.0 以降では --experimental-strip-types フラグで TypeScript をネイティブ実行できます。JavaScript を使う場合もコードはほぼ同じです。詳細は Node.js ドキュメントを参照してください。

MCP SDK と依存パッケージのインストール​

npm install @modelcontextprotocol/sdk express zod

または pnpm や yarn などお好みのパッケージマネージャーを利用してください。

MCP サーバーの作成​

todo-manager.ts というファイルを作成し、次のコードを追加します：

（※コード部分は翻訳不要のため省略）

サーバーの起動：

npm start

認可サーバーとの連携​

このセクションを完了するには、いくつかの考慮事項があります：

認可サーバーの発行者 (Issuer) URL

通常は認可サーバーのベース URL です（例：https://auth.example.com）。プロバイダーによっては https://example.logto.app/oidc のようなパスが付く場合もあるので、ドキュメントを確認してください。

認可サーバーメタデータの取得方法
  • 認可サーバーが OAuth 2.0 Authorization Server Metadata または OpenID Connect Discovery に準拠していれば、MCP Auth の組み込みユーティリティで自動取得できます。
  • 準拠していない場合は、MCP サーバー設定でメタデータ URL やエンドポイントを手動指定する必要があります。詳細はプロバイダーのドキュメントを参照してください。
認可サーバーで MCP クライアントを登録する方法
  • 認可サーバーが Dynamic Client Registration をサポートしていれば、この手順は不要です。MCP クライアントが自動登録されます。
  • サポートしていない場合は、MCP クライアントを手動で登録する必要があります。
トークンリクエストパラメーターの理解

認可サーバーごとに、ターゲットリソースや権限指定の方法が異なります。主なパターンは以下の通りです：

  • リソースインジケーター方式：

    • resource パラメーターでターゲット API を指定（RFC 8707 参照）
    • モダンな OAuth 2.0 実装で一般的
    • 例： 
      {
  "resource": "http://localhost:3001/",
  "scope": "create:todos read:todos"
}
    • サーバーはリクエストされたリソース専用のトークンを発行

  • オーディエンス方式：

    • audience パラメーターでトークンの受信者を指定
    • リソースインジケーターと似ているが意味が異なる
    • 例： 
      {
  "audience": "todo-api",
  "scope": "create:todos read:todos"
}

  • 純粋なスコープ方式：

    • resource/audience パラメーターなしでスコープのみを利用
    • 従来の OAuth 2.0 アプローチ
    • 例： 
      {
  "scope": "todo-api:create todo-api:read openid profile"
}
    • スコープにプレフィックスを付けて権限をネームスペース化することが多い
    • シンプルな OAuth 2.0 実装で一般的
ベストプラクティス
  • プロバイダーのドキュメントでサポートされているパラメーターを確認
  • 複数の方式を同時にサポートするプロバイダーも存在
  • リソースインジケーターはオーディエンス制限によるセキュリティ向上に有効
  • 利用可能な場合はリソースインジケーター方式を推奨

プロバイダーごとに要件は異なりますが、以下の手順で VS Code と MCP サーバーをプロバイダー固有の設定で連携できます。

MCP クライアントをサードパーティアプリとして登録​

Logto との連携は簡単です。OpenID Connect プロバイダーであり、リソースインジケーターとスコープをサポートしているため、http://localhost:3001/ をリソースインジケーターとして todo API を安全に保護できます。

Logto は Dynamic Client Registration をまだサポートしていないため、MCP クライアント（VS Code）を Logto テナントのサードパーティアプリとして手動登録する必要があります：

  1. Logto Console（またはセルフホストの Logto Console）にサインイン
  2. アプリケーション > サードパーティアプリ へ移動し、「アプリケーションを作成」をクリック
  3. アプリケーションタイプとして ネイティブアプリ を選択
  4. アプリケーション詳細を入力：
    • アプリケーション名：例「MCP Client」
    • 説明：例「VS Code 用 MCP クライアント」
  5. VS Code 用の リダイレクト URI を設定： 
    http://127.0.0.1
https://vscode.dev/redirect
  6. 「変更を保存」
  7. アプリの 権限 タブで、ユーザー セクションにて、先ほど作成した Todo Manager API リソースから create:todos, read:todos, delete:todos 権限を追加
  8. 上部カードに「App ID」が表示されるので、後で使うためコピー

MCP Auth のセットアップ​

まず、MCP サーバープロジェクトに MCP Auth SDK をインストールします。

pnpm add mcp-auth

次に、MCP サーバーで MCP Auth を初期化します。保護リソースモードでは、認可サーバーを含むリソースメタデータを設定する必要があります。

認可サーバーの設定方法は 2 通りあります：

  • 事前取得（推奨）：fetchServerConfig() でメタデータを取得してから MCPAuth を初期化。起動時に設定が検証されます。
  • オンデマンドディスカバリー：issuer と type のみ指定し、初回利用時にメタデータを取得。Cloudflare Workers などトップレベル async fetch が許可されない環境で便利です。

保護リソースメタデータの設定​

まず、認可サーバーの issuer URL を取得します：

Logto では、Logto Console のアプリ詳細ページ「エンドポイント & 資格情報 / Issuer endpoint」セクションで issuer URL を確認できます。例：https://my-project.logto.app/oidc

次に、MCP Auth インスタンス作成時に Protected Resource Metadata を設定します：

（※コード部分は翻訳不要のため省略）

MCP サーバーの更新​

いよいよ MCP サーバーに MCP Auth ルートとミドルウェア関数を適用し、ユーザーのスコープに基づく権限制御を実装します。

まず、MCP クライアントが MCP サーバーからリソースメタデータを取得できるよう、保護リソースメタデータルートを適用します。

（※コード部分は翻訳不要のため省略）

次に、MCP Auth ミドルウェアを MCP サーバーに適用します。このミドルウェアはリクエストの認証 (Authentication) と認可 (Authorization) を処理し、認可されたユーザーのみが todo マネージャーツールにアクセスできるようにします。

（※コード部分は翻訳不要のため省略）

ここまでで、MCP Auth ミドルウェアを利用した認証 (Authentication)・認可 (Authorization) の仕組みをツール実装に反映できます。

ツールの実装を更新しましょう。

（※コード部分は翻訳不要のため省略）

次に、上記コードで利用している「Todo サービス」を作成します：

todo-service.ts ファイルを作成し、Todo サービスの機能を実装します：

（※コード部分は翻訳不要のため省略）

おめでとうございます！これで認証 (Authentication) と認可 (Authorization) を備えた MCP サーバーが完成しました！

情報

MCP サーバー（OIDC バージョン）の完全なコードは MCP Auth Node.js SDK リポジトリ をご覧ください。

チェックポイント: todo-manager ツールを実行​

MCP サーバーを再起動し、VS Code から接続します。認証付きで接続する手順は以下の通りです：

  1. VS Code で Command + Shift + P（macOS）または Ctrl + Shift + P（Windows/Linux）を押してコマンドパレットを開く
  2. MCP: Add Server... と入力して選択
  3. サーバータイプに HTTP を選択
  4. MCP サーバーの URL を入力：http://localhost:3001
  5. OAuth リクエストが開始されると、VS Code から App ID の入力を求められます。認可サーバーで控えた App ID を入力
  6. App Secret は不要（パブリッククライアントのため）なので Enter でスキップ
  7. ブラウザでサインインフローを完了

サインイン後 VS Code に戻り、前回のチェックポイントと同じ操作で todo マネージャーツールを実行します。今回は認証済みユーザーとしてツールを利用できます。ツールの挙動はユーザーに割り当てられたロールと権限によって異なります：

  • User（create:todos スコープのみ）の場合：

    • create-todo ツールで新しい todo を作成可能
    • 自分の todo のみ閲覧・削除可能
    • 他ユーザーの todo は閲覧・削除不可

  • Admin（すべてのスコープ：create:todos, read:todos, delete:todos）の場合：

    • 新しい todo の作成が可能
    • get-todos ツールでシステム内のすべての todo を閲覧可能
    • delete-todo ツールで誰が作成したかに関係なく任意の todo を削除可能

異なる権限レベルをテストするには：

  1. MCP サーバーから切断（VS Code のサーバー設定を削除）
  2. 別のロール/権限を持つユーザーアカウントでサインイン
  3. 同じツールを再度試して、ユーザーの権限による挙動の違いを確認

これにより、ロールベースのアクセス制御 (RBAC) が実際にどのように機能するかを体験できます。異なるユーザーがシステムの機能に対して異なるアクセスレベルを持つことが分かります。

情報

MCP サーバー（OIDC バージョン）の完全なコードは MCP Auth Node.js SDK リポジトリ をご覧ください。

締めくくり​

おめでとうございます！チュートリアルを無事完了しました。ここまでの内容を振り返りましょう：

  • Todo 管理ツール（create-todo, get-todos, delete-todo）を備えた基本的な MCP サーバーのセットアップ
  • ユーザーと管理者向けに異なる権限レベルを持つロールベースのアクセス制御 (RBAC) の実装
  • MCP Auth を使った MCP サーバーと認可サーバーの連携
  • VS Code でユーザー認証 (Authentication)・スコープ付きアクセス トークンを利用したツール呼び出しの設定

他のチュートリアルやドキュメントもぜひご覧いただき、MCP Auth を最大限に活用してください。