googleapis/mcp-toolbox · error

`scopesRequired` is not allowed when `mcpEnabled` is false

Error message

`scopesRequired` is not allowed when `mcpEnabled` is false

What it means

scopesRequired (scopes the token must contain) is only supported in MCP mode for the generic auth service. Initialize rejects a non-empty ScopesRequired list when McpEnabled is false, since legacy-mode validation never checks scopes.

Source

Thrown at internal/auth/generic/generic.go:75

func (cfg Config) IsMCPEnabled() bool {
	return cfg.McpEnabled
}

// Initialize a generic auth service
func (cfg Config) Initialize() (auth.AuthService, error) {
	if !cfg.McpEnabled {
		if cfg.IntrospectionEndpoint != "" {
			return nil, fmt.Errorf("`introspectionEndpoint` is not allowed when `mcpEnabled` is false")
		}
		if cfg.IntrospectionMethod != "" {
			return nil, fmt.Errorf("`introspectionMethod` is not allowed when `mcpEnabled` is false")
		}
		if cfg.IntrospectionParamName != "" {
			return nil, fmt.Errorf("`introspectionParamName` is not allowed when `mcpEnabled` is false")
		}
		if len(cfg.ScopesRequired) > 0 {
			return nil, fmt.Errorf("`scopesRequired` is not allowed when `mcpEnabled` is false")
		}
	}
	httpClient := newSecureHTTPClient()

	// Discover OIDC endpoints
	jwksURL, introspectionURL, issuer, err := discoverOIDCConfig(httpClient, cfg.AuthorizationServer)
	if err != nil {
		return nil, fmt.Errorf("failed to discover OIDC config: %w", err)
	}

	// Override introspection URL if configured
	if cfg.IntrospectionEndpoint != "" {
		introspectionURL = cfg.IntrospectionEndpoint
	}

	// Create the keyfunc to fetch and cache the JWKS in the background
	kf, err := keyfunc.NewDefault([]string{jwksURL})
	if err != nil {

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Enable mcpEnabled: true if scope enforcement is required
2. Remove scopesRequired for legacy-mode deployments (legacy mode validates JWT signature/claims only)
3. Switch the deployment to MCP mode to get scopes + introspection support

Example fix

// before
kind: generic
mcpEnabled: false
scopesRequired: [read:tools]
// after
kind: generic
mcpEnabled: true
scopesRequired: [read:tools]

mcp=$(yq '.authServices.my-auth.mcpEnabled' auth.yaml)
scopes=$(yq '.authServices.my-auth.scopesRequired' auth.yaml)
if [ "$mcp" != "true" ] && [ "$scopes" != "null" ] && [ "$scopes" != "[]" ]; then
  echo "scopesRequired requires mcpEnabled: true"; exit 1
fi

When it happens

Trigger: kind: generic auth service with mcpEnabled: false and a non-empty scopesRequired list in the YAML.

Common situations: Hardening a legacy deployment by copying scopesRequired from an MCP config; leaving scopesRequired after disabling MCP; assuming scopes work in legacy JWT validation.

Related errors

• `introspectionEndpoint` is not allowed when `mcpEnabled` is
• `introspectionMethod` is not allowed when `mcpEnabled` is fa
• `introspectionParamName` is not allowed when `mcpEnabled` is
• failed to check auth requirements: %w
• MCP Auth cannot be enabled together with the legacy HTTP API

AI-assisted analysis of googleapis/mcp-toolbox@8cc6e09de2 (2026-09-05). Data as JSON: /api/errors/d466df6b081c2d5e. Report an issue: GitHub.