Claude Code ガイド

Appearance

原文（日本語に翻訳） ​

MCPのOAuth認証で、スコープが指定されていない場合に認可サーバーの scopes_supported カタログ全体をリクエストしてしまい、GitLabセルフホスト版などのエンタープライズIdPで invalid_scope エラーが発生する問題を修正

原文（英語） ​

Fixed MCP OAuth requesting the authorization server's full scopes_supported catalog when no scope is specified, causing invalid_scope failures on GitLab self-hosted and other enterprise IdPs

概要 ​

MCPサーバーへのOAuth認証で、scopeが明示的に設定されていない場合、Claude Codeが認可サーバーの提供する scopes_supported のカタログをそのまま全部リクエストしてしまう不具合がありました。GitLabセルフホスト版など、管理者専用スコープを含む多くのスコープを公開しているエンタープライズIdP（Identity Provider）では、これが原因で invalid_scope エラーとなり認証に失敗していました。v2.1.196でこの挙動が修正され、より妥当なスコープ選択ロジックが使われるようになりました。

基本的な使い方 ​

json
// .mcp.json でのOAuth設定例（scopeを明示的に指定する）
{
  "mcpServers": {
    "gitlab-mcp": {
      "type": "http",
      "url": "https://gitlab.example.com/mcp",
      "oauth": {
        "scopes": ["mcp", "read_api"]
      }
    }
  }
}

実践例 ​

GitLabセルフホスト版MCPサーバーへの接続 ​

【修正前】
1. Claude CodeがMCP接続を開始
2. 認可サーバーの scopes_supported を丸ごと取得
3. 管理者専用スコープなども含めてリクエスト
4. GitLabが要求スコープを許可できないと判断
5. 結果: invalid_scope エラーで認証失敗

【修正後】
1. Claude CodeがMCP接続を開始
2. サーバー側から提示される必要最小限のスコープ、
   または明示的に設定されたスコープのみをリクエスト
3. 結果: 認証成功

scopeを明示的に指定する設定 ​

json
// .mcp.json（プロジェクトレベル）
{
  "mcpServers": {
    "gitlab-self-hosted": {
      "type": "http",
      "url": "https://gitlab-internal.company.com/mcp",
      "oauth": {
        "scopes": ["mcp"]
      }
    }
  }
}

修正前後の挙動比較 ​

bash
# 修正前: scopeを指定していない場合のエラー
claude mcp connect gitlab-self-hosted
# エラー: invalid_scope - The requested scope is invalid

# 修正後: scopeを指定しない場合も適切なスコープのみが要求される
claude mcp connect gitlab-self-hosted
# 認証成功

注意点 ​

  • 影響を受けるのは、エンタープライズ向けのセルフホストIdP（GitLabセルフホスト版など）で多数のスコープを公開している場合です。Anthropicが提供する標準的なMCPサーバーでは通常問題になりません
  • 安全のため、エンタープライズ環境でMCPサーバーを設定する際は oauth.scopes でスコープを明示的に指定することを推奨します
  • このバージョン以前に invalid_scope エラーで接続できなかったMCPサーバーがある場合は、アップグレード後に再接続を試してください

関連情報 ​