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

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

このチュートリアルでは、ユーザー認証 (Authentication) と認可 (Authorization) を備えた todo マネージャー MCP サーバーを構築します。

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

  • ✅ MCP サーバーでロールベースのアクセス制御 (RBAC) を設定する方法の基本的な理解
  • ✅ 個人の todo リストを管理できる MCP サーバー
メモ

始める前に、MCP サーバーや OAuth 2 に不慣れな場合は、Who am I チュートリアル を先にご覧いただくことを強くおすすめします。

概要​

このチュートリアルでは、以下のコンポーネントが登場します：

  • MCP サーバー：MCP 公式 SDK を利用してリクエストを処理し、ユーザーの todo アイテムを管理する Todo サービスを統合したシンプルな MCP サーバー
  • MCP inspector：MCP サーバーのためのビジュアルテストツール。OAuth / OIDC クライアントとして認可フローを開始し、アクセス トークンを取得する役割も担います。
  • 認可サーバー (Authorization server)：ユーザーのアイデンティティを管理し、アクセス トークンを発行する OAuth 2.1 または OpenID Connect プロバイダー

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

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

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

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 サーバーがリクエストを受け取った際に行うべきこと：

  1. アクセス トークンの署名と有効期限を検証
  2. 検証済みトークンからスコープを抽出
  3. リクエストされた操作に必要なスコープがトークンに含まれているか確認

例えば、ユーザーが新しい 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 リソースを作成し、インジケーターとして https://todo.mcp-server.app（デモ用）を使用
    • 以下のスコープを作成：
      • create:todos: 「新しい todo アイテムを作成」
      • read:todos: 「すべての todo アイテムを取得」
      • delete:todos: 「任意の todo アイテムを削除」

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

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

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

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

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

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

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

  • 新しい todo を作成できるか（create:todos）
  • すべての todo を閲覧できるか（read:todos）または自分のものだけか
  • 任意の todo を削除できるか（delete:todos）または自分のものだけか

MCP サーバーをセットアップする​

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

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

mkdir mcp-server
cd mcp-server
uv init # または `pipenv` や `poetry` で仮想環境を作成

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

pip install "mcp[cli]" starlette uvicorn

または uv や poetry などお好みのパッケージマネージャーを利用できます。

MCP サーバーを作成​

まず、ツール定義を含む基本的な MCP サーバーを作成します：

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

from typing import Any
from mcp.server.fastmcp import FastMCP
from starlette.applications import Starlette
from starlette.routing import Mount

mcp = FastMCP("Todo Manager")

@mcp.tool()
def create_todo(content: str) -> dict[str, Any]:
    """新しい todo を作成"""
    return {"error": "Not implemented"}

@mcp.tool()
def get_todos() -> dict[str, Any]:
    """すべての todo を一覧表示"""
    return {"error": "Not implemented"}

@mcp.tool()
def delete_todo(id: str) -> dict[str, Any]:
    """ID で todo を削除"""
    return {"error": "Not implemented"}

app = Starlette(
    routes=[Mount('/', app=mcp.sse_app())]
)

サーバーを起動：

uvicorn todo_manager:app --host 0.0.0.0 --port 3001

MCP サーバーを検証する​

MCP inspector をクローンして起動​

MCP サーバーが起動したので、MCP inspector を使って whoami ツールが利用可能か確認します。

現状の実装制限のため、MCP inspector をフォークし、認証 (Authentication)・認可 (Authorization) に柔軟かつ拡張可能にしました。オリジナルリポジトリにもプルリクエストを提出済みです。

MCP inspector を起動するには（Node.js が必要です）：

git clone https://github.com/mcp-auth/inspector.git
cd inspector
npm install
npm run dev

その後、ブラウザで http://localhost:6274/（またはターミナルに表示された URL）にアクセスしてください。

MCP inspector を MCP サーバーに接続​

進める前に、MCP inspector の設定を確認してください：

  • Transport Type：SSE に設定
  • URL：MCP サーバーの URL を設定（例：http://localhost:3001/sse）

「Connect」ボタンをクリックし、MCP inspector が MCP サーバーに接続できるか確認します。問題なければ MCP inspector に「Connected」ステータスが表示されます。

チェックポイント: Todo マネージャーツールを実行​

  1. MCP inspector の上部メニューで「Tools」タブをクリック
  2. 「List Tools」ボタンをクリック
  3. create-todo, get-todos, delete-todo ツールが一覧に表示されるはずです。クリックして詳細を開きます。
  4. 右側に「Run Tool」ボタンが表示されます。クリックして必要なパラメータを入力し、ツールを実行します。
  5. ツールの結果として {"error": "Not implemented"} という JSON レスポンスが表示されます。

MCP inspector first run

認可サーバーと連携する​

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

認可サーバーの発行者 (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 inspector を認可サーバーのクライアントとして登録する方法
  • 認可サーバーが Dynamic Client Registration をサポートしていれば、このステップは不要です。MCP inspector が自動でクライアント登録します。
  • サポートしていない場合は、MCP inspector を手動でクライアント登録する必要があります。
トークンリクエストパラメータの理解

認可サーバーからアクセス トークンをリクエストする際、ターゲットリソースや権限指定の方法がいくつかあります。主なパターンは以下の通りです：

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

    • resource パラメータでターゲット API を指定（RFC 8707 参照）
    • モダンな OAuth 2.0 実装で一般的
    • 例： 
      {
  "resource": "https://todo.mcp-server.app",
  "scope": "create:todos read:todos"
}
    • サーバーはリソースにバインドされたトークンを発行

  • オーディエンス方式：

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

  • 純粋なスコープ方式：

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

プロバイダーごとに固有の要件がある場合もありますが、以下の手順で MCP inspector および MCP サーバーをプロバイダー固有の設定で統合できます。

MCP inspector をクライアントとして登録​

Logto との統合は簡単です。OpenID Connect プロバイダーであり、リソースインジケーターとスコープをサポートしているため、https://todo.mcp-server.app をリソースインジケーターとして todo API を安全に保護できます。

Logto は現時点で Dynamic Client Registration をサポートしていないため、MCP inspector を Logto テナントのクライアントとして手動登録する必要があります：

  1. MCP inspector を開き、「OAuth Configuration」ボタンをクリック。Redirect URL (auto-populated) の値（例：http://localhost:6274/oauth/callback）をコピー
  2. Logto Console（またはセルフホストの Logto Console）にサインイン
  3. 「アプリケーション」タブで「Create application」をクリック。ページ下部で「Create app without framework」をクリック
  4. アプリケーション詳細を入力し、「Create application」をクリック：
    • アプリケーションタイプ：「Single-page application」を選択
    • アプリケーション名：例「MCP Inspector」
  5. 「Settings / Redirect URIs」セクションで、先ほどコピーした Redirect URL (auto-populated) を貼り付け、「Save changes」をクリック
  6. 上部カードに「App ID」が表示されるのでコピー
  7. MCP inspector に戻り、「OAuth Configuration」セクションの「Client ID」に「App ID」を貼り付け
  8. 「Auth Params」フィールドに {"scope": "create:todos read:todos delete:todos", "resource": "https://todo.mcp-server.app"} を入力。これで Logto から返されるアクセストークンに必要なスコープが含まれます。

MCP auth をセットアップ​

MCP サーバープロジェクトで MCP Auth SDK をインストールし、認可サーバーメタデータを使って設定します。

まず mcpauth パッケージをインストール：

pip install mcpauth

または uv や poetry などお好みのパッケージマネージャーを利用できます。

MCP Auth は認可サーバーメタデータが必要です。プロバイダーごとに：

発行者 (Issuer) URL は Logto Console のアプリケーション詳細ページ「Endpoints & Credentials / Issuer endpoint」セクションで確認できます（例：https://my-project.logto.app/oidc）。

todo-manager.py を更新して MCP Auth の設定を追加します：

from mcpauth import MCPAuth
from mcpauth.config import AuthServerType
from mcpauth.utils import fetch_server_config

auth_issuer = '<issuer-endpoint>'  # 発行者エンドポイントに置き換えてください
auth_server_config = fetch_server_config(auth_issuer, type=AuthServerType.OIDC)
mcp_auth = MCPAuth(server=auth_server_config)

todo-manager.py を MCP Auth 設定を含むように更新：

from mcpauth import MCPAuth
from mcpauth.config import AuthServerType
from mcpauth.utils import fetch_server_config

auth_issuer = '<issuer-endpoint>'  # 発行者エンドポイントに置き換え
auth_server_config = fetch_server_config(auth_issuer, type=AuthServerType.OIDC)
mcp_auth = MCPAuth(server=auth_server_config)

MCP サーバーを更新​

あと少しです！MCP Auth のルートとミドルウェア関数を適用し、ユーザーのスコープに基づく権限管理を todo マネージャーツールに実装します。

@mcp.tool()
def create_todo(content: str) -> dict[str, Any]:
    """新しい todo を作成"""
    return (
        mcp_auth.auth_info.scopes
        if mcp_auth.auth_info # Bearer 認証ミドルウェアでセットされる
        else {"error": "Not authenticated"}
    )

# ...

bearer_auth = Middleware(mcp_auth.bearer_auth_middleware("jwt"))
app = Starlette(
    routes=[
        # メタデータルート（`/.well-known/oauth-authorization-server`）を追加
        mcp_auth.metadata_route(),
        # Bearer 認証ミドルウェアで MCP サーバーを保護
        Mount('/', app=mcp.sse_app(), middleware=[bearer_auth]),
    ],
)

次に、実際のツールを実装します。

まず、メモリ上で todo アイテムの基本的な CRUD 操作を提供するシンプルな todo サービスを作成します。

# service.py

"""
デモ用のシンプルな Todo サービス。
メモリ上のリストで todo を管理します。
"""

from datetime import datetime
from typing import List, Optional, Dict, Any
import random
import string

class Todo:
"""Todo アイテムを表します。"""

    def __init__(self, id: str, content: str, owner_id: str, created_at: str):
        self.id = id
        self.content = content
        self.owner_id = owner_id
        self.created_at = created_at

    def to_dict(self) -> Dict[str, Any]:
        """Todo を辞書に変換（JSON シリアライズ用）"""
        return {
            "id": self.id,
            "content": self.content,
            "ownerId": self.owner_id,
            "createdAt": self.created_at
        }

class TodoService:
"""デモ用のシンプルな Todo サービス。"""

    def __init__(self):
        self._todos: List[Todo] = []

    def get_all_todos(self, owner_id: Optional[str] = None) -> List[Dict[str, Any]]:
        """
        すべての todo を取得。owner_id でフィルタ可能。

        Args:
            owner_id: 指定した場合、そのユーザー所有の todo のみ返す

        Returns:
            Todo 辞書のリスト
        """
        if owner_id:
            filtered_todos = [todo for todo in self._todos if todo.owner_id == owner_id]
            return [todo.to_dict() for todo in filtered_todos]
        return [todo.to_dict() for todo in self._todos]

    def get_todo_by_id(self, todo_id: str) -> Optional[Todo]:
        """
        ID で todo を取得

        Args:
            todo_id: 取得する todo の ID

        Returns:
            見つかれば Todo オブジェクト、なければ None
        """
        for todo in self._todos:
            if todo.id == todo_id:
                return todo
        return None

    def create_todo(self, content: str, owner_id: str) -> Dict[str, Any]:
        """
        新しい todo を作成

        Args:
            content: todo の内容
            owner_id: この todo の所有ユーザー ID

        Returns:
            作成した todo の辞書
        """
        todo = Todo(
            id=self._generate_id(),
            content=content,
            owner_id=owner_id,
            created_at=datetime.now().isoformat()
        )
        self._todos.append(todo)
        return todo.to_dict()

    def delete_todo(self, todo_id: str) -> Optional[Dict[str, Any]]:
        """
        ID で todo を削除

        Args:
            todo_id: 削除する todo の ID

        Returns:
            削除した todo の辞書（見つかれば）、なければ None
        """
        for i, todo in enumerate(self._todos):
            if todo.id == todo_id:
                deleted_todo = self._todos.pop(i)
                return deleted_todo.to_dict()
        return None

    def _generate_id(self) -> str:
        """Todo 用のランダム ID を生成"""
        return ''.join(random.choices(string.ascii_lowercase + string.digits, k=8))

次にツール層で、ユーザーのスコープに基づいて操作が許可されるかどうかを判定します：

# todo-manager.py

from typing import Any, Optional
from mcpauth.errors import MCPAuthBearerAuthError

def assert_user_id(auth_info: Optional[dict]) -> str:
    """auth info からユーザー ID を抽出・検証"""
    subject = auth_info.get('subject') if auth_info else None
    if not subject:
        raise ValueError('Invalid auth info')
    return subject

def has_required_scopes(user_scopes: list[str], required_scopes: list[str]) -> bool:
    """ユーザーがすべての必要なスコープを持っているかチェック"""
    return all(scope in user_scopes for scope in required_scopes)

# TodoService のインスタンスを作成
todo_service = TodoService()

@mcp.tool()
def create_todo(content: str) -> dict[str, Any]:
    """新しい todo を作成

    'create:todos' スコープを持つユーザーのみ作成可能
    """
    # 認証情報を取得
    auth_info = mcp_auth.auth_info

    # ユーザー ID を検証
    try:
        user_id = assert_user_id(auth_info)
    except ValueError as e:
        return {"error": str(e)}

    # 必要な権限を持っているかチェック
    if not has_required_scopes(auth_info.scopes if auth_info else [], ['create:todos']):
        raise MCPAuthBearerAuthError('missing_required_scopes')

    # 新しい todo を作成
    created_todo = todo_service.create_todo(content=content, owner_id=user_id)

    # 作成した todo を返す
    return created_todo.__dict__

# ...

サンプルコード で他の詳細実装も確認できます。

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

MCP サーバーを再起動し、ブラウザで MCP inspector を開きます。「Connect」ボタンをクリックすると、認可サーバーのサインインページにリダイレクトされます。

サインインして MCP inspector に戻ったら、前回のチェックポイントと同じ操作で 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 inspector の「Disconnect」ボタンをクリック）
  2. 別のロール／権限を持つユーザーアカウントでサインイン
  3. 同じツールを再度試し、ユーザーの権限による挙動の違いを確認

これにより、ロールベースのアクセス制御 (RBAC) が実際にどのように機能するかを体験できます。

MCP inspector todo manager tool result

情報

MCP Auth Python SDK リポジトリ で MCP サーバー（OIDC 版）の完全なコードを確認できます。

締めくくり​

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

  • Todo 管理ツール（create-todo, get-todos, delete-todo）付きの基本的な MCP サーバーのセットアップ
  • ユーザーと管理者で異なる権限レベルを持つロールベースのアクセス制御 (RBAC) の実装
  • MCP サーバーを MCP Auth で認可サーバーと統合
  • MCP Inspector でユーザー認証とスコープ付きアクセストークンを使ったツール呼び出し

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