googleapis/mcp-toolbox · error

`introspectionParamName` is not allowed when `mcpEnabled` is

Error message

`introspectionParamName` is not allowed when `mcpEnabled` is false

What it means

introspectionParamName (the form/header parameter name sent to the introspection endpoint) is MCP-mode-only. Initialize validates this before building the HTTP client and discovering OIDC endpoints, rejecting the config when McpEnabled is false.

Source

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

func (cfg Config) AuthServiceConfigType() string {
	return AuthServiceType
}

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
	}

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Set mcpEnabled: true when introspection parameters are required
2. Remove introspectionParamName from legacy-mode auth configs
3. Audit generated/templated configs for MCP-only fields

Example fix

// before
kind: generic
mcpEnabled: false
introspectionParamName: token
// after
kind: generic
mcpEnabled: true
introspectionParamName: token

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

When it happens

Trigger: kind: generic auth service with mcpEnabled: false and introspectionParamName set.

Common situations: Same as sibling errors: config drift after toggling mcpEnabled off, or inheriting a shared tools/auth YAML that includes introspection tuning parameters.

Related errors

• `introspectionEndpoint` is not allowed when `mcpEnabled` is
• `introspectionMethod` is not allowed when `mcpEnabled` is fa
• `scopesRequired` is not allowed when `mcpEnabled` is false
• 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/9668c8a7f15fdcf5. Report an issue: GitHub.