diff --git a/api/v1alpha1/mcp_route.go b/api/v1alpha1/mcp_route.go index 5c037f89e..6c20241a1 100644 --- a/api/v1alpha1/mcp_route.go +++ b/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 diff --git a/manifests/charts/ai-gateway-crds-helm/templates/aigateway.envoyproxy.io_mcproutes.yaml b/manifests/charts/ai-gateway-crds-helm/templates/aigateway.envoyproxy.io_mcproutes.yaml index 1734e611b..322efff1f 100644 --- a/manifests/charts/ai-gateway-crds-helm/templates/aigateway.envoyproxy.io_mcproutes.yaml +++ b/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 diff --git a/site/docs/api/api.mdx b/site/docs/api/api.mdx index 66fb5147c..e41fec661 100644 --- a/site/docs/api/api.mdx +++ b/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.
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." />