Kubernetes CRD reference

Packages

• toolhive.stacklok.dev/v1alpha1

toolhive.stacklok.dev/v1alpha1

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

Resource Types

• MCPServer
• MCPServerList

AuthzConfigRef

AuthzConfigRef defines a reference to authorization configuration

Appears in:

• MCPServerSpec

Field	Description	Default	Validation
type string	Type is the type of authorization configuration	configMap	Enum: [configMap inline]
configMap ConfigMapAuthzRef	ConfigMap references a ConfigMap containing authorization configuration Only used when Type is "configMap"
inline InlineAuthzConfig	Inline contains direct authorization configuration Only used when Type is "inline"

ConfigMapAuthzRef

ConfigMapAuthzRef references a ConfigMap containing authorization configuration

Appears in:

• AuthzConfigRef

Field	Description	Default	Validation
name string	Name is the name of the ConfigMap		Required: {}
key string	Key is the key in the ConfigMap that contains the authorization configuration	authz.json

ConfigMapOIDCRef

ConfigMapOIDCRef references a ConfigMap containing OIDC configuration

Appears in:

• OIDCConfigRef

Field	Description	Default	Validation
name string	Name is the name of the ConfigMap		Required: {}
key string	Key is the key in the ConfigMap that contains the OIDC configuration	oidc.json

EnvVar

EnvVar represents an environment variable in a container

Appears in:

• MCPServerSpec
• ProxyDeploymentOverrides

Field	Description	Default	Validation
name string	Name of the environment variable		Required: {}
value string	Value of the environment variable		Required: {}

InlineAuthzConfig

InlineAuthzConfig contains direct authorization configuration

Appears in:

• AuthzConfigRef

Field	Description	Default	Validation
policies string array	Policies is a list of Cedar policy strings		MinItems: 1 Required: {}
entitiesJson string	EntitiesJSON is a JSON string representing Cedar entities	[]

InlineOIDCConfig

InlineOIDCConfig contains direct OIDC configuration

Appears in:

• OIDCConfigRef

Field	Description	Default	Validation
issuer string	Issuer is the OIDC issuer URL		Required: {}
audience string	Audience is the expected audience for the token
jwksUrl string	JWKSURL is the URL to fetch the JWKS from
clientId string	ClientID is deprecated and will be removed in a future release.
thvCABundlePath string	ThvCABundlePath 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 string	JWKSAuthTokenPath 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 boolean	JWKSAllowPrivateIP 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:

• OIDCConfigRef

Field	Description	Default	Validation
serviceAccount string	ServiceAccount is deprecated and will be removed in a future release.
namespace string	Namespace is the namespace of the service account If empty, uses the MCPServer's namespace
audience string	Audience is the expected audience for the token	toolhive
issuer string	Issuer is the OIDC issuer URL	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
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

MCPServer

MCPServer is the Schema for the mcpservers API

Appears in:

• MCPServerList

Field	Description	Default	Validation
apiVersion string	toolhive.stacklok.dev/v1alpha1
kind string	MCPServer
kind string	Kind 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 string	APIVersion 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 ObjectMeta	Refer to Kubernetes API documentation for fields of metadata.
spec MCPServerSpec
status MCPServerStatus

MCPServerList

MCPServerList contains a list of MCPServer

Field	Description	Default	Validation
apiVersion string	toolhive.stacklok.dev/v1alpha1
kind string	MCPServerList
kind string	Kind 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 string	APIVersion 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 ListMeta	Refer 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:

• MCPServerStatus

Field	Description
Pending	MCPServerPhasePending means the MCPServer is being created
Running	MCPServerPhaseRunning means the MCPServer is running
Failed	MCPServerPhaseFailed means the MCPServer failed to start
Terminating	MCPServerPhaseTerminating means the MCPServer is being deleted

MCPServerSpec

MCPServerSpec defines the desired state of MCPServer

Appears in:

• MCPServer

Field	Description	Default	Validation
image string	Image is the container image for the MCP server		Required: {}
transport string	Transport is the transport method for the MCP server (stdio, streamable-http or sse)	stdio	Enum: [stdio streamable-http sse]
port integer	Port is the port to expose the MCP server on	8080	Maximum: 65535 Minimum: 1
targetPort integer	TargetPort is the port that MCP server listens to		Maximum: 65535 Minimum: 1
args string array	Args are additional arguments to pass to the MCP server
env EnvVar array	Env are environment variables to set in the MCP server container
volumes Volume array	Volumes are volumes to mount in the MCP server container
resources ResourceRequirements	Resources defines the resource requirements for the MCP server container
secrets SecretRef array	Secrets are references to secrets to mount in the MCP server container
permissionProfile PermissionProfileRef	PermissionProfile defines the permission profile to use
podTemplateSpec PodTemplateSpec	PodTemplateSpec 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 ResourceOverrides	ResourceOverrides allows overriding annotations and labels for resources created by the operator
oidcConfig OIDCConfigRef	OIDCConfig defines OIDC authentication configuration for the MCP server
authzConfig AuthzConfigRef	AuthzConfig defines authorization policy configuration for the MCP server

MCPServerStatus

MCPServerStatus defines the observed state of MCPServer

Appears in:

• MCPServer

Field	Description	Default	Validation
conditions Condition array	Conditions represent the latest available observations of the MCPServer's state
url string	URL is the URL where the MCP server can be accessed
phase MCPServerPhase	Phase is the current phase of the MCPServer		Enum: [Pending Running Failed Terminating]
message string	Message provides additional information about the current phase

NetworkPermissions

NetworkPermissions defines the network permissions for an MCP server

Appears in:

• PermissionProfileSpec

Field	Description	Default	Validation
outbound OutboundNetworkPermissions	Outbound defines the outbound network permissions

OIDCConfigRef

OIDCConfigRef defines a reference to OIDC configuration

Appears in:

• MCPServerSpec

Field	Description	Default	Validation
type string	Type is the type of OIDC configuration	kubernetes	Enum: [kubernetes configMap inline]
kubernetes KubernetesOIDCConfig	Kubernetes configures OIDC for Kubernetes service account token validation Only used when Type is "kubernetes"
configMap ConfigMapOIDCRef	ConfigMap references a ConfigMap containing OIDC configuration Only used when Type is "configmap"
inline InlineOIDCConfig	Inline contains direct OIDC configuration Only used when Type is "inline"

OutboundNetworkPermissions

OutboundNetworkPermissions defines the outbound network permissions

Appears in:

• NetworkPermissions

Field	Description	Default	Validation
insecureAllowAll boolean	InsecureAllowAll allows all outbound network connections (not recommended)	false
allowTransport string array	AllowTransport is a list of transport protocols to allow (e.g., "tcp", "udp")
allowHost string array	AllowHost is a list of hosts to allow connections to
allowPort integer array	AllowPort is a list of ports to allow connections to

PermissionProfileRef

PermissionProfileRef defines a reference to a permission profile

Appears in:

• MCPServerSpec

Field	Description	Default	Validation
type string	Type is the type of permission profile reference	builtin	Enum: [builtin configmap]
name string	Name 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 string	Key is the key in the ConfigMap that contains the permission profile Only used when Type is "configmap"

ProxyDeploymentOverrides

ProxyDeploymentOverrides defines overrides specific to the proxy deployment

Appears in:

• ResourceOverrides

Field	Description	Default	Validation
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
env EnvVar array	Env are environment variables to set in the proxy container (thv run process) These affect the toolhive proxy itself, not the MCP server it manages

ResourceList

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

Appears in:

• ResourceRequirements

Field	Description	Default	Validation
cpu string	CPU is the CPU limit in cores (e.g., "500m" for 0.5 cores)
memory string	Memory is the memory limit in bytes (e.g., "64Mi" for 64 megabytes)

ResourceMetadataOverrides

ResourceMetadataOverrides defines metadata overrides for a resource

Appears in:

• ProxyDeploymentOverrides
• ResourceOverrides

Field	Description	Default	Validation
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:

• MCPServerSpec

Field	Description	Default	Validation
proxyDeployment ProxyDeploymentOverrides	ProxyDeployment defines overrides for the Proxy Deployment resource (toolhive proxy)
proxyService ResourceMetadataOverrides	ProxyService defines overrides for the Proxy Service resource (points to the proxy deployment)

ResourceRequirements

ResourceRequirements describes the compute resource requirements

Appears in:

• MCPServerSpec

Field	Description	Default	Validation
limits ResourceList	Limits describes the maximum amount of compute resources allowed
requests ResourceList	Requests describes the minimum amount of compute resources required

SecretRef

SecretRef is a reference to a secret

Appears in:

• MCPServerSpec

Field	Description	Default	Validation
name string	Name is the name of the secret		Required: {}
key string	Key is the key in the secret itself		Required: {}
targetEnvName string	TargetEnvName is the environment variable to be used when setting up the secret in the MCP server If left unspecified, it defaults to the key

Volume

Volume represents a volume to mount in a container

Appears in:

• MCPServerSpec

Field	Description	Default	Validation
name string	Name is the name of the volume		Required: {}
hostPath string	HostPath is the path on the host to mount		Required: {}
mountPath string	MountPath is the path in the container to mount to		Required: {}
readOnly boolean	ReadOnly specifies whether the volume should be mounted read-only	false