docs: update comments for ScopesSupported (envoyproxy#1612)

Author: zhaohuabing

api/v1alpha1/mcp_route.go

@@ -262,7 +262,13 @@ type ProtectedResourceMetadata struct {
 	// +optional
 	ResourceName *string `json:"resourceName,omitempty"`
 
-	// ScopesSupported is a list of OAuth 2.0 scopes that the resource server supports.
+	// ScopesSupported defines the minimal set of scopes required for the basic functionality of the MCPRoute.
+	// It should avoid broad or overly permissive scopes to prevent clients from requesting tokens with excessive privileges.
+	//
+	// If an operation requires additional scopes that are not present in the access token, the client will receive a
+	// 403 Forbidden response that includes the required scopes in the `scope` field of the `WWW-Authenticate` header.
+	// This enables incremental privilege elevation through targeted `WWW-Authenticate: scope="..."` challenges when
+	// privileged operations are first attempted.
 	//
 	// +kubebuilder:validation:Optional
 	// +kubebuilder:validation:MaxItems=32

manifests/charts/ai-gateway-crds-helm/templates/aigateway.envoyproxy.io_mcproutes.yaml

@@ -4112,8 +4112,14 @@ spec:
                             minItems: 1
                             type: array
                           scopesSupported:
-                            description: ScopesSupported is a list of OAuth 2.0 scopes
-                              that the resource server supports.
+                            description: |-
+                              ScopesSupported defines the minimal set of scopes required for the basic functionality of the MCPRoute.
+                              It should avoid broad or overly permissive scopes to prevent clients from requesting tokens with excessive privileges.
+
+                              If an operation requires additional scopes that are not present in the access token, the client will receive a
+                              403 Forbidden response that includes the required scopes in the `scope` field of the `WWW-Authenticate` header.
+                              This enables incremental privilege elevation through targeted `WWW-Authenticate: scope="..."` challenges when
+                              privileged operations are first attempted.
                             items:
                               type: string
                             maxItems: 32

site/docs/api/api.mdx

@@ -1811,7 +1811,7 @@ References:
   name="scopesSupported"
   type="string array"
   required="false"
-  description="ScopesSupported is a list of OAuth 2.0 scopes that the resource server supports."
+  description="ScopesSupported defines the minimal set of scopes required for the basic functionality of the MCPRoute.<br />It should avoid broad or overly permissive scopes to prevent clients from requesting tokens with excessive privileges.<br />If an operation requires additional scopes that are not present in the access token, the client will receive a<br />403 Forbidden response that includes the required scopes in the `scope` field of the `WWW-Authenticate` header.<br />This enables incremental privilege elevation through targeted `WWW-Authenticate: scope=`...`` challenges when<br />privileged operations are first attempted."
 /><ApiField
   name="resourceSigningAlgValuesSupported"
   type="string array"