Skip to main content

Kubernetes CRD reference

Packages

toolhive.stacklok.dev/v1alpha1

Package v1alpha1 contains API Schema definitions for the toolhive v1alpha1 API group

Resource Types

AuditConfig

AuditConfig defines audit logging configuration for the MCP server

Appears in:

FieldDescriptionDefaultValidation
enabled booleanEnabled controls whether audit logging is enabled
When true, enables audit logging with default configuration
false

AuthzConfigRef

AuthzConfigRef defines a reference to authorization configuration

Appears in:

FieldDescriptionDefaultValidation
type stringType is the type of authorization configurationconfigMapEnum: [configMap inline]
configMap ConfigMapAuthzRefConfigMap references a ConfigMap containing authorization configuration
Only used when Type is "configMap"
inline InlineAuthzConfigInline contains direct authorization configuration
Only used when Type is "inline"

ConfigMapAuthzRef

ConfigMapAuthzRef references a ConfigMap containing authorization configuration

Appears in:

FieldDescriptionDefaultValidation
name stringName is the name of the ConfigMapRequired: {}
key stringKey is the key in the ConfigMap that contains the authorization configurationauthz.json

ConfigMapOIDCRef

ConfigMapOIDCRef references a ConfigMap containing OIDC configuration

Appears in:

FieldDescriptionDefaultValidation
name stringName is the name of the ConfigMapRequired: {}
key stringKey is the key in the ConfigMap that contains the OIDC configurationoidc.json

ConfigMapSource

ConfigMapSource defines ConfigMap source configuration

Appears in:

FieldDescriptionDefaultValidation
name stringName is the name of the ConfigMapMinLength: 1
Required: {}
key stringKey is the key in the ConfigMap that contains the registry dataregistry.jsonMinLength: 1

EnvVar

EnvVar represents an environment variable in a container

Appears in:

FieldDescriptionDefaultValidation
name stringName of the environment variableRequired: {}
value stringValue of the environment variableRequired: {}

InlineAuthzConfig

InlineAuthzConfig contains direct authorization configuration

Appears in:

FieldDescriptionDefaultValidation
policies string arrayPolicies is a list of Cedar policy stringsMinItems: 1
Required: {}
entitiesJson stringEntitiesJSON is a JSON string representing Cedar entities[]

InlineOIDCConfig

InlineOIDCConfig contains direct OIDC configuration

Appears in:

FieldDescriptionDefaultValidation
issuer stringIssuer is the OIDC issuer URLRequired: {}
audience stringAudience is the expected audience for the token
jwksUrl stringJWKSURL is the URL to fetch the JWKS from
introspectionUrl stringIntrospectionURL is the URL for token introspection endpoint
clientId stringClientID is the OIDC client ID
clientSecret stringClientSecret is the client secret for introspection (optional)
thvCABundlePath stringThvCABundlePath is the path to CA certificate bundle file for HTTPS requests
The file must be mounted into the pod (e.g., via ConfigMap or Secret volume)
jwksAuthTokenPath stringJWKSAuthTokenPath is the path to file containing bearer token for JWKS/OIDC requests
The file must be mounted into the pod (e.g., via Secret volume)
jwksAllowPrivateIP booleanJWKSAllowPrivateIP allows JWKS/OIDC endpoints on private IP addresses
Use with caution - only enable for trusted internal IDPs
false

KubernetesOIDCConfig

KubernetesOIDCConfig configures OIDC for Kubernetes service account token validation

Appears in:

FieldDescriptionDefaultValidation
serviceAccount stringServiceAccount is the name of the service account to validate tokens for
If empty, uses the pod's service account
namespace stringNamespace is the namespace of the service account
If empty, uses the MCPServer's namespace
audience stringAudience is the expected audience for the tokentoolhive
issuer stringIssuer is the OIDC issuer URLhttps://kubernetes.default.svc
jwksUrl stringJWKSURL is the URL to fetch the JWKS from
If empty, OIDC discovery will be used to automatically determine the JWKS URL
introspectionUrl stringIntrospectionURL is the URL for token introspection endpoint
If empty, OIDC discovery will be used to automatically determine the introspection URL
useClusterAuth booleanUseClusterAuth 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

MCPRegistry

MCPRegistry is the Schema for the mcpregistries API ⚠️ Experimental API (v1alpha1) — subject to change.

Appears in:

FieldDescriptionDefaultValidation
apiVersion stringtoolhive.stacklok.dev/v1alpha1
kind stringMCPRegistry
kind stringKind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
apiVersion stringAPIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
metadata ObjectMetaRefer to Kubernetes API documentation for fields of metadata.
spec MCPRegistrySpec
status MCPRegistryStatus

MCPRegistryList

MCPRegistryList contains a list of MCPRegistry

FieldDescriptionDefaultValidation
apiVersion stringtoolhive.stacklok.dev/v1alpha1
kind stringMCPRegistryList
kind stringKind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
apiVersion stringAPIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
metadata ListMetaRefer to Kubernetes API documentation for fields of metadata.
items MCPRegistry array

MCPRegistryPhase

Underlying type: string

MCPRegistryPhase represents the phase of the MCPRegistry

Validation:

  • Enum: [Pending Ready Failed Syncing Terminating]

Appears in:

FieldDescription
PendingMCPRegistryPhasePending means the MCPRegistry is being initialized
ReadyMCPRegistryPhaseReady means the MCPRegistry is ready and operational
FailedMCPRegistryPhaseFailed means the MCPRegistry has failed
SyncingMCPRegistryPhaseSyncing means the MCPRegistry is currently syncing data
TerminatingMCPRegistryPhaseTerminating means the MCPRegistry is being deleted

MCPRegistrySource

MCPRegistrySource defines the source configuration for registry data

Appears in:

FieldDescriptionDefaultValidation
type stringType is the type of source (configmap)configmapEnum: [configmap]
format stringFormat is the data format (toolhive, upstream)toolhiveEnum: [toolhive upstream]
configmap ConfigMapSourceConfigMap defines the ConfigMap source configuration
Only used when Type is "configmap"

MCPRegistrySpec

MCPRegistrySpec defines the desired state of MCPRegistry

Appears in:

FieldDescriptionDefaultValidation
displayName stringDisplayName is a human-readable name for the registry
source MCPRegistrySourceSource defines the configuration for the registry data sourceRequired: {}
syncPolicy SyncPolicySyncPolicy defines the automatic synchronization behavior for the registry.
If specified, enables automatic synchronization at the given interval.
Manual synchronization is always supported via annotation-based triggers
regardless of this setting.
filter RegistryFilterFilter defines include/exclude patterns for registry content

MCPRegistryStatus

MCPRegistryStatus defines the observed state of MCPRegistry

Appears in:

FieldDescriptionDefaultValidation
phase MCPRegistryPhasePhase represents the current phase of the MCPRegistryEnum: [Pending Ready Failed Syncing Terminating]
message stringMessage provides additional information about the current phase
lastSyncTime TimeLastSyncTime is the timestamp of the last successful sync
lastSyncHash stringLastSyncHash is the hash of the last successfully synced data
Used to detect changes in source data
serverCount integerServerCount is the total number of servers in the registryMinimum: 0
deployedServerCount integerDeployedServerCount is the number of deployed servers with matching labelsMinimum: 0
syncAttempts integerSyncAttempts is the number of sync attempts since last successMinimum: 0
apiEndpoint stringAPIEndpoint is the URL of the registry API service
storageRef StorageReferenceStorageRef is a reference to the internal storage location
conditions Condition arrayConditions represent the latest available observations of the MCPRegistry's state

MCPServer

MCPServer is the Schema for the mcpservers API

Appears in:

FieldDescriptionDefaultValidation
apiVersion stringtoolhive.stacklok.dev/v1alpha1
kind stringMCPServer
kind stringKind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
apiVersion stringAPIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
metadata ObjectMetaRefer to Kubernetes API documentation for fields of metadata.
spec MCPServerSpec
status MCPServerStatus

MCPServerList

MCPServerList contains a list of MCPServer

FieldDescriptionDefaultValidation
apiVersion stringtoolhive.stacklok.dev/v1alpha1
kind stringMCPServerList
kind stringKind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
apiVersion stringAPIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
metadata ListMetaRefer to Kubernetes API documentation for fields of metadata.
items MCPServer array

MCPServerPhase

Underlying type: string

MCPServerPhase is the phase of the MCPServer

Validation:

  • Enum: [Pending Running Failed Terminating]

Appears in:

FieldDescription
PendingMCPServerPhasePending means the MCPServer is being created
RunningMCPServerPhaseRunning means the MCPServer is running
FailedMCPServerPhaseFailed means the MCPServer failed to start
TerminatingMCPServerPhaseTerminating means the MCPServer is being deleted

MCPServerSpec

MCPServerSpec defines the desired state of MCPServer

Appears in:

FieldDescriptionDefaultValidation
image stringImage is the container image for the MCP serverRequired: {}
transport stringTransport is the transport method for the MCP server (stdio, streamable-http or sse)stdioEnum: [stdio streamable-http sse]
proxyMode stringProxyMode is the proxy mode for stdio transport (sse or streamable-http)
This setting is only used when Transport is "stdio"
sseEnum: [sse streamable-http]
port integerPort is the port to expose the MCP server on8080Maximum: 65535
Minimum: 1
targetPort integerTargetPort is the port that MCP server listens toMaximum: 65535
Minimum: 1
args string arrayArgs are additional arguments to pass to the MCP server
env EnvVar arrayEnv are environment variables to set in the MCP server container
volumes Volume arrayVolumes are volumes to mount in the MCP server container
resources ResourceRequirementsResources defines the resource requirements for the MCP server container
secrets SecretRef arraySecrets are references to secrets to mount in the MCP server container
serviceAccount stringServiceAccount is the name of an already existing service account to use by the MCP server.
If not specified, a ServiceAccount will be created automatically and used by the MCP server.
permissionProfile PermissionProfileRefPermissionProfile defines the permission profile to use
podTemplateSpec PodTemplateSpecPodTemplateSpec defines the pod template to use for the MCP server
This allows for customizing the pod configuration beyond what is provided by the other fields.
Note that to modify the specific container the MCP server runs in, you must specify
the mcp container name in the PodTemplateSpec.
resourceOverrides ResourceOverridesResourceOverrides allows overriding annotations and labels for resources created by the operator
oidcConfig OIDCConfigRefOIDCConfig defines OIDC authentication configuration for the MCP server
authzConfig AuthzConfigRefAuthzConfig defines authorization policy configuration for the MCP server
audit AuditConfigAudit defines audit logging configuration for the MCP server
tools string arrayToolsFilter is the filter on tools applied to the MCP server
Deprecated: Use ToolConfigRef instead
toolConfigRef ToolConfigRefToolConfigRef references a MCPToolConfig resource for tool filtering and renaming.
The referenced MCPToolConfig must exist in the same namespace as this MCPServer.
Cross-namespace references are not supported for security and isolation reasons.
If specified, this takes precedence over the inline ToolsFilter field.
telemetry TelemetryConfigTelemetry defines observability configuration for the MCP server

MCPServerStatus

MCPServerStatus defines the observed state of MCPServer

Appears in:

FieldDescriptionDefaultValidation
conditions Condition arrayConditions represent the latest available observations of the MCPServer's state
toolConfigHash stringToolConfigHash stores the hash of the referenced ToolConfig for change detection
url stringURL is the URL where the MCP server can be accessed
phase MCPServerPhasePhase is the current phase of the MCPServerEnum: [Pending Running Failed Terminating]
message stringMessage provides additional information about the current phase

MCPToolConfig

MCPToolConfig is the Schema for the mcptoolconfigs API. MCPToolConfig resources are namespace-scoped and can only be referenced by MCPServer resources within the same namespace. Cross-namespace references are not supported for security and isolation reasons.

Appears in:

FieldDescriptionDefaultValidation
apiVersion stringtoolhive.stacklok.dev/v1alpha1
kind stringMCPToolConfig
kind stringKind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
apiVersion stringAPIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
metadata ObjectMetaRefer to Kubernetes API documentation for fields of metadata.
spec MCPToolConfigSpec
status MCPToolConfigStatus

MCPToolConfigList

MCPToolConfigList contains a list of MCPToolConfig

FieldDescriptionDefaultValidation
apiVersion stringtoolhive.stacklok.dev/v1alpha1
kind stringMCPToolConfigList
kind stringKind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
apiVersion stringAPIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
metadata ListMetaRefer to Kubernetes API documentation for fields of metadata.
items MCPToolConfig array

MCPToolConfigSpec

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

Appears in:

FieldDescriptionDefaultValidation
toolsFilter string arrayToolsFilter is a list of tool names to filter (allow list).
Only tools in this list will be exposed by the MCP server.
If empty, all tools are exposed.
toolsOverride object (keys:string, values:ToolOverride)ToolsOverride is a map from actual tool names to their overridden configuration.
This allows renaming tools and/or changing their descriptions.

MCPToolConfigStatus

MCPToolConfigStatus defines the observed state of MCPToolConfig

Appears in:

FieldDescriptionDefaultValidation
observedGeneration integerObservedGeneration is the most recent generation observed for this MCPToolConfig.
It corresponds to the MCPToolConfig's generation, which is updated on mutation by the API Server.
configHash stringConfigHash is a hash of the current configuration for change detection
referencingServers string arrayReferencingServers is a list of MCPServer resources that reference this MCPToolConfig
This helps track which servers need to be reconciled when this config changes

NameFilter

NameFilter defines name-based filtering

Appears in:

FieldDescriptionDefaultValidation
include string arrayInclude is a list of glob patterns to include
exclude string arrayExclude is a list of glob patterns to exclude

NetworkPermissions

NetworkPermissions defines the network permissions for an MCP server

Appears in:

FieldDescriptionDefaultValidation
outbound OutboundNetworkPermissionsOutbound defines the outbound network permissions

OIDCConfigRef

OIDCConfigRef defines a reference to OIDC configuration

Appears in:

FieldDescriptionDefaultValidation
type stringType is the type of OIDC configurationkubernetesEnum: [kubernetes configMap inline]
resourceUrl stringResourceURL is the explicit resource URL for OAuth discovery endpoint (RFC 9728)
If not specified, defaults to the in-cluster Kubernetes service URL
kubernetes KubernetesOIDCConfigKubernetes configures OIDC for Kubernetes service account token validation
Only used when Type is "kubernetes"
configMap ConfigMapOIDCRefConfigMap references a ConfigMap containing OIDC configuration
Only used when Type is "configmap"
inline InlineOIDCConfigInline contains direct OIDC configuration
Only used when Type is "inline"

OpenTelemetryConfig

OpenTelemetryConfig defines pure OpenTelemetry configuration

Appears in:

FieldDescriptionDefaultValidation
enabled booleanEnabled controls whether OpenTelemetry is enabledfalse
endpoint stringEndpoint is the OTLP endpoint URL for tracing and metrics
serviceName stringServiceName is the service name for telemetry
If not specified, defaults to the MCPServer name
headers string arrayHeaders contains authentication headers for the OTLP endpoint
Specified as key=value pairs
insecure booleanInsecure indicates whether to use HTTP instead of HTTPS for the OTLP endpointfalse
metrics OpenTelemetryMetricsConfigMetrics defines OpenTelemetry metrics-specific configuration
tracing OpenTelemetryTracingConfigTracing defines OpenTelemetry tracing configuration

OpenTelemetryMetricsConfig

OpenTelemetryMetricsConfig defines OpenTelemetry metrics configuration

Appears in:

FieldDescriptionDefaultValidation
enabled booleanEnabled controls whether OTLP metrics are sentfalse

OpenTelemetryTracingConfig

OpenTelemetryTracingConfig defines OpenTelemetry tracing configuration

Appears in:

FieldDescriptionDefaultValidation
enabled booleanEnabled controls whether OTLP tracing is sentfalse
samplingRate stringSamplingRate is the trace sampling rate (0.0-1.0)0.05

OutboundNetworkPermissions

OutboundNetworkPermissions defines the outbound network permissions

Appears in:

FieldDescriptionDefaultValidation
insecureAllowAll booleanInsecureAllowAll allows all outbound network connections (not recommended)false
allowHost string arrayAllowHost is a list of hosts to allow connections to
allowPort integer arrayAllowPort is a list of ports to allow connections to

PermissionProfileRef

PermissionProfileRef defines a reference to a permission profile

Appears in:

FieldDescriptionDefaultValidation
type stringType is the type of permission profile referencebuiltinEnum: [builtin configmap]
name stringName is the name of the permission profile
If Type is "builtin", Name must be one of: "none", "network"
If Type is "configmap", Name is the name of the ConfigMap
Required: {}
key stringKey is the key in the ConfigMap that contains the permission profile
Only used when Type is "configmap"

PrometheusConfig

PrometheusConfig defines Prometheus-specific configuration

Appears in:

FieldDescriptionDefaultValidation
enabled booleanEnabled controls whether Prometheus metrics endpoint is exposedfalse

ProxyDeploymentOverrides

ProxyDeploymentOverrides defines overrides specific to the proxy deployment

Appears in:

FieldDescriptionDefaultValidation
annotations object (keys:string, values:string)Annotations to add or override on the resource
labels object (keys:string, values:string)Labels to add or override on the resource
podTemplateMetadataOverrides ResourceMetadataOverrides
env EnvVar arrayEnv are environment variables to set in the proxy container (thv run process)
These affect the toolhive proxy itself, not the MCP server it manages

RegistryFilter

RegistryFilter defines include/exclude patterns for registry content

Appears in:

FieldDescriptionDefaultValidation
names NameFilterNameFilters defines name-based filtering
tags TagFilterTags defines tag-based filtering

ResourceList

ResourceList is a set of (resource name, quantity) pairs

Appears in:

FieldDescriptionDefaultValidation
cpu stringCPU is the CPU limit in cores (e.g., "500m" for 0.5 cores)
memory stringMemory is the memory limit in bytes (e.g., "64Mi" for 64 megabytes)

ResourceMetadataOverrides

ResourceMetadataOverrides defines metadata overrides for a resource

Appears in:

FieldDescriptionDefaultValidation
annotations object (keys:string, values:string)Annotations to add or override on the resource
labels object (keys:string, values:string)Labels to add or override on the resource

ResourceOverrides

ResourceOverrides defines overrides for annotations and labels on created resources

Appears in:

FieldDescriptionDefaultValidation
proxyDeployment ProxyDeploymentOverridesProxyDeployment defines overrides for the Proxy Deployment resource (toolhive proxy)
proxyService ResourceMetadataOverridesProxyService defines overrides for the Proxy Service resource (points to the proxy deployment)

ResourceRequirements

ResourceRequirements describes the compute resource requirements

Appears in:

FieldDescriptionDefaultValidation
limits ResourceListLimits describes the maximum amount of compute resources allowed
requests ResourceListRequests describes the minimum amount of compute resources required

SecretRef

SecretRef is a reference to a secret

Appears in:

FieldDescriptionDefaultValidation
name stringName is the name of the secretRequired: {}
key stringKey is the key in the secret itselfRequired: {}
targetEnvName stringTargetEnvName is the environment variable to be used when setting up the secret in the MCP server
If left unspecified, it defaults to the key

StorageReference

StorageReference defines a reference to internal storage

Appears in:

FieldDescriptionDefaultValidation
type stringType is the storage type (configmap)Enum: [configmap]
configMapRef LocalObjectReferenceConfigMapRef is a reference to a ConfigMap storage
Only used when Type is "configmap"

SyncPolicy

SyncPolicy defines automatic synchronization behavior. When specified, enables automatic synchronization at the given interval. Manual synchronization via annotation-based triggers is always available regardless of this policy setting.

Appears in:

FieldDescriptionDefaultValidation
interval stringInterval is the sync interval for automatic synchronization (Go duration format)
Examples: "1h", "30m", "24h"
Pattern: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
Required: {}

TagFilter

TagFilter defines tag-based filtering

Appears in:

FieldDescriptionDefaultValidation
include string arrayInclude is a list of tags to include
exclude string arrayExclude is a list of tags to exclude

TelemetryConfig

TelemetryConfig defines observability configuration for the MCP server

Appears in:

FieldDescriptionDefaultValidation
openTelemetry OpenTelemetryConfigOpenTelemetry defines OpenTelemetry configuration
prometheus PrometheusConfigPrometheus defines Prometheus-specific configuration

ToolConfigRef

ToolConfigRef defines a reference to a MCPToolConfig resource. The referenced MCPToolConfig must be in the same namespace as the MCPServer.

Appears in:

FieldDescriptionDefaultValidation
name stringName is the name of the MCPToolConfig resource in the same namespaceRequired: {}

ToolOverride

ToolOverride represents a tool override configuration. Both Name and Description can be overridden independently, but they can't be both empty.

Appears in:

FieldDescriptionDefaultValidation
name stringName is the redefined name of the tool
description stringDescription is the redefined description of the tool

Volume

Volume represents a volume to mount in a container

Appears in:

FieldDescriptionDefaultValidation
name stringName is the name of the volumeRequired: {}
hostPath stringHostPath is the path on the host to mountRequired: {}
mountPath stringMountPath is the path in the container to mount toRequired: {}
readOnly booleanReadOnly specifies whether the volume should be mounted read-onlyfalse