PKCE を使用した MCP OAuth 2.1: 7 つのステップでエージェント サーバーを保護します

2026-03-15 MCP 仕様は、PKCE を認証標準として OAuth 2.1 をロックします。 リモート MCP サーバー。 環境変数内の API キーは初日から機能しますが、レジストリは Claude Desktop、Cursor、VS Code Copilot、および Windsurf はすべて、ユーザーが次のような場合に OAuth ベースのサーバーを優先します。 統合を参照します。 サーバーが依然として構成ファイル内で長寿命ベアラーを要求する場合は、 配布の一部をテーブルの上に残しています。

難しい部分は OAuth 自体ではありません。 MCP 認証フローを構成する 5 つの小さな仕様です。 組み合わせ: OAuth 2.1 (RFC 9700)、PKCE (RFC 7636)、動的クライアント登録 (RFC 7591)、 リソース インジケーター (RFC 8707)、および保護されたリソース メタデータ。 それぞれは小さいです。 配線 そこがチームが行き詰まるところだ。 ここに順番にパスを示します。

ステップ 1: 保護されたリソースのメタデータ ドキュメントを提供する

PRM ファイルは、認証サーバーがどこにあるか、どのスコープを受け入れるか、そして何を受け入れるかをクライアントに伝えます。 に入れるリソース識別子 aud 請求。 でホストしてください /.well-known/oauth-protected-resource MCP エンドポイントと同じオリジン上:

の authorization_servers list は検出ホップです。 クライアントは PRM を取得し、 AS メタデータ ドキュメントの最初のエントリに従い、そこから認証 URL を構築します。 フェデレーションを実行しない限り、リストは 1 つのエントリに留めてください。 複数の発行者がクライアントを混乱させ、 仕様にはそれが必要なものはありません。

ステップ 2: 認可サーバーのメタデータを公開する

ID プロバイダー (Auth0、Okta、Clerk、Cloudflare Access、またはセルフホスト型 Hydra) がサービスを提供します。 AS メタデータ /.well-known/oauth-authorization-server。 MCP クライアントがそれを消費します 承認エンドポイントとトークンエンドポイント、サポートされている付与タイプ、および JWKS の場所を確認するには トークン検証の場合:

仕様で要求される 3 つのフィールド: code_challenge_methods_supported 含める必要があります S256; grant_types_supported 含める必要があります authorization_code そして refresh_token; registration_endpoint 動的クライアントをサポートする場合は、このファイルが存在する必要があります。 どれかが欠けている Claude Desktop は、セットアップ中にサーバーに非準拠としてフラグを立てます。

ステップ 3: クライアント上で PKCE ペアを生成する

PKCE は 20 行のクライアント コードであり、次の認証コード インターセプト クラスを強制終了します。 攻撃する。 32 のランダムなバイトを生成し、それらを Base64URL エンコードしてベリファイアーに変換し、SHA-256 でベリファイアーします。 をチャレンジに組み込み、承認リクエストとともにチャレンジを送信します。

の resource パラメータ (RFC 8707) は、ほとんどの実装で欠落しているものです。 なし これにより、MCP サーバー用に作成されたトークンは、そのサーバーを信頼する他の API に対して再生できます。 同じ発行者。 それとともに、 aud クレームはトークンをリソース識別子に固定します そして他にそれを受け入れるものはありません。

ステップ 4: コードをトークンに交換する

リダイレクトが戻った後、クライアントはコードと元の検証子をトークンに POST します。 エンドポイント。 認可サーバーは検証者の SHA-256 を再計算し、それを検証者の SHA-256 と比較します。 保存されたチャレンジ。 一致する場合、アクセス トークンを取得します。

リフレッシュ トークンを安全なストレージ (キーチェーン、Windows Credential Manager、Linux) に保存します。 libsecret) を実行し、交換が成功した瞬間にセッション ストレージからベリファイアを削除します。 アクセス トークンの有効期間は 5 ～ 60 分です。 リフレッシュ トークンはより長く存続しますが、使用時にローテーションする必要があります。

ステップ 5: すべての MCP リクエストでベアラー トークンを検証する

ストリーミング可能な HTTP により、トークンの検証が簡単になります。各 HTTP リクエストには、 Authorization ヘッダーなので、MCP サーバーは前にミドルウェアでそれを検証します。 ツール呼び出しをディスパッチします。 JWKS を一度取得してキャッシュし、発行者、対象者、および すべての呼び出しで有効期限が切れます:

実際のバグを捕捉する 3 つの主張: iss 発行者を固定します。 aud リソースを固定します (リソース間の再生を防止します)。 exp 古いトークンをキャッチします。 これらのないトークンは受け入れないでください。 「私が検証したのは、 「署名」は「私は主張を検証しました」と同じではありません。

ステップ 6: アノテーションが宣言するスコープで各ツールをゲートします。

OAuth 2.1 マイナス スコープ設計により、バイナリ アクセスが可能になります。クライアントはすべてのツールを呼び出すことができます。 なし。 MCP アノテーション システムは、各ツールにスコープを宣言させることでそのギャップを埋めます。 ニーズがあります。 ハンドラーは、呼び出し時にアノテーションとトークン スコープを読み取ります。

破壊的スコープと読み取り専用スコープを分離してください。 許可したユーザー tools:read に 週次レポートを実行することはできません send_email 同じトークンから。 クロード デスクトップとカーソル サーフェスは同意画面でスコープを要求したため、分割により クライアントが何ができるかについて正直なUX。

ステップ 7: 動的クライアント登録のサポート

動的クライアント登録により、MCP クライアントが認可サーバーに自己登録できるようになります 人間がフォームに記入する必要はありません。 カーソルまたはクロード デスクトップが登録リクエストを POST します。 を受け取ります client_idし、OAuth フローをすぐに実行します。

これは、MCP サーバーを「構成ファイルに API キーを貼り付ける」状態から次の状態に移行する部分です。 「カーソルで接続をクリックしてアクセスを許可します。」 サーバーが公開されている場合は、取り組む価値があります。 スキップ可能 少数の既知の顧客にのみ発送する場合。

完全なフローをエンドツーエンドで検証する

これらの要素が配置されると、完全な MCP ツール呼び出しは他のベアラー認証された呼び出しと同じように見えます。 HTTPリクエスト:

見たら 401 と WWW-Authenticate: Bearer resource_metadata="..."、 クライアントは、認証設定を検出してフローを再実行する場所を知っています。 そのヘッダーは、 取り消し後のサイレント トークンの更新と再接続を可能にするハンドシェイク。

スコープ設計チートシート

重要なポイント

• OAuth 2.1 には PKCE が必要です。 あったら便利というわけではありません。 すべての認証コード フローには、 検証者とチャレンジを行うか、仕様準拠に失敗します。
• PRM で /.well-known/oauth-protected-resource がエントリーポイントです。 クライアントは、その 1 つの URL から認証設定を検出します。 これをスキップすると、クライアントは自動構成できなくなります。
• を使用します。 resource パラメータ (RFC 8707)。 トークンの対象ユーザーを固定します 漏洩したトークンが他の API に対して再生できないように、MCP サーバーに送信します。
• 発行者、対象者、有効期限、範囲を検証します。 署名小切手だけでも構いません クロスリソースリプレイスルー。
• 破壊的なスコープを分割します。 tools:read、 tools:invoke:safe、 そして tools:invoke:destructive ユーザーに与える OS の権限に期待する同意 UX。
• 動的クライアント登録により、ゼロ構成インストールのロックが解除されます。 を支払う 1 回の実装コスト。 すべての新しい MCP クライアントは永久にメリットを享受できます。

Botoi がホストする MCP サーバーは次のとおりです。 api.botoi.com/mcp 同じパターンで実行されます。 閲覧する MCP セットアップ ドキュメント Claude Desktop、Claude Code、Cursor、VS Code、および Windsurf 構成用。 JWT署名の場合 上記のミドルウェアが使用する検証プリミティブについては、 JWT API エンドポイント インタラクティブドキュメントで。