MCPAuthzConfig

MCPAuthzConfig defines a reusable authorization policy that is decoupled from a particular authorizer backend. MCPServer, MCPRemoteProxy, and VirtualMCPServer reference an MCPAuthzConfig via spec.authzConfigRef (or spec.incomingAuth.authzConfigRef on VirtualMCPServer), mutually exclusive with the inline authzConfig field.

Workload controllers resolve authzConfigRef into a runtime authorization config and apply it to the proxy, and each config controller blocks deletion while any workload still references it. For walkthroughs, see Share policies across resources with MCPAuthzConfig.

VirtualMCPServer is Cedar-only

VirtualMCPServer.spec.incomingAuth.authzConfigRef only supports MCPAuthzConfig resources with spec.type: cedarv1. Referencing a non-Cedar config (for example, httpv1) fails reconciliation with a clear condition message because the vMCP runtime authorization middleware is Cedar-only.

API: toolhive.stacklok.dev/v1beta1 · Scope: Namespaced · Short names: authzcfg

Example

mcpauthzconfig.yaml

apiVersion: toolhive.stacklok.dev/v1beta1
kind: MCPAuthzConfig
metadata:
  name: my-mcpauthzconfig
  namespace: default
spec:
  config: {}
  type: <string>

Schema

spec

MCPAuthzConfigSpec defines the desired state of MCPAuthzConfig. MCPAuthzConfig resources are namespace-scoped and can only be referenced by MCPServer, MCPRemoteProxy, or VirtualMCPServer resources in the same namespace.

Field	Type	Description
configrequired	object	Config contains the backend-specific authorization configuration. The structure depends on the Type field: - cedarv1: policies ([]string), entities_json (string), primary_upstream_provider (string), group_claim_name (string) - httpv1: http ({url, timeout, insecure_skip_verify}), context ({include_args, include_operation}), claim_mapping (string)
typerequired	string	Type identifies the authorizer backend (e.g., "cedarv1", "httpv1"). Must match a registered authorizer type in the factory registry. minLength 1

status

MCPAuthzConfigStatus defines the observed state of MCPAuthzConfig

Field	Type	Description
conditions	object[]	Conditions represent the latest available observations of the MCPAuthzConfig's state
configHash	string	ConfigHash is a hash of the current configuration for change detection
observedGeneration	integer	ObservedGeneration is the most recent generation observed for this MCPAuthzConfig. format int64

status.conditions[]

Conditions represent the latest available observations of the MCPAuthzConfig's state

Field	Type	Description
lastTransitionTimerequired	string	lastTransitionTime is the last time the condition transitioned from one status to another. This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable. format date-time
messagerequired	string	message is a human readable message indicating details about the transition. This may be an empty string. maxLength 32768
observedGeneration	integer	observedGeneration represents the .metadata.generation that the condition was set based upon. For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date with respect to the current state of the instance. format int64 · min 0
reasonrequired	string	reason contains a programmatic identifier indicating the reason for the condition's last transition. Producers of specific condition types may define expected values and meanings for this field, and whether the values are considered a guaranteed API. The value should be a CamelCase string. This field may not be empty. pattern ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$ · minLength 1 · maxLength 1024
statusrequired	string	status of the condition, one of True, False, Unknown. enum: True | False | Unknown
typerequired	string	type of condition in CamelCase or in foo.example.com/CamelCase. pattern ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$ · maxLength 316

↑ Back to status

Related resources

Referenced by:

• MCPRemoteProxy - via spec.authzConfigRef
• MCPServer - via spec.authzConfigRef
• VirtualMCPServer - via spec.incomingAuth.authzConfigRef