Descope 認証付き MCP サーバーテンプレート

Descope による完全な MCP 認証を備えた、Render 用のシンプルな FastMCP サーバーテンプレートです。

含まれているもの

• Streamable HTTP トランスポートを使用した FastMCP による動作可能な MCP サーバー

• FastMCP の DescopeProvider および descope-mcp SDK による完全な MCP 認可サポート

• "Hello, world!" を返し、ツールレベルのスコープ要件 (mcp:greet) を強制するサンプルツール (hello) が1つ

• 簡単にデプロイできる render.yaml ブループリント

注: このテンプレートはデフォルトで Render の無料プランにデプロイされます。無料サービスは15分間操作がないと停止し、次のリクエスト時に30〜60秒のコールドスタートが発生します。この遅延中に MCP クライアントがタイムアウトする可能性があります。確実に使用するには、Render ダッシュボードで有料プランにアップグレードしてください。Starter プランではサービスが継続的に実行されます。

Related MCP server: MCP Server Template

前提条件

• Python 3.13+

• uv

• Descope のアカウントとプロジェクト

Descope のセットアップ

1. Descope コンソールにログインします。

2. Agentic Identity Hub → MCP Servers に移動します。

3. + MCP Server をクリックして新しい MCP サーバーを作成し、名前を付けます。

4. MCP Client Registration で、Client ID Metadata Documents (CIMD) と Dynamic Client Registration (DCR) を有効にします。オプションで、CIMD を介して登録するクライアントの許可ドメインを制限できます (例: https://claude.ai)。このフィールドは空のままでも構いません。

5. MCP Server Scopes で、mcp:greet という名前のスコープと、「ユーザーに挨拶する」のような簡単な説明を追加します。

6. Create をクリックします。

7. 確認ページの Connect your MCP server to Descope セクションを展開します。

8. Well-Known URL をコピーします。以下のようになります。

   https://api.descope.com/v1/apps/agentic/.../.well-known/openid-configuration

   これが DESCOPE_CONFIG_URL です。

注: Descope は、MCP 仕様で要求されている通り、Resource Indicators (RFC 8707) に従ったトークンを発行します。Render にデプロイする場合やローカルで実行する場合は、MCP サーバー URL セクションを更新する必要があります。

Render へのデプロイ

DESCOPE_CONFIG_URL が必要になるため、ローカルで開発する前に Descope のセットアップ ステップを完了していることを確認してください。

1. このリポジトリを自分の GitHub アカウントにフォークします。

2. Deploy to Render をクリックします（または GitHub でこのリポジトリをフォークし、Render アカウントでブループリントとしてインポートします）。

   

3. 指定した構成で、環境変数を Descope のセットアップ ステップで取得した値に設定します。

   キー	値
   DESCOPE_CONFIG_URL	Descope コンソールからの Well-Known URL

4. Deploy Blueprint をクリックします。

5. ライブになったら、Render サービス URL (例: https://<your-project>.onrender.com) をコピーし、/mcp を追加して、Descope コンソールの MCP Server URLs に追加します。

これで、完全な認証仕様をサポートするリモートホストされた MCP サーバーが完成しました！

ローカル開発

DESCOPE_CONFIG_URL が必要になるため、ローカルで開発する前に Descope のセットアップ ステップを完了していることを確認してください。

まず、このリポジトリを自分の GitHub アカウントにフォークし、以下の手順に従って環境をセットアップします。

# Install dependencies
uv sync

# Set required environment variables
export DESCOPE_CONFIG_URL="<your URL from Descope>"
export SERVER_URL="http://localhost:8000"

# Run the server
uv run server.py --transport http --port 8000

ローカルで実行すると、サーバーは http://localhost:8000/mcp で実行されます。

利用可能なツール

次のステップ

セットアップが完了したら、MCP サーバーを本番環境に移行する場合に推奨される手順がいくつかあります。

独自のツールを追加する

server.py の hello ツールを独自のロジックに置き換えるか、拡張します。新しいツールごとに以下を行います。

1. Descope コンソールの MCP Server Scopes に新しいスコープを定義します (例: mcp:your-scope)。

2. @mcp.tool() デコレータを使用してツールを追加します。

3. ツール本体内で require_scopes(token, ["mcp:your-scope"]) を呼び出してアクセス制御を強制します。

4. 新しいツールとその必要なスコープを上記の 利用可能なツール テーブルに追加します。

@mcp.tool()
def my_tool() -> str:
    token = validate_token()
    require_scopes(token, ["mcp:your-scope"])
    return "your result"

Render でカスタムドメインを使用する

デフォルトでは、サービスには https://<your-project>.onrender.com からアクセスできます。カスタムドメインを使用するには:

1. Render ダッシュボードで、サービス → Settings → Custom Domains に移動します。

2. ドメインを追加し、提供された DNS 指示に従います。

3. ドメインが確認されたら、Descope コンソールの MCP Server URLs を更新してカスタムドメインを使用するようにします (例: https://mcp.yourdomain.com/mcp)。

4. コードの変更は不要です。RENDER_EXTERNAL_URL は Render によって自動的に設定され、プライマリドメインを反映します。

すべてのツールをスコープで保護する

require_scopes() チェックは、必要に応じて認証されていないツールを追加できるように、ツールごとに意図的にオプトインにしています。本番サーバーでは、すべてのツールで require_scopes() を呼び出すのが良い習慣です。また、validate_token() と require_scopes() をラップするヘルパーを作成し、各ツールハンドラーの先頭でそれを呼び出すことで、これを一元化することもできます。

MCP 認証の仕組み

1. MCP クライアント (Claude Desktop、Cursor など) は、MCP サーバーへの接続を試みる際に /.well-known/oauth-authorization-server から OAuth メタデータを検出します。

2. クライアントは (CIMD または DCR を介して) 認可サーバーに動的に登録し、ユーザーを Descope のログイン/同意フローにリダイレクトします。

3. ログイン後、Descope は署名付き JWT を発行します。クライアントはこれをすべての MCP リクエストの Bearer トークンとして含めます。

4. DescopeProvider は、ツールが呼び出される前に Descope の JWKS エンドポイントを使用して JWT を検証します。

5. ツール内では、validate_token() がクレームを解析し、require_scopes() が mcp:greet が存在することを確認します。存在しない場合はクライアントにエラーを返します。

詳細はこちら

• Render Blueprints

• MCP Authorization

• FastMCP

• Descope Agentic Identity Hub docs

• Descope MCP SDK