MCP OAuth + Dynamic Client Registration

概要

リモート MCP サーバーが静的ベアラートークンで設定できず、代わりに OAuth 2.1 認可を必要とする場合は、このスキルを使用します。ホストされている多くの MCP サーバーは、保護されたリソースメタデータ、Dynamic Client Registration (DCR)、Authorization Code + PKCE、およびリフレッシュトークンを使用します。

目標は、サーバーの OAuth メタデータを検出し、Hermes または別の MCP クライアントを動的に登録し、ブラウザベースの承認ステップを通じてアクセストークンを取得し、トークンセットを安全に保存し、アクセストークンの有効期限が切れたときに自動的にリフレッシュすることです。

使用するタイミング

以下の場合に使用します:

• リモート MCP エンドポイントが WWW-Authenticate ヘッダー付きで 401 Unauthorized を返す
• WWW-Authenticate ヘッダーに resource_metadata=... が含まれている
• MCP プロバイダーが静的 API キーまたは長期的なベアラートークンを提供していない
• プロバイダーが OAuth 2.1、PKCE、または Dynamic Client Registration を想定している
• アクセストークンの有効期限が切れた後に MCP 呼び出しが失敗を始め、リフレッシュトークンを使用する必要がある

以下の場合は使用しないでください:

• npx、uvx、または別のローカルコマンドで起動されたローカル stdio MCP サーバー
• すでに静的ベアラートークンを提供し、OAuth を必要としないリモート MCP サーバー
• プロバイダーが同じメタデータおよび PKCE パターンに従わない限り、非 MCP OAuth 統合

必要な概念

• 保護されたリソースメタデータ: リソースサーバーによって公開される OAuth メタデータ。通常は WWW-Authenticate レスポンスから検出されます
• 認可サーバーメタデータ: OAuth サーバーメタデータ。通常は発行者の /.well-known/oauth-authorization-server で利用可能です
• Dynamic Client Registration (DCR): クライアントが自己登録し、実行時に client_id を受け取るフロー
• PKCE: Proof Key for Code Exchange。パブリッククライアントは code_verifier を生成し、認可中に派生した code_challenge を送信します
• アクセストークン: MCP リクエストの Authorization: Bearer ... ヘッダーで使用される短期間のトークン
• リフレッシュトークン: ユーザーの再承認を求めずに新しいアクセストークンを取得するために使用される長期間のトークン
• State: OAuth コールバックが開始した認可リクエストに属することを検証するために使用されるランダム値

ディスカバリーフロー

1. MCP エンドポイントをプローブします

   認証情報なしで MCP サーバー URL にリクエストを送信するか、失敗をテストしている場合は現在の認証情報を使用して送信します

   OAuth で保護されたサーバーの期待される結果:

   HTTP/1.1 401 Unauthorized
   WWW-Authenticate: Bearer resource_metadata="https://example.com/.well-known/oauth-protected-resource"
   

2. WWW-Authenticate ヘッダーから resource_metadata URL を抽出します

3. 保護されたリソースメタデータを取得します

   以下のようなフィールドを探します:

   • resource
   • authorization_servers
   • scopes_supported
   • bearer_methods_supported

4. 認可サーバーの発行者を特定します

   保護されたリソースメタデータから発行者または認可サーバー URL を使用します

5. 認可サーバーメタデータを取得します

   一般的なパス:

   <issuer>/.well-known/oauth-authorization-server
   

   以下を探します:

   • authorization_endpoint
   • token_endpoint
   • registration_endpoint
   • grant_types_supported
   • response_types_supported
   • code_challenge_methods_supported
   • token_endpoint_auth_methods_supported

Dynamic Client Registration フロー

認可サーバーメタデータから registration_endpoint でパブリッククライアントを登録します

以下のようなペイロードを使用します:

{
  "client_name": "Hermes MCP Client",
  "redirect_uris": ["http://127.0.0.1:49152/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none"
}

ガイドライン:

• 一時的なポート上のローカルホストリダイレクト URI を使用します
• プロバイダーがリダイレクトマッチングについて厳密な場合は、localhost の代わりに 127.0.0.1 を使用します
• プロバイダーがリフレッシュトークンをサポートしている場合は、authorization_code と refresh_token の両方のグラントをリクエストします
• パブリッククライアントに対して token_endpoint_auth_method: none を使用します。ただし、登録レスポンスでクライアントシークレットが提供され、クライアント認証が明示的に必要とされている場合を除きます
• 返された client_id を保存します。一部のプロバイダーは client_secret、client_id_issued_at、または client_secret_expires_at も返す可能性があります

Authorization Code + PKCE フロー

1. ログイン試行ごとに新しい OAuth 値を生成します:

   • state: 高エントロピーのランダム文字列
   • code_verifier: 高エントロピーのランダム文字列
   • code_challenge: ベリファイアの SHA-256 ハッシュの base64url エンコード
   • code_challenge_method: S256

2. メタデータから authorization_endpoint を使用して認可 URL を構築します

   以下を含めます:

   • authorize_url=https://app.superleap.com/api/v1/oauth/authorize
   • response_type=code
   • client_id=<dynamic client id>
   • redirect_uri=<exact registered redirect uri>
   • state=<random state>
   • code_challenge=<S256 challenge>
   • code_challenge_method=S256
   • プロバイダーが RFC 8707 リソースインジケータを必要とする場合は resource=<MCP resource URL>
   • メタデータまたはプロバイダードキュメントでスコープが必要な場合は scope=<requested scopes>

3. 認可 URL をブラウザで開くか、ユーザーに提示します

   https://<subdomain>.superleap.com/mcp/authorize?authorize_url=https://app.superleap.com/api/v1/oauth/authorize&client_id=<client_id>&redirect_uri=<redirect_uri>&code_challenge=<code_challenge>&state=<state>&code_challenge_method=S256&resource=<resource>&response_type=code&client_name=<yourname>
   

4. リダイレクト URI ポートで一時的なローカルホストコールバックリスナーを実行します

5. プロバイダーがリダイレクト バックするときに、以下を検証します:

   • コールバックに code が含まれている
   • 返された state が保存されたステートと完全に一致する
   • error または error_description がある場合は処理し、明確に表示される

6. トークンエンドポイントで認可コードを交換します

   フォームエンコードされたパラメータを使用します:

   grant_type=authorization_code
   code=<authorization code>
   redirect_uri=<exact redirect uri>
   client_id=<dynamic client id>
   code_verifier=<original code verifier>
   resource=<MCP resource URL, if required by provider>
   

7. トークンレスポンスを安全に保存します

   典型的なレスポンスフィールド:

   • access_token
   • token_type
   • expires_in
   • refresh_token
   • scope

8. 以下で MCP 接続を再試行します:

   Authorization: Bearer <access_token>
   

Superleap テナント/サブドメインルール (重要)

Superleap MCP URL では、ホスト名 mcp.superleap.com または OAuth 発行者 app.superleap.com からユーザー向けテナントを推測しないでください

MCP リソース URL パスからテナントサブドメインを導き出します:

https://mcp.superleap.com/<tenant>/mcp

例:

MCP リソース URL: https://mcp.superleap.com/apple/mcp
テナント/サブドメイン: apple
保護されたリソースメタデータ: https://mcp.superleap.com/apple/.well-known/oauth-protected-resource

重要なルール:

• MCP URL が https://mcp.superleap.com/apple/mcp の場合、常に apple をテナント/サブドメインとして使用します
• リソースインジケータが必要な場合、OAuth 認可 URL およびトークンリクエストで resource=https://mcp.superleap.com/apple/mcp を保持します
• MCP URL にテナントパスが含まれておらず、テナントが別の場所で提供されていない場合にのみ、テナント/サブドメイン app にフォールバックします

リフレッシュトークンフロー

アクセストークンの有効期限が切れているか、有効期限が近い場合はいつでもリフレッシュトークンを使用します

推奨される動作:

• アクセストークンが発行された時刻を追跡します
• expires_at = issued_at + expires_in を計算します
• 有効期限の 60～300 秒前など、期限切れになる前に先制的にリフレッシュします
• MCP リクエストが 401 Unauthorized を返し、トークンの有効期限が近い場合または期限切れの場合は、1 回リフレッシュしてリクエストを再試行します
• リフレッシュが invalid_grant、invalid_client、または失効/期限切れのリフレッシュトークンで失敗した場合は、保存されたトークンセットを破棄し、完全な認可フローを再開します

トークンリフレッシュリクエスト:

grant_type=refresh_token
refresh_token=<stored refresh token>
client_id=<dynamic client id>
resource=<MCP resource URL, if required by provider>
scope=<optional scopes, only if provider requires or allows narrowing>

クライアントが token_endpoint_auth_method: none を使用するパブリッククライアントとして登録された場合は、クライアントシークレットを送信しないでください。プロバイダーがクライアントシークレットを発行し、クライアント認証を必要とする場合は、メタデータおよび登録レスポンスからトークンエンドポイント認証方法に従います

リフレッシュ後:

• 古いアクセストークンを新しいアクセストークンに置き換えます
• 新しい expires_in から expires_at を更新します
• レスポンスに新しい refresh_token が含まれている場合は、古いリフレッシュトークンを置き換えます。一部のプロバイダーはリフレッシュトークンをローテーションします
• 新しいリフレッシュトークンが返されない場合は、既存のリフレッシュトークンを保持します
• 新しいアクセストークンで MCP リクエストを 1 回再試行します

リフレッシュを無限ループしないでください。失敗した MCP リクエストごとに 1 回のリフレッシュと再試行で通常は十分です。繰り返される失敗は再認可またはエラーをトリガーする必要があります

トークンストレージのガイダンス

OAuth ステートとトークンをプロンプトとログの外に保存します

以下を永続化します:

• issuer
• resource
• client_id
• client_secret (発行されて必要な場合のみ)
• redirect_uri
• access_token
• refresh_token
• expires_at
• scope
• ディスカバリーに使用されたプロバイダーメタデータ URL

トークンを LLM、ターミナル出力、git 履歴、またはイシューコメントに公開しないでください。以下をマスクします:

• ベアラートークン
• リフレッシュトークン
• 認可コード
• クライアントシークレット
• code を含む完全なコールバック URL

アプリケーションがシークレットマネージャーを持たない場合は、OS キーチェーン、暗号化された認証情報ストア、または厳密なアクセス権限を持つローカルファイルを使用することをお勧めします

プロバイダー固有の例: Superleap <subdomain> MCP

観察されたプロバイダーの詳細:

• 保護されたリソースメタデータ:

  https://mcp.superleap.com/<subdomain>/.well-known/oauth-protected-resource
  

• 認可サーバーメタデータ:

  https://app.superleap.com/.well-known/oauth-authorization-server
  

• Dynamic Client Registration エンドポイント:

  POST https://app.superleap.com/api/v1/oauth/register
  

• メタデータからの認可エンドポイント:

  https://app.superleap.com/api/v1/oauth/authorize
  

このプロバイダーでは、サーバーがリソースインジケータを必要とする場合、認可リクエストおよびトークンリクエストで MCP リソース URL を resource= として含めます

https://<subdomain>.superleap.com/mcp/authorize?authorize_url=https://app.superleap.com/api/v1/oauth/authorize&client_id=<client_id>&redirect_uri=<redirect_uri>&code_challenge=<code_challenge>&state=<state>&code_challenge_method=S256&resource=<resource>&response_type=code&client_name=<yourname>

トークン取得後の Hermes 設定

MCP クライアントが有効なアクセストークンを持っており、組み込みの OAuth マネージャーがリフレッシュを処理していない場合は、リモート MCP サーバーを認可ヘッダー付きの HTTP MCP サーバーとして設定します:

mcp_servers:
  example_remote:
    url: "https://mcp.example.com/mcp"
    headers:
      Authorization: "Bearer <access_token>"
    timeout: 120
    connect_timeout: 60

重要:

• 静的 YAML ヘッダーはアクセストークンの有効期限が切れるまでしか機能しません
• 本番使用では、アクセストークンをリフレッシュし、MCP 呼び出しの前にリクエストヘッダーを更新する OAuth トークンマネージャーを追加または使用します
• ~/.hermes/config.yaml または共有リポジトリにトークンをコミットしないでください

よくある落とし穴

1. 保護されたリソースディスカバリーをスキップしています。 MCP エンドポイントは、期待される発行者またはメタデータパスと同じものを使用していない可能性があります。WWW-Authenticate ヘッダーから始めます

2. 古い PKCE 値を使用しています。 認可試行ごとに新しい state、code_verifier、および code_challenge を生成します

3. ベリファイアを失っています。 トークン交換には元の code_verifier が必要です。コールバックが完了するまで、保留中の認可試行とともに保存します

4. ステートを検証していません。 トークン交換の前に、返された state と保存されたステートを常に比較します

5. リダイレクト URI の不一致。 認可リクエストおよびトークン交換の redirect_uri は、登録されたリダイレクト URI のいずれかと完全に一致する必要があります

6. resource を省略しています。 一部の MCP OAuth プロバイダーは、認可リクエストとトークンリクエストの両方で MCP リソース URL を必要とします

7. リフレッシュトークンがローテーションされないと仮定しています。 リフレッシュレスポンスに新しいリフレッシュトークンが含まれている場合は、直ちに新しいトークンを保存します

8. 無限リトライループ。 401 で 1 回リフレッシュして 1 回再試行します。それでも失敗した場合は、再認可するかエラーを表示します

9. コードまたはトークンをリークしています。 コールバック URL には認可コードが含まれています。これらを秘密として扱い、ログから削除します

10. 非 PTY オートメーションで hermes mcp add を使用しています。 これはインタラクティブな TUI にフォールバックして失敗する可能性があります。スクリプト化されたセットアップの場合は、~/.hermes/config.yaml を直接編集し、hermes mcp list で検証します

11. プロバイダー固有のエンドポイントを無視しています。 メタデータが利用可能な場合は優先しますが、テスト中に検出されたプロバイダー固有のルートを保持します

検証チェックリスト

• MCP エンドポイントプローブが WWW-Authenticate メタデータを含む 401 またはドキュメント化された OAuth チャレンジを返す
• 保護されたリソースメタデータが取得され、MCP リソース識別子が記録された
• 認可サーバーメタデータが発行者から取得された
• Dynamic Client Registration が client_id を返した
• 認可 URL に PKCE、ステート、リダイレクト URI、および必要な場合はリソースが含まれている
• コールバックステートがトークン交換前に検証された
• トークン交換がアクセストークンを返した
• リフレッシュトークンが返された場合は保存されている
• アクセストークンの有効期限が expires_at タイムスタンプで追跡されている
• リフレッシュフローが実装され、アクセストークン有効期限の前にテストされている
• アクセストークン有効期限または関連する 401 でクライアントが 1 回リフレッシュして MCP リクエストを再試行する
• ローテーションされたリフレッシュトークンが古いリフレッシュトークンを置き換える
• トークン、コード、およびクライアントシークレットがログから削除され、コミットされていない
• 認可後に MCP 接続が成功する

最小実装疑似コード

connect_mcp(resource_url):
  token = load_token(resource_url)

  if token exists and access_token_expires_soon(token):
    token = refresh_access_token(token)
    save_token(token)

  response = mcp_initialize(resource_url, bearer=token.access_token if token else none)

  if response.status == 401 and has_resource_metadata(response):
    metadata = discover_metadata(response)
    client = register_client(metadata.registration_endpoint)
    auth_request = create_pkce_authorization_request(metadata, client)
    callback = ask_user_to_authorize_and_capture_callback(auth_request.url)
    validate_state(callback.state, auth_request.state)
    token = exchange_code_for_tokens(metadata.token_endpoint, callback.code, auth_request.code_verifier)
    save_token(token)
    return mcp_initialize(resource_url, bearer=token.access_token)

  if response.status == 401 and token has refresh_token:
    token = refresh_access_token(token)
    save_token(token)
    return mcp_initialize(resource_url, bearer=token.access_token)

  return response