MCPOIDCConfig

MCPOIDCConfig defines OIDC authentication settings that can be shared across multiple MCP workloads. MCPServer, MCPRemoteProxy, and VirtualMCPServer reference an MCPOIDCConfig via spec.oidcConfigRef to validate incoming tokens.

API: toolhive.stacklok.dev/v1alpha1 · Scope: Namespaced · Short names: mcpoidc

Example

mcpoidcconfig.yaml

apiVersion: toolhive.stacklok.dev/v1alpha1
kind: MCPOIDCConfig
metadata:
  name: my-mcpoidcconfig
  namespace: default
spec:
  type: kubernetesServiceAccount

Schema

spec

MCPOIDCConfigSpec defines the desired state of MCPOIDCConfig. MCPOIDCConfig resources are namespace-scoped and can only be referenced by MCPServer resources in the same namespace.

Field	Type	Description
inline	object	Inline contains direct OIDC configuration. Only used when Type is "inline".
kubernetesServiceAccount	object	KubernetesServiceAccount configures OIDC for Kubernetes service account token validation. Only used when Type is "kubernetesServiceAccount".
typerequired	string	Type is the type of OIDC configuration source enum: kubernetesServiceAccount | inline

spec.inline

Inline contains direct OIDC configuration. Only used when Type is "inline".

Field	Type	Description
caBundleRef	object	CABundleRef references a ConfigMap containing the CA certificate bundle. When specified, ToolHive auto-mounts the ConfigMap and auto-computes ThvCABundlePath.
clientId	string	ClientID is the OIDC client ID
clientSecretRef	object	ClientSecretRef is a reference to a Kubernetes Secret containing the client secret
insecureAllowHTTP	boolean	InsecureAllowHTTP allows HTTP (non-HTTPS) OIDC issuers for development/testing. WARNING: This is insecure and should NEVER be used in production. default false
introspectionUrl	string	IntrospectionURL is the URL for token introspection endpoint
issuerrequired	string	Issuer is the OIDC issuer URL
jwksAllowPrivateIP	boolean	JWKSAllowPrivateIP allows JWKS/OIDC endpoints on private IP addresses. Note: at runtime, if either JWKSAllowPrivateIP or ProtectedResourceAllowPrivateIP is true, private IPs are allowed for all OIDC HTTP requests (JWKS, discovery, introspection). default false
jwksAuthTokenPath	string	JWKSAuthTokenPath is the path to file containing bearer token for JWKS/OIDC requests
jwksUrl	string	JWKSURL is the URL to fetch the JWKS from
protectedResourceAllowPrivateIP	boolean	ProtectedResourceAllowPrivateIP allows protected resource endpoint on private IP addresses. Note: at runtime, if either ProtectedResourceAllowPrivateIP or JWKSAllowPrivateIP is true, private IPs are allowed for all OIDC HTTP requests (JWKS, discovery, introspection). default false

↑ Back to spec

spec.inline.caBundleRef

CABundleRef references a ConfigMap containing the CA certificate bundle. When specified, ToolHive auto-mounts the ConfigMap and auto-computes ThvCABundlePath.

Field	Type	Description
configMapRef	object	ConfigMapRef references a ConfigMap containing the CA certificate bundle. If Key is not specified, it defaults to "ca.crt".

↑ Back to spec.inline

spec.inline.caBundleRef.configMapRef

ConfigMapRef references a ConfigMap containing the CA certificate bundle. If Key is not specified, it defaults to "ca.crt".

Field	Type	Description
keyrequired	string	The key to select.
name	string	Name of the referent. This field is effectively required, but due to backwards compatibility is allowed to be empty. Instances of this type with an empty value here are almost certainly wrong. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names default ""
optional	boolean	Specify whether the ConfigMap or its key must be defined

↑ Back to spec.inline.caBundleRef

spec.inline.clientSecretRef

ClientSecretRef is a reference to a Kubernetes Secret containing the client secret

Field	Type	Description
keyrequired	string	Key is the key within the secret
namerequired	string	Name is the name of the secret

↑ Back to spec.inline

spec.kubernetesServiceAccount

KubernetesServiceAccount configures OIDC for Kubernetes service account token validation. Only used when Type is "kubernetesServiceAccount".

Field	Type	Description
introspectionUrl	string	IntrospectionURL is the URL for token introspection endpoint. If empty, OIDC discovery will be used to automatically determine the introspection URL.
issuer	string	Issuer is the OIDC issuer URL. default "https://kubernetes.default.svc"
jwksUrl	string	JWKSURL is the URL to fetch the JWKS from. If empty, OIDC discovery will be used to automatically determine the JWKS URL.
namespace	string	Namespace is the namespace of the service account. If empty, uses the MCPServer's namespace.
serviceAccount	string	ServiceAccount is the name of the service account to validate tokens for. If empty, uses the pod's service account.
useClusterAuth	boolean	UseClusterAuth enables using the Kubernetes cluster's CA bundle and service account token. When true, uses /var/run/secrets/kubernetes.io/serviceaccount/ca.crt for TLS verification and /var/run/secrets/kubernetes.io/serviceaccount/token for bearer token authentication. Defaults to true if not specified.

↑ Back to spec

status

MCPOIDCConfigStatus defines the observed state of MCPOIDCConfig

Field	Type	Description
conditions	object[]	Conditions represent the latest available observations of the MCPOIDCConfig'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 MCPOIDCConfig. format int64
referencingWorkloads	object[]	ReferencingWorkloads is a list of workload resources that reference this MCPOIDCConfig. Each entry identifies the workload by kind and name.

status.conditions[]

Conditions represent the latest available observations of the MCPOIDCConfig'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

status.referencingWorkloads[]

ReferencingWorkloads is a list of workload resources that reference this MCPOIDCConfig. Each entry identifies the workload by kind and name.

Field	Type	Description
kindrequired	string	Kind is the type of workload resource enum: MCPServer | VirtualMCPServer | MCPRemoteProxy
namerequired	string	Name is the name of the workload resource minLength 1

↑ Back to status

Related resources

Referenced by:

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