Claude Code ガイド

Appearance

MCP OAuth設定オーバーライドがリスタート後のトークンリフレッシュで無効になっていた問題の修正 ​

原文（日本語に翻訳） ​

リスタート後のトークンリフレッシュ時に、MCP OAuthのoauth.authServerMetadataUrl設定オーバーライドが反映されていなかった問題を修正しました。ADFSや類似のIdP（アイデンティティプロバイダー）に影響していました。

原文（英語） ​

Fixed MCP OAuth oauth.authServerMetadataUrl config override not being honored on token refresh after restart, affecting ADFS and similar IdPs

概要 ​

MCP（Model Context Protocol）の認証にOAuthを使用している環境で、oauth.authServerMetadataUrlを設定オーバーライドとして指定していた場合、Claude Codeのリスタート後に行われるトークンリフレッシュ時にこの設定が無視されていました。特に、標準的なOAuth メタデータエンドポイントを持たないADFS（Active Directory Federation Services）や類似のエンタープライズIdPを使用している場合に認証が失敗する問題でした。v2.1.98でこの問題が修正され、リスタート後もカスタムのメタデータURLが正しく使用されます。

基本的な使い方 ​

修正前の動作（問題のある挙動） ​

json
// .claude/settings.json でカスタム OAuth メタデータURLを設定
{
  "mcp": {
    "oauth": {
      "authServerMetadataUrl": "https://adfs.company.com/adfs/.well-known/openid-configuration"
    }
  }
}
# 修正前の動作
$ claude  # 初回起動 → 認証成功（カスタムURLを使用）
[作業中...]

$ claude  # 再起動後のトークンリフレッシュ
Error: Failed to refresh OAuth token
# → リスタート後はカスタムURLが無視され、デフォルトURLでリフレッシュを試みるため失敗

修正後の動作（v2.1.98以降） ​

# 修正後の動作
$ claude  # 初回起動 → 認証成功
[作業中...]

$ claude  # 再起動後のトークンリフレッシュ
# → カスタムURLが正しく使用され、認証成功

実践例 ​

シナリオ1：ADFSを使った企業認証環境（修正後） ​

企業でADFSを使用してClaude Code MCPサーバーを認証している場合の設定例です。

json
// .claude/settings.json
{
  "mcp": {
    "servers": {
      "company-tools": {
        "url": "https://mcp-server.company.com",
        "auth": {
          "type": "oauth",
          "authServerMetadataUrl": "https://adfs.company.com/adfs/.well-known/openid-configuration",
          "clientId": "claude-code-app"
        }
      }
    }
  }
}

v2.1.98以降では、claudeを再起動した後もこの設定が正しく使用されます。

シナリオ2：カスタムIdPを使ったMCP認証（修正後） ​

ADFS以外のカスタムOAuthサーバーを使用している場合も同様に修正されます。

json
// カスタムOAuthプロバイダーの設定例
{
  "mcp": {
    "oauth": {
      "authServerMetadataUrl": "https://auth.internal.company.com/.well-known/oauth-authorization-server",
      "tokenEndpoint": "https://auth.internal.company.com/oauth/token"
    }
  }
}
bash
# 修正後：以下の操作サイクルが正常に動作する
$ claude  # 初回認証
# 作業...
$ claude  # 再起動後もトークンリフレッシュが正常に動作

シナリオ3：長時間セッションでのトークン自動リフレッシュ（修正後） ​

Claude Codeを長時間使用する際、バックグラウンドでのトークン自動リフレッシュも正しく機能します。

bash
# 長時間のコード作業セッション
$ claude
# ...長時間の作業中にトークンが期限切れ...
# 修正前：カスタムIdPを使用している場合、リフレッシュ失敗でセッション切断
# 修正後：authServerMetadataUrl が正しく使用され、自動的にトークンがリフレッシュ

シナリオ4：トラブルシューティング（修正後の確認方法） ​

修正が正しく適用されているか確認する方法：

bash
# Claude Code を再起動し、MCP接続が正常に動作するか確認
$ claude --mcp-debug  # MCPデバッグモードで起動
# OAuth トークンリフレッシュのログを確認
# authServerMetadataUrl が設定値通りに使用されていることを確認

注意点 ​

  • この修正はMCP OAuthにauthServerMetadataUrlカスタム設定を使用している場合にのみ影響します。標準的なOAuthプロバイダー（Google、GitHub等）を使用している場合は影響がありません。
  • ADFS（Active Directory Federation Services）を使用している企業環境では特に重要な修正です。v2.1.98への更新を推奨します。
  • トークンリフレッシュの問題が発生していた場合、v2.1.98にアップデートした後、一度ログアウト・ログインを行うと設定が正しく適用されます。
  • MCPサーバーとの接続に問題が続く場合は、~/.claude/配下の認証情報キャッシュをクリアして再認証することを試してください。

関連情報 ​