toolhive-crd-api.md

Packages

• toolhive.stacklok.dev/audit
• toolhive.stacklok.dev/authtypes
• toolhive.stacklok.dev/config
• toolhive.stacklok.dev/telemetry
• toolhive.stacklok.dev/v1alpha1

toolhive.stacklok.dev/audit

pkg.audit.Config

Config represents the audit logging configuration.

Appears in:

• vmcp.config.Config

Field	Description	Default	Validation
enabled boolean	Enabled controls whether audit logging is enabled. When true, enables audit logging with the configured options.	false
component string	Component is the component name to use in audit events.
eventTypes string array	EventTypes specifies which event types to audit. If empty, all events are audited.
excludeEventTypes string array	ExcludeEventTypes specifies which event types to exclude from auditing. This takes precedence over EventTypes.
includeRequestData boolean	IncludeRequestData determines whether to include request data in audit logs.	false
includeResponseData boolean	IncludeResponseData determines whether to include response data in audit logs.	false
maxDataSize integer	MaxDataSize limits the size of request/response data included in audit logs (in bytes).	1024
logFile string	LogFile specifies the file path for audit logs. If empty, logs to stdout.

toolhive.stacklok.dev/authtypes

auth.types.BackendAuthStrategy

BackendAuthStrategy defines how to authenticate to a specific backend.

This struct provides type-safe configuration for different authentication strategies using HeaderInjection or TokenExchange fields based on the Type field.

Appears in:

• vmcp.config.OutgoingAuthConfig

Field	Description	Default	Validation
type string	Type is the auth strategy: "unauthenticated", "header_injection", "token_exchange"
headerInjection auth.types.HeaderInjectionConfig	HeaderInjection contains configuration for header injection auth strategy. Used when Type = "header_injection".
tokenExchange auth.types.TokenExchangeConfig	TokenExchange contains configuration for token exchange auth strategy. Used when Type = "token_exchange".

auth.types.HeaderInjectionConfig

HeaderInjectionConfig configures the header injection auth strategy. This strategy injects a static or environment-sourced header value into requests.

Appears in:

• auth.types.BackendAuthStrategy

Field	Description	Default	Validation
headerName string	HeaderName is the name of the header to inject (e.g., "Authorization").
headerValue string	HeaderValue is the static header value to inject. Either HeaderValue or HeaderValueEnv should be set, not both.
headerValueEnv string	HeaderValueEnv is the environment variable name containing the header value. The value will be resolved at runtime from this environment variable. Either HeaderValue or HeaderValueEnv should be set, not both.

auth.types.TokenExchangeConfig

TokenExchangeConfig configures the OAuth 2.0 token exchange auth strategy. This strategy exchanges incoming tokens for backend-specific tokens using RFC 8693.

Appears in:

• auth.types.BackendAuthStrategy

Field	Description	Default	Validation
tokenUrl string	TokenURL is the OAuth token endpoint URL for token exchange.
clientId string	ClientID is the OAuth client ID for the token exchange request.
clientSecret string	ClientSecret is the OAuth client secret (use ClientSecretEnv for security).
clientSecretEnv string	ClientSecretEnv is the environment variable name containing the client secret. The value will be resolved at runtime from this environment variable.
audience string	Audience is the target audience for the exchanged token.
scopes string array	Scopes are the requested scopes for the exchanged token.
subjectTokenType string	SubjectTokenType is the token type of the incoming subject token. Defaults to "urn:ietf:params:oauth:token-type:access_token" if not specified.

toolhive.stacklok.dev/config

vmcp.config.AggregationConfig

AggregationConfig defines tool aggregation and conflict resolution strategies.

Appears in:

• vmcp.config.Config

Field	Description	Default	Validation
conflictResolution pkg.vmcp.ConflictResolutionStrategy	ConflictResolution defines the strategy for resolving tool name conflicts. - prefix: Automatically prefix tool names with workload identifier - priority: First workload in priority order wins - manual: Explicitly define overrides for all conflicts	prefix	Enum: [prefix priority manual]
conflictResolutionConfig vmcp.config.ConflictResolutionConfig	ConflictResolutionConfig provides configuration for the chosen strategy.
tools vmcp.config.WorkloadToolConfig array	Tools defines per-workload tool filtering and overrides.
excludeAllTools boolean	ExcludeAllTools excludes all tools from aggregation when true.

vmcp.config.AuthzConfig

AuthzConfig configures authorization.

Appears in:

• vmcp.config.IncomingAuthConfig

Field	Description	Default	Validation
type string	Type is the authz type: "cedar", "none"
policies string array	Policies contains Cedar policy definitions (when Type = "cedar").

vmcp.config.CircuitBreakerConfig

CircuitBreakerConfig configures circuit breaker behavior.

Appears in:

• vmcp.config.FailureHandlingConfig

Field	Description	Default	Validation
enabled boolean	Enabled controls whether circuit breaker is enabled.	false
failureThreshold integer	FailureThreshold is the number of failures before opening the circuit.	5
timeout vmcp.config.Duration	Timeout is the duration to wait before attempting to close the circuit.	60s	Pattern: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$ Type: string

vmcp.config.CompositeToolConfig

CompositeToolConfig defines a composite tool workflow. This matches the YAML structure from the proposal (lines 173-255).

Appears in:

• vmcp.config.Config
• api.v1alpha1.VirtualMCPCompositeToolDefinitionSpec

Field	Description	Default	Validation
name string	Name is the workflow name (unique identifier).
description string	Description describes what the workflow does.
parameters pkg.json.Map	Parameters defines input parameter schema in JSON Schema format. Should be a JSON Schema object with "type": "object" and "properties". Example: { "type": "object", "properties": { "param1": {"type": "string", "default": "value"}, "param2": {"type": "integer"} }, "required": ["param2"] } We use json.Map rather than a typed struct because JSON Schema is highly flexible with many optional fields (default, enum, minimum, maximum, pattern, items, additionalProperties, oneOf, anyOf, allOf, etc.). Using json.Map allows full JSON Schema compatibility without needing to define every possible field, and matches how the MCP SDK handles inputSchema.
timeout vmcp.config.Duration	Timeout is the maximum workflow execution time.		Pattern: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$ Type: string
steps vmcp.config.WorkflowStepConfig array	Steps are the workflow steps to execute.
output vmcp.config.OutputConfig	Output defines the structured output schema for this workflow. If not specified, the workflow returns the last step's output (backward compatible).

vmcp.config.CompositeToolRef

CompositeToolRef defines a reference to a VirtualMCPCompositeToolDefinition resource. The referenced resource must be in the same namespace as the VirtualMCPServer.

Appears in:

• vmcp.config.Config

Field	Description	Default	Validation
name string	Name is the name of the VirtualMCPCompositeToolDefinition resource in the same namespace.		Required: {}

vmcp.config.Config

Config is the unified configuration model for Virtual MCP Server. This is platform-agnostic and used by both CLI and Kubernetes deployments.

Platform-specific adapters (CLI YAML loader, Kubernetes CRD converter) transform their native formats into this model.

Validation:

• Type: object

Appears in:

• api.v1alpha1.VirtualMCPServerSpec

Field	Description	Default	Validation
name string	Name is the virtual MCP server name.
groupRef string	Group references an existing MCPGroup that defines backend workloads. In Kubernetes, the referenced MCPGroup must exist in the same namespace.		Required: {}
incomingAuth vmcp.config.IncomingAuthConfig	IncomingAuth configures how clients authenticate to the virtual MCP server. When using the Kubernetes operator, this is populated by the converter from VirtualMCPServerSpec.IncomingAuth and any values set here will be superseded.
outgoingAuth vmcp.config.OutgoingAuthConfig	OutgoingAuth configures how the virtual MCP server authenticates to backends. When using the Kubernetes operator, this is populated by the converter from VirtualMCPServerSpec.OutgoingAuth and any values set here will be superseded.
aggregation vmcp.config.AggregationConfig	Aggregation defines tool aggregation and conflict resolution strategies. Supports ToolConfigRef for Kubernetes-native MCPToolConfig resource references.
compositeTools vmcp.config.CompositeToolConfig array	CompositeTools defines inline composite tool workflows. Full workflow definitions are embedded in the configuration. For Kubernetes, complex workflows can also reference VirtualMCPCompositeToolDefinition CRDs.
compositeToolRefs vmcp.config.CompositeToolRef array	CompositeToolRefs references VirtualMCPCompositeToolDefinition resources for complex, reusable workflows. Only applicable when running in Kubernetes. Referenced resources must be in the same namespace as the VirtualMCPServer.
operational vmcp.config.OperationalConfig	Operational configures operational settings.
metadata object (keys:string, values:string)	Refer to Kubernetes API documentation for fields of metadata.
telemetry pkg.telemetry.Config	Telemetry configures OpenTelemetry-based observability for the Virtual MCP server including distributed tracing, OTLP metrics export, and Prometheus metrics endpoint.
audit pkg.audit.Config	Audit configures audit logging for the Virtual MCP server. When present, audit logs include MCP protocol operations. See audit.Config for available configuration options.

vmcp.config.ConflictResolutionConfig

ConflictResolutionConfig provides configuration for conflict resolution strategies.

Appears in:

• vmcp.config.AggregationConfig

Field	Description	Default	Validation
prefixFormat string	PrefixFormat defines the prefix format for the "prefix" strategy. Supports placeholders: {workload}, {workload}_, {workload}.	{workload}_
priorityOrder string array	PriorityOrder defines the workload priority order for the "priority" strategy.

vmcp.config.ElicitationResponseConfig

ElicitationResponseConfig defines how to handle user responses to elicitation requests.

Appears in:

• vmcp.config.WorkflowStepConfig

Field	Description	Default	Validation
action string	Action defines the action to take when the user declines or cancels - skip_remaining: Skip remaining steps in the workflow - abort: Abort the entire workflow execution - continue: Continue to the next step	abort	Enum: [skip_remaining abort continue]

vmcp.config.FailureHandlingConfig

FailureHandlingConfig configures failure handling behavior.

Appears in:

• vmcp.config.OperationalConfig

Field	Description	Default	Validation
healthCheckInterval vmcp.config.Duration	HealthCheckInterval is the interval between health checks.	30s	Pattern: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$ Type: string
unhealthyThreshold integer	UnhealthyThreshold is the number of consecutive failures before marking unhealthy.	3
partialFailureMode string	PartialFailureMode defines behavior when some backends are unavailable. - fail: Fail entire request if any backend is unavailable - best_effort: Continue with available backends	fail	Enum: [fail best_effort]
circuitBreaker vmcp.config.CircuitBreakerConfig	CircuitBreaker configures circuit breaker behavior.

vmcp.config.IncomingAuthConfig

IncomingAuthConfig configures client authentication to the virtual MCP server.

Note: When using the Kubernetes operator (VirtualMCPServer CRD), the VirtualMCPServerSpec.IncomingAuth field is the authoritative source for authentication configuration. The operator's converter will resolve the CRD's IncomingAuth (which supports Kubernetes-native references like SecretKeyRef, ConfigMapRef, etc.) and populate this IncomingAuthConfig with the resolved values. Any values set here directly will be superseded by the CRD configuration.

Appears in:

• vmcp.config.Config

Field	Description	Default	Validation
type string	Type is the auth type: "oidc", "local", "anonymous"
oidc vmcp.config.OIDCConfig	OIDC contains OIDC configuration (when Type = "oidc").
authz vmcp.config.AuthzConfig	Authz contains authorization configuration (optional).

vmcp.config.OIDCConfig

OIDCConfig configures OpenID Connect authentication.

Appears in:

• vmcp.config.IncomingAuthConfig

Field	Description	Default	Validation
issuer string	Issuer is the OIDC issuer URL.
clientId string	ClientID is the OAuth client ID.
clientSecretEnv string	ClientSecretEnv is the name of the environment variable containing the client secret. This is the secure way to reference secrets - the actual secret value is never stored in configuration files, only the environment variable name. The secret value will be resolved from this environment variable at runtime.
audience string	Audience is the required token audience.
resource string	Resource is the OAuth 2.0 resource indicator (RFC 8707). Used in WWW-Authenticate header and OAuth discovery metadata (RFC 9728). If not specified, defaults to Audience.
scopes string array	Scopes are the required OAuth scopes.
protectedResourceAllowPrivateIp boolean	ProtectedResourceAllowPrivateIP allows protected resource endpoint on private IP addresses Use with caution - only enable for trusted internal IDPs or testing
insecureAllowHttp boolean	InsecureAllowHTTP allows HTTP (non-HTTPS) OIDC issuers for development/testing WARNING: This is insecure and should NEVER be used in production

vmcp.config.OperationalConfig

OperationalConfig contains operational settings. OperationalConfig defines operational settings like timeouts and health checks.

Appears in:

• vmcp.config.Config

Field	Description	Default	Validation
logLevel string	LogLevel sets the logging level for the Virtual MCP server. The only valid value is "debug" to enable debug logging. When omitted or empty, the server uses info level logging.		Enum: [debug]
timeouts vmcp.config.TimeoutConfig	Timeouts configures timeout settings.
failureHandling vmcp.config.FailureHandlingConfig	FailureHandling configures failure handling behavior.

vmcp.config.OutgoingAuthConfig

OutgoingAuthConfig configures backend authentication.

Note: When using the Kubernetes operator (VirtualMCPServer CRD), the VirtualMCPServerSpec.OutgoingAuth field is the authoritative source for backend authentication configuration. The operator's converter will resolve the CRD's OutgoingAuth (which supports Kubernetes-native references like SecretKeyRef, ConfigMapRef, etc.) and populate this OutgoingAuthConfig with the resolved values. Any values set here directly will be superseded by the CRD configuration.

Appears in:

• vmcp.config.Config

Field	Description	Default	Validation
source string	Source defines how to discover backend auth: "inline", "discovered" - inline: Explicit configuration in OutgoingAuth - discovered: Auto-discover from backend MCPServer.externalAuthConfigRef (Kubernetes only)
default auth.types.BackendAuthStrategy	Default is the default auth strategy for backends without explicit config.
backends object (keys:string, values:auth.types.BackendAuthStrategy)	Backends contains per-backend auth configuration.

vmcp.config.OutputConfig

OutputConfig defines the structured output schema for a composite tool workflow. This follows the same pattern as the Parameters field, defining both the MCP output schema (type, description) and runtime value construction (value, default).

Appears in:

• vmcp.config.CompositeToolConfig
• api.v1alpha1.VirtualMCPCompositeToolDefinitionSpec

Field	Description	Default	Validation
properties object (keys:string, values:vmcp.config.OutputProperty)	Properties defines the output properties. Map key is the property name, value is the property definition.
required string array	Required lists property names that must be present in the output.

vmcp.config.OutputProperty

OutputProperty defines a single output property. For non-object types, Value is required. For object types, either Value or Properties must be specified (but not both).

Appears in:

• vmcp.config.OutputConfig
• vmcp.config.OutputProperty

Field	Description	Default	Validation
type string	Type is the JSON Schema type: "string", "integer", "number", "boolean", "object", "array"		Enum: [string integer number boolean object array] Required: {}
description string	Description is a human-readable description exposed to clients and models
value string	Value is a template string for constructing the runtime value. For object types, this can be a JSON string that will be deserialized. Supports template syntax: {{.steps.step_id.output.field}}, {{.params.param_name}}
properties object (keys:string, values:vmcp.config.OutputProperty)	Properties defines nested properties for object types. Each nested property has full metadata (type, description, value/properties).		Schemaless: {} Type: object
default pkg.json.Any	Default is the fallback value if template expansion fails. Type coercion is applied to match the declared Type.		Schemaless: {}

vmcp.config.StepErrorHandling

StepErrorHandling defines error handling behavior for workflow steps.

Appears in:

• vmcp.config.WorkflowStepConfig

Field	Description	Default	Validation
action string	Action defines the action to take on error	abort	Enum: [abort continue retry]
retryCount integer	RetryCount is the maximum number of retries Only used when Action is "retry"
retryDelay vmcp.config.Duration	RetryDelay is the delay between retry attempts Only used when Action is "retry"		Pattern: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$ Type: string

vmcp.config.TimeoutConfig

TimeoutConfig configures timeout settings.

Appears in:

• vmcp.config.OperationalConfig

Field	Description	Default	Validation
default vmcp.config.Duration	Default is the default timeout for backend requests.	30s	Pattern: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$ Type: string
perWorkload object (keys:string, values:vmcp.config.Duration)	PerWorkload defines per-workload timeout overrides.

vmcp.config.ToolConfigRef

ToolConfigRef references an MCPToolConfig resource for tool filtering and renaming. Only used when running in Kubernetes with the operator.

Appears in:

• vmcp.config.WorkloadToolConfig

Field	Description	Default	Validation
name string	Name is the name of the MCPToolConfig resource in the same namespace.		Required: {}

vmcp.config.ToolOverride

ToolOverride defines tool name and description overrides.

Appears in:

• vmcp.config.WorkloadToolConfig

Field	Description	Default	Validation
name string	Name is the new tool name (for renaming).
description string	Description is the new tool description.

vmcp.config.WorkflowStepConfig

WorkflowStepConfig defines a single workflow step. This matches the proposal's step configuration (lines 180-255).

Appears in:

• vmcp.config.CompositeToolConfig
• api.v1alpha1.VirtualMCPCompositeToolDefinitionSpec

Field	Description	Default	Validation
id string	ID is the unique identifier for this step.		Required: {}
type string	Type is the step type (tool, elicitation, etc.)	tool	Enum: [tool elicitation]
tool string	Tool is the tool to call (format: "workload.tool_name") Only used when Type is "tool"
arguments pkg.json.Map	Arguments is a map of argument values with template expansion support. Supports Go template syntax with .params and .steps for string values. Non-string values (integers, booleans, arrays, objects) are passed as-is. Note: the templating is only supported on the first level of the key-value pairs.		Type: object
condition string	Condition is a template expression that determines if the step should execute
dependsOn string array	DependsOn lists step IDs that must complete before this step
onError vmcp.config.StepErrorHandling	OnError defines error handling behavior
message string	Message is the elicitation message Only used when Type is "elicitation"
schema pkg.json.Map	Schema defines the expected response schema for elicitation		Type: object
timeout vmcp.config.Duration	Timeout is the maximum execution time for this step		Pattern: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$ Type: string
onDecline vmcp.config.ElicitationResponseConfig	OnDecline defines the action to take when the user explicitly declines the elicitation Only used when Type is "elicitation"
onCancel vmcp.config.ElicitationResponseConfig	OnCancel defines the action to take when the user cancels/dismisses the elicitation Only used when Type is "elicitation"
defaultResults pkg.json.Map	DefaultResults provides fallback output values when this step is skipped (due to condition evaluating to false) or fails (when onError.action is "continue"). Each key corresponds to an output field name referenced by downstream steps. Required if the step may be skipped AND downstream steps reference this step's output.		Schemaless: {}

vmcp.config.WorkloadToolConfig

WorkloadToolConfig defines tool filtering and overrides for a specific workload.

Appears in:

• vmcp.config.AggregationConfig

Field	Description	Default	Validation
workload string	Workload is the name of the backend MCPServer workload.		Required: {}
toolConfigRef vmcp.config.ToolConfigRef	ToolConfigRef references an MCPToolConfig resource for tool filtering and renaming. If specified, Filter and Overrides are ignored. Only used when running in Kubernetes with the operator.
filter string array	Filter is an inline list of tool names to allow (allow list). Only used if ToolConfigRef is not specified.
overrides object (keys:string, values:vmcp.config.ToolOverride)	Overrides is an inline map of tool overrides. Only used if ToolConfigRef is not specified.
excludeAll boolean	ExcludeAll excludes all tools from this workload when true.

toolhive.stacklok.dev/telemetry

pkg.telemetry.Config

Config holds the configuration for OpenTelemetry instrumentation.

Appears in:

• vmcp.config.Config

Field	Description	Default	Validation
endpoint string	Endpoint is the OTLP endpoint URL
serviceName string	ServiceName is the service name for telemetry. When omitted, defaults to the server name (e.g., VirtualMCPServer name).
serviceVersion string	ServiceVersion is the service version for telemetry. When omitted, defaults to the ToolHive version.
tracingEnabled boolean	TracingEnabled controls whether distributed tracing is enabled. When false, no tracer provider is created even if an endpoint is configured.	false
metricsEnabled boolean	MetricsEnabled controls whether OTLP metrics are enabled. When false, OTLP metrics are not sent even if an endpoint is configured. This is independent of EnablePrometheusMetricsPath.	false
samplingRate string	SamplingRate is the trace sampling rate (0.0-1.0) as a string. Only used when TracingEnabled is true. Example: "0.05" for 5% sampling.	0.05
headers object (keys:string, values:string)	Headers contains authentication headers for the OTLP endpoint.
insecure boolean	Insecure indicates whether to use HTTP instead of HTTPS for the OTLP endpoint.	false
enablePrometheusMetricsPath boolean	EnablePrometheusMetricsPath controls whether to expose Prometheus-style /metrics endpoint. The metrics are served on the main transport port at /metrics. This is separate from OTLP metrics which are sent to the Endpoint.	false
environmentVariables string array	EnvironmentVariables is a list of environment variable names that should be included in telemetry spans as attributes. Only variables in this list will be read from the host machine and included in spans for observability. Example: ["NODE_ENV", "DEPLOYMENT_ENV", "SERVICE_VERSION"]
customAttributes object (keys:string, values:string)	CustomAttributes contains custom resource attributes to be added to all telemetry signals. These are parsed from CLI flags (--otel-custom-attributes) or environment variables (OTEL_RESOURCE_ATTRIBUTES) as key=value pairs.

toolhive.stacklok.dev/v1alpha1

Resource Types

• MCPExternalAuthConfig
• MCPExternalAuthConfigList
• MCPGroup
• MCPGroupList
• MCPRegistry
• MCPRegistryList
• MCPRemoteProxy
• MCPRemoteProxyList
• MCPServer
• MCPServerList
• MCPToolConfig
• MCPToolConfigList
• VirtualMCPCompositeToolDefinition
• VirtualMCPCompositeToolDefinitionList
• VirtualMCPServer
• VirtualMCPServerList

api.v1alpha1.APIPhase

Underlying type: string

APIPhase represents the API service state

Validation:

• Enum: [NotStarted Deploying Ready Unhealthy Error]

Appears in:

• api.v1alpha1.APIStatus

Field	Description
NotStarted	APIPhaseNotStarted means API deployment has not been created
Deploying	APIPhaseDeploying means API is being deployed
Ready	APIPhaseReady means API is ready to serve requests
Unhealthy	APIPhaseUnhealthy means API is deployed but not healthy
Error	APIPhaseError means API deployment failed

api.v1alpha1.APISource

APISource defines API source configuration for ToolHive Registry APIs Phase 1: Supports ToolHive API endpoints (no pagination) Phase 2: Will add support for upstream MCP Registry API with pagination

Appears in:

• api.v1alpha1.MCPRegistryConfig

Field	Description	Default	Validation
endpoint string	Endpoint is the base API URL (without path) The controller will append the appropriate paths: Phase 1 (ToolHive API): - /v0/servers - List all servers (single response, no pagination) - /v0/servers/{name} - Get specific server (future) - /v0/info - Get registry metadata (future) Example: "http://my-registry-api.default.svc.cluster.local/api"		MinLength: 1 Pattern: ^https?://.* Required: {}

api.v1alpha1.APIStatus

APIStatus provides detailed information about the API service

Appears in:

• api.v1alpha1.MCPRegistryStatus

Field	Description	Default	Validation
phase api.v1alpha1.APIPhase	Phase represents the current API service phase		Enum: [NotStarted Deploying Ready Unhealthy Error]
message string	Message provides additional information about the API status
endpoint string	Endpoint is the URL where the API is accessible
readySince Time	ReadySince is the timestamp when the API became ready

api.v1alpha1.AuditConfig

AuditConfig defines audit logging configuration for the MCP server

Appears in:

• api.v1alpha1.MCPRemoteProxySpec
• api.v1alpha1.MCPServerSpec

Field	Description	Default	Validation
enabled boolean	Enabled controls whether audit logging is enabled When true, enables audit logging with default configuration	false

api.v1alpha1.AuthzConfigRef

AuthzConfigRef defines a reference to authorization configuration

Appears in:

• api.v1alpha1.IncomingAuthConfig
• api.v1alpha1.MCPRemoteProxySpec
• api.v1alpha1.MCPServerSpec

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

api.v1alpha1.BackendAuthConfig

BackendAuthConfig defines authentication configuration for a backend MCPServer

Appears in:

• api.v1alpha1.OutgoingAuthConfig

Field	Description	Default	Validation
type string	Type defines the authentication type		Enum: [discovered external_auth_config_ref] Required: {}
externalAuthConfigRef api.v1alpha1.ExternalAuthConfigRef	ExternalAuthConfigRef references an MCPExternalAuthConfig resource Only used when Type is "external_auth_config_ref"

api.v1alpha1.ConfigMapAuthzRef

ConfigMapAuthzRef references a ConfigMap containing authorization configuration

Appears in:

• api.v1alpha1.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

api.v1alpha1.ConfigMapOIDCRef

ConfigMapOIDCRef references a ConfigMap containing OIDC configuration

Appears in:

• api.v1alpha1.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

api.v1alpha1.DiscoveredBackend

DiscoveredBackend represents a discovered backend MCPServer in the MCPGroup

Appears in:

• api.v1alpha1.VirtualMCPServerStatus

Field	Description	Default	Validation
name string	Name is the name of the backend MCPServer
authConfigRef string	AuthConfigRef is the name of the discovered MCPExternalAuthConfig (if any)
authType string	AuthType is the type of authentication configured
status string	Status is the current status of the backend (ready, degraded, unavailable)
lastHealthCheck Time	LastHealthCheck is the timestamp of the last health check
url string	URL is the URL of the backend MCPServer

api.v1alpha1.EnvVar

EnvVar represents an environment variable in a container

Appears in:

• api.v1alpha1.MCPServerSpec
• api.v1alpha1.ProxyDeploymentOverrides

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

api.v1alpha1.ExternalAuthConfigRef

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

Appears in:

• api.v1alpha1.BackendAuthConfig
• api.v1alpha1.MCPRemoteProxySpec
• api.v1alpha1.MCPServerSpec

Field	Description	Default	Validation
name string	Name is the name of the MCPExternalAuthConfig resource		Required: {}

api.v1alpha1.ExternalAuthType

Underlying type: string

ExternalAuthType represents the type of external authentication

Appears in:

• api.v1alpha1.MCPExternalAuthConfigSpec

Field	Description
tokenExchange	ExternalAuthTypeTokenExchange is the type for RFC-8693 token exchange
headerInjection	ExternalAuthTypeHeaderInjection is the type for custom header injection
unauthenticated	ExternalAuthTypeUnauthenticated is the type for no authentication This should only be used for backends on trusted networks (e.g., localhost, VPC) or when authentication is handled by network-level security

api.v1alpha1.GitSource

GitSource defines Git repository source configuration

Appears in:

• api.v1alpha1.MCPRegistryConfig

Field	Description	Default	Validation
repository string	Repository is the Git repository URL (HTTP/HTTPS/SSH)		MinLength: 1 Pattern: ^(file:///|https?://|git@|ssh://|git://).* Required: {}
branch string	Branch is the Git branch to use (mutually exclusive with Tag and Commit)		MinLength: 1
tag string	Tag is the Git tag to use (mutually exclusive with Branch and Commit)		MinLength: 1
commit string	Commit is the Git commit SHA to use (mutually exclusive with Branch and Tag)		MinLength: 1
path string	Path is the path to the registry file within the repository	registry.json	Pattern: ^.*\.json$

api.v1alpha1.HeaderInjectionConfig

HeaderInjectionConfig holds configuration for custom HTTP header injection authentication. This allows injecting a secret-based header value into requests to backend MCP servers. For security reasons, only secret references are supported (no plaintext values).

Appears in:

• api.v1alpha1.MCPExternalAuthConfigSpec

Field	Description	Default	Validation
headerName string	HeaderName is the name of the HTTP header to inject		MinLength: 1 Required: {}
valueSecretRef api.v1alpha1.SecretKeyRef	ValueSecretRef references a Kubernetes Secret containing the header value		Required: {}

api.v1alpha1.IncomingAuthConfig

IncomingAuthConfig configures authentication for clients connecting to the Virtual MCP server

Appears in:

• api.v1alpha1.VirtualMCPServerSpec

Field	Description	Default	Validation
type string	Type defines the authentication type: anonymous or oidc When no authentication is required, explicitly set this to "anonymous"		Enum: [anonymous oidc] Required: {}
oidcConfig api.v1alpha1.OIDCConfigRef	OIDCConfig defines OIDC authentication configuration Reuses MCPServer OIDC patterns
authzConfig api.v1alpha1.AuthzConfigRef	AuthzConfig defines authorization policy configuration Reuses MCPServer authz patterns

api.v1alpha1.InlineAuthzConfig

InlineAuthzConfig contains direct authorization configuration

Appears in:

• api.v1alpha1.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	[]

api.v1alpha1.InlineOIDCConfig

InlineOIDCConfig contains direct OIDC configuration

Appears in:

• api.v1alpha1.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
introspectionUrl string	IntrospectionURL is the URL for token introspection endpoint
clientId string	ClientID is the OIDC client ID
clientSecret string	ClientSecret is the client secret for introspection (optional) Deprecated: Use ClientSecretRef instead for better security
clientSecretRef api.v1alpha1.SecretKeyRef	ClientSecretRef is a reference to a Kubernetes Secret containing the client secret If both ClientSecret and ClientSecretRef are provided, ClientSecretRef takes precedence
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
protectedResourceAllowPrivateIP boolean	ProtectedResourceAllowPrivateIP allows protected resource endpoint on private IP addresses Use with caution - only enable for trusted internal IDPs or testing	false
insecureAllowHTTP boolean	InsecureAllowHTTP allows HTTP (non-HTTPS) OIDC issuers for development/testing WARNING: This is insecure and should NEVER be used in production Only enable for local development, testing, or trusted internal networks	false
scopes string array	Scopes is the list of OAuth scopes to advertise in the well-known endpoint (RFC 9728) If empty, defaults to ["openid"]

api.v1alpha1.KubernetesOIDCConfig

KubernetesOIDCConfig configures OIDC for Kubernetes service account token validation

Appears in:

• api.v1alpha1.OIDCConfigRef

Field	Description	Default	Validation
serviceAccount string	ServiceAccount is the name of the service account to validate tokens for If empty, uses the pod's service account
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
introspectionUrl string	IntrospectionURL is the URL for token introspection endpoint If empty, OIDC discovery will be used to automatically determine the introspection 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

api.v1alpha1.MCPExternalAuthConfig

MCPExternalAuthConfig is the Schema for the mcpexternalauthconfigs API. MCPExternalAuthConfig 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:

• api.v1alpha1.MCPExternalAuthConfigList

Field	Description	Default	Validation
apiVersion string	toolhive.stacklok.dev/v1alpha1
kind string	MCPExternalAuthConfig
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 api.v1alpha1.MCPExternalAuthConfigSpec
status api.v1alpha1.MCPExternalAuthConfigStatus

api.v1alpha1.MCPExternalAuthConfigList

MCPExternalAuthConfigList contains a list of MCPExternalAuthConfig

Field	Description	Default	Validation
apiVersion string	toolhive.stacklok.dev/v1alpha1
kind string	MCPExternalAuthConfigList
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 api.v1alpha1.MCPExternalAuthConfig array

api.v1alpha1.MCPExternalAuthConfigSpec

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

Appears in:

• api.v1alpha1.MCPExternalAuthConfig

Field	Description	Default	Validation
type api.v1alpha1.ExternalAuthType	Type is the type of external authentication to configure		Enum: [tokenExchange headerInjection unauthenticated] Required: {}
tokenExchange api.v1alpha1.TokenExchangeConfig	TokenExchange configures RFC-8693 OAuth 2.0 Token Exchange Only used when Type is "tokenExchange"
headerInjection api.v1alpha1.HeaderInjectionConfig	HeaderInjection configures custom HTTP header injection Only used when Type is "headerInjection"

api.v1alpha1.MCPExternalAuthConfigStatus

MCPExternalAuthConfigStatus defines the observed state of MCPExternalAuthConfig

Appears in:

• api.v1alpha1.MCPExternalAuthConfig

Field	Description	Default	Validation
observedGeneration integer	ObservedGeneration is the most recent generation observed for this MCPExternalAuthConfig. It corresponds to the MCPExternalAuthConfig's generation, which is updated on mutation by the API Server.
configHash string	ConfigHash is a hash of the current configuration for change detection
referencingServers string array	ReferencingServers is a list of MCPServer resources that reference this MCPExternalAuthConfig This helps track which servers need to be reconciled when this config changes

api.v1alpha1.MCPGroup

MCPGroup is the Schema for the mcpgroups API

Appears in:

• api.v1alpha1.MCPGroupList

Field	Description	Default	Validation
apiVersion string	toolhive.stacklok.dev/v1alpha1
kind string	MCPGroup
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 api.v1alpha1.MCPGroupSpec
status api.v1alpha1.MCPGroupStatus

api.v1alpha1.MCPGroupList

MCPGroupList contains a list of MCPGroup

Field	Description	Default	Validation
apiVersion string	toolhive.stacklok.dev/v1alpha1
kind string	MCPGroupList
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 api.v1alpha1.MCPGroup array

api.v1alpha1.MCPGroupPhase

Underlying type: string

MCPGroupPhase represents the lifecycle phase of an MCPGroup

Validation:

• Enum: [Ready Pending Failed]

Appears in:

• api.v1alpha1.MCPGroupStatus

Field	Description
Ready	MCPGroupPhaseReady indicates the MCPGroup is ready
Pending	MCPGroupPhasePending indicates the MCPGroup is pending
Failed	MCPGroupPhaseFailed indicates the MCPGroup has failed

api.v1alpha1.MCPGroupSpec

MCPGroupSpec defines the desired state of MCPGroup

Appears in:

• api.v1alpha1.MCPGroup

Field	Description	Default	Validation
description string	Description provides human-readable context

api.v1alpha1.MCPGroupStatus

MCPGroupStatus defines observed state

Appears in:

• api.v1alpha1.MCPGroup

Field	Description	Default	Validation
phase api.v1alpha1.MCPGroupPhase	Phase indicates current state	Pending	Enum: [Ready Pending Failed]
servers string array	Servers lists MCPServer names in this group
serverCount integer	ServerCount is the number of MCPServers
remoteProxies string array	RemoteProxies lists MCPRemoteProxy names in this group
remoteProxyCount integer	RemoteProxyCount is the number of MCPRemoteProxies
conditions Condition array	Conditions represent observations

api.v1alpha1.MCPRegistry

MCPRegistry is the Schema for the mcpregistries API

Appears in:

• api.v1alpha1.MCPRegistryList

Field	Description	Default	Validation
apiVersion string	toolhive.stacklok.dev/v1alpha1
kind string	MCPRegistry
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 api.v1alpha1.MCPRegistrySpec
status api.v1alpha1.MCPRegistryStatus

api.v1alpha1.MCPRegistryAuthConfig

MCPRegistryAuthConfig defines authentication configuration for the registry API server.

Appears in:

• api.v1alpha1.MCPRegistrySpec

Field	Description	Default	Validation
mode api.v1alpha1.MCPRegistryAuthMode	Mode specifies the authentication mode (anonymous or oauth) Defaults to "anonymous" if not specified. Use "oauth" to enable OAuth/OIDC authentication.	anonymous	Enum: [anonymous oauth]
oauth api.v1alpha1.MCPRegistryOAuthConfig	OAuth defines OAuth/OIDC specific authentication settings Only used when Mode is "oauth"

api.v1alpha1.MCPRegistryAuthMode

Underlying type: string

MCPRegistryAuthMode represents the authentication mode for the registry API server

Appears in:

• api.v1alpha1.MCPRegistryAuthConfig

Field	Description
anonymous	MCPRegistryAuthModeAnonymous allows unauthenticated access
oauth	MCPRegistryAuthModeOAuth enables OAuth/OIDC authentication

api.v1alpha1.MCPRegistryConfig

MCPRegistryConfig defines the configuration for a registry data source

Appears in:

• api.v1alpha1.MCPRegistrySpec

Field	Description	Default	Validation
name string	Name is a unique identifier for this registry configuration within the MCPRegistry		MinLength: 1 Required: {}
format string	Format is the data format (toolhive, upstream)	toolhive	Enum: [toolhive upstream]
configMapRef ConfigMapKeySelector	ConfigMapRef defines the ConfigMap source configuration Mutually exclusive with Git, API, and PVCRef
git api.v1alpha1.GitSource	Git defines the Git repository source configuration Mutually exclusive with ConfigMapRef, API, and PVCRef
api api.v1alpha1.APISource	API defines the API source configuration Mutually exclusive with ConfigMapRef, Git, and PVCRef
pvcRef api.v1alpha1.PVCSource	PVCRef defines the PersistentVolumeClaim source configuration Mutually exclusive with ConfigMapRef, Git, and API
syncPolicy api.v1alpha1.SyncPolicy	SyncPolicy defines the automatic synchronization behavior for this registry. If specified, enables automatic synchronization at the given interval. Manual synchronization is always supported via annotation-based triggers regardless of this setting.
filter api.v1alpha1.RegistryFilter	Filter defines include/exclude patterns for registry content

api.v1alpha1.MCPRegistryDatabaseConfig

MCPRegistryDatabaseConfig defines PostgreSQL database configuration for the registry API server. Uses a two-user security model: separate users for operations and migrations.

Appears in:

• api.v1alpha1.MCPRegistrySpec

Field	Description	Default	Validation
host string	Host is the database server hostname	postgres
port integer	Port is the database server port	5432	Maximum: 65535 Minimum: 1
user string	User is the application user (limited privileges: SELECT, INSERT, UPDATE, DELETE) Credentials should be provided via pgpass file or environment variables	db_app
migrationUser string	MigrationUser is the migration user (elevated privileges: CREATE, ALTER, DROP) Used for running database schema migrations Credentials should be provided via pgpass file or environment variables	db_migrator
database string	Database is the database name	registry
sslMode string	SSLMode is the SSL mode for the connection Valid values: disable, allow, prefer, require, verify-ca, verify-full	prefer	Enum: [disable allow prefer require verify-ca verify-full]
maxOpenConns integer	MaxOpenConns is the maximum number of open connections to the database	10	Minimum: 1
maxIdleConns integer	MaxIdleConns is the maximum number of idle connections in the pool	2	Minimum: 0
connMaxLifetime string	ConnMaxLifetime is the maximum amount of time a connection may be reused (Go duration format) Examples: "30m", "1h", "24h"	30m	Pattern: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
dbAppUserPasswordSecretRef SecretKeySelector	DBAppUserPasswordSecretRef references a Kubernetes Secret containing the password for the application database user. The operator will use this password along with DBMigrationUserPasswordSecretRef to generate a pgpass file that is mounted to the registry API container.		Required: {}
dbMigrationUserPasswordSecretRef SecretKeySelector	DBMigrationUserPasswordSecretRef references a Kubernetes Secret containing the password for the migration database user. The operator will use this password along with DBAppUserPasswordSecretRef to generate a pgpass file that is mounted to the registry API container.		Required: {}

api.v1alpha1.MCPRegistryList

MCPRegistryList contains a list of MCPRegistry

Field	Description	Default	Validation
apiVersion string	toolhive.stacklok.dev/v1alpha1
kind string	MCPRegistryList
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 api.v1alpha1.MCPRegistry array

api.v1alpha1.MCPRegistryOAuthConfig

MCPRegistryOAuthConfig defines OAuth/OIDC specific authentication settings

Appears in:

• api.v1alpha1.MCPRegistryAuthConfig

Field	Description	Default	Validation
resourceUrl string	ResourceURL is the URL identifying this protected resource (RFC 9728) Used in the /.well-known/oauth-protected-resource endpoint
providers api.v1alpha1.MCPRegistryOAuthProviderConfig array	Providers defines the OAuth/OIDC providers for authentication Multiple providers can be configured (e.g., Kubernetes + external IDP)		MinItems: 1
scopesSupported string array	ScopesSupported defines the OAuth scopes supported by this resource (RFC 9728) Defaults to ["mcp-registry:read", "mcp-registry:write"] if not specified
realm string	Realm is the protection space identifier for WWW-Authenticate header (RFC 7235) Defaults to "mcp-registry" if not specified

api.v1alpha1.MCPRegistryOAuthProviderConfig

MCPRegistryOAuthProviderConfig defines configuration for an OAuth/OIDC provider

Appears in:

• api.v1alpha1.MCPRegistryOAuthConfig

Field	Description	Default	Validation
name string	Name is a unique identifier for this provider (e.g., "kubernetes", "keycloak")		MinLength: 1 Required: {}
issuerUrl string	IssuerURL is the OIDC issuer URL (e.g., https://accounts.google.com) The JWKS URL will be discovered automatically from .well-known/openid-configuration unless JwksUrl is explicitly specified		MinLength: 1 Pattern: ^https?://.* Required: {}
jwksUrl string	JwksUrl is the URL to fetch the JSON Web Key Set (JWKS) from If specified, OIDC discovery is skipped and this URL is used directly Example: https://kubernetes.default.svc/openid/v1/jwks		Pattern: ^https?://.*
audience string	Audience is the expected audience claim in the token (REQUIRED) Per RFC 6749 Section 4.1.3, tokens must be validated against expected audience For Kubernetes, this is typically the API server URL		MinLength: 1 Required: {}
clientId string	ClientID is the OAuth client ID for token introspection (optional)
clientSecretRef SecretKeySelector	ClientSecretRef is a reference to a Secret containing the client secret The secret should have a key "clientSecret" containing the secret value
caCertRef ConfigMapKeySelector	CACertRef is a reference to a ConfigMap containing the CA certificate bundle for verifying the provider's TLS certificate. Required for Kubernetes in-cluster authentication or self-signed certificates
caCertPath string	CaCertPath is the path to the CA certificate bundle for verifying the provider's TLS certificate. Required for Kubernetes in-cluster authentication or self-signed certificates
authTokenRef SecretKeySelector	AuthTokenRef is a reference to a Secret containing a bearer token for authenticating to OIDC/JWKS endpoints. Useful when the OIDC discovery or JWKS endpoint requires authentication. Example: ServiceAccount token for Kubernetes API server
authTokenFile string	AuthTokenFile is the path to a file containing a bearer token for authenticating to OIDC/JWKS endpoints. Useful when the OIDC discovery or JWKS endpoint requires authentication. Example: /var/run/secrets/kubernetes.io/serviceaccount/token
introspectionUrl string	IntrospectionURL is the OAuth 2.0 Token Introspection endpoint (RFC 7662) Used for validating opaque (non-JWT) tokens If not specified, only JWT tokens can be validated via JWKS		Pattern: ^https?://.*
allowPrivateIP boolean	AllowPrivateIP allows JWKS/OIDC endpoints on private IP addresses Required when the OAuth provider (e.g., Kubernetes API server) is running on a private network Example: Set to true when using https://kubernetes.default.svc as the issuer URL	false

api.v1alpha1.MCPRegistryPhase

Underlying type: string

MCPRegistryPhase represents the phase of the MCPRegistry

Validation:

• Enum: [Pending Ready Failed Syncing Terminating]

Appears in:

• api.v1alpha1.MCPRegistryStatus

Field	Description
Pending	MCPRegistryPhasePending means the MCPRegistry is being initialized
Ready	MCPRegistryPhaseReady means the MCPRegistry is ready and operational
Failed	MCPRegistryPhaseFailed means the MCPRegistry has failed
Syncing	MCPRegistryPhaseSyncing means the MCPRegistry is currently syncing data
Terminating	MCPRegistryPhaseTerminating means the MCPRegistry is being deleted

api.v1alpha1.MCPRegistrySpec

MCPRegistrySpec defines the desired state of MCPRegistry

Appears in:

• api.v1alpha1.MCPRegistry

Field	Description	Default	Validation
displayName string	DisplayName is a human-readable name for the registry
registries api.v1alpha1.MCPRegistryConfig array	Registries defines the configuration for the registry data sources		MinItems: 1 Required: {}
enforceServers boolean	EnforceServers indicates whether MCPServers in this namespace must have their images present in at least one registry in the namespace. When any registry in the namespace has this field set to true, enforcement is enabled for the entire namespace. MCPServers with images not found in any registry will be rejected. When false (default), MCPServers can be deployed regardless of registry presence.	false
podTemplateSpec RawExtension	PodTemplateSpec defines the pod template to use for the registry API server This allows for customizing the pod configuration beyond what is provided by the other fields. Note that to modify the specific container the registry API server runs in, you must specify the registry-api container name in the PodTemplateSpec. This field accepts a PodTemplateSpec object as JSON/YAML.		Type: object
databaseConfig api.v1alpha1.MCPRegistryDatabaseConfig	DatabaseConfig defines the PostgreSQL database configuration for the registry API server. If not specified, defaults will be used: - Host: "postgres" - Port: 5432 - User: "db_app" - MigrationUser: "db_migrator" - Database: "registry" - SSLMode: "prefer" - MaxOpenConns: 10 - MaxIdleConns: 2 - ConnMaxLifetime: "30m"
authConfig api.v1alpha1.MCPRegistryAuthConfig	AuthConfig defines the authentication configuration for the registry API server. If not specified, defaults to anonymous authentication.

api.v1alpha1.MCPRegistryStatus

MCPRegistryStatus defines the observed state of MCPRegistry

Appears in:

• api.v1alpha1.MCPRegistry

Field	Description	Default	Validation
phase api.v1alpha1.MCPRegistryPhase	Phase represents the current overall phase of the MCPRegistry Derived from sync and API status		Enum: [Pending Ready Failed Syncing Terminating]
message string	Message provides additional information about the current phase
syncStatus api.v1alpha1.SyncStatus	SyncStatus provides detailed information about data synchronization
apiStatus api.v1alpha1.APIStatus	APIStatus provides detailed information about the API service
lastAppliedFilterHash string	LastAppliedFilterHash is the hash of the last applied filter
storageRef api.v1alpha1.StorageReference	StorageRef is a reference to the internal storage location
lastManualSyncTrigger string	LastManualSyncTrigger tracks the last processed manual sync annotation value Used to detect new manual sync requests via toolhive.stacklok.dev/sync-trigger annotation
conditions Condition array	Conditions represent the latest available observations of the MCPRegistry's state

api.v1alpha1.MCPRemoteProxy

MCPRemoteProxy is the Schema for the mcpremoteproxies API It enables proxying remote MCP servers with authentication, authorization, audit logging, and tool filtering

Appears in:

• api.v1alpha1.MCPRemoteProxyList

Field	Description	Default	Validation
apiVersion string	toolhive.stacklok.dev/v1alpha1
kind string	MCPRemoteProxy
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 api.v1alpha1.MCPRemoteProxySpec
status api.v1alpha1.MCPRemoteProxyStatus

api.v1alpha1.MCPRemoteProxyList

MCPRemoteProxyList contains a list of MCPRemoteProxy

Field	Description	Default	Validation
apiVersion string	toolhive.stacklok.dev/v1alpha1
kind string	MCPRemoteProxyList
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 api.v1alpha1.MCPRemoteProxy array

api.v1alpha1.MCPRemoteProxyPhase

Underlying type: string

MCPRemoteProxyPhase is a label for the condition of a MCPRemoteProxy at the current time

Validation:

• Enum: [Pending Ready Failed Terminating]

Appears in:

• api.v1alpha1.MCPRemoteProxyStatus

Field	Description
Pending	MCPRemoteProxyPhasePending means the proxy is being created
Ready	MCPRemoteProxyPhaseReady means the proxy is ready and operational
Failed	MCPRemoteProxyPhaseFailed means the proxy failed to start or encountered an error
Terminating	MCPRemoteProxyPhaseTerminating means the proxy is being deleted

api.v1alpha1.MCPRemoteProxySpec

MCPRemoteProxySpec defines the desired state of MCPRemoteProxy

Appears in:

• api.v1alpha1.MCPRemoteProxy

Field	Description	Default	Validation
remoteURL string	RemoteURL is the URL of the remote MCP server to proxy		Pattern: ^https?:// Required: {}
port integer	Port is the port to expose the MCP proxy on	8080	Maximum: 65535 Minimum: 1
transport string	Transport is the transport method for the remote proxy (sse or streamable-http)	streamable-http	Enum: [sse streamable-http]
oidcConfig api.v1alpha1.OIDCConfigRef	OIDCConfig defines OIDC authentication configuration for the proxy This validates incoming tokens from clients. Required for proxy mode.		Required: {}
externalAuthConfigRef api.v1alpha1.ExternalAuthConfigRef	ExternalAuthConfigRef references a MCPExternalAuthConfig resource for token exchange. When specified, the proxy will exchange validated incoming tokens for remote service tokens. The referenced MCPExternalAuthConfig must exist in the same namespace as this MCPRemoteProxy.
authzConfig api.v1alpha1.AuthzConfigRef	AuthzConfig defines authorization policy configuration for the proxy
audit api.v1alpha1.AuditConfig	Audit defines audit logging configuration for the proxy
toolConfigRef api.v1alpha1.ToolConfigRef	ToolConfigRef references a MCPToolConfig resource for tool filtering and renaming. The referenced MCPToolConfig must exist in the same namespace as this MCPRemoteProxy. Cross-namespace references are not supported for security and isolation reasons. If specified, this allows filtering and overriding tools from the remote MCP server.
telemetry api.v1alpha1.TelemetryConfig	Telemetry defines observability configuration for the proxy
resources api.v1alpha1.ResourceRequirements	Resources defines the resource requirements for the proxy container
trustProxyHeaders boolean	TrustProxyHeaders indicates whether to trust X-Forwarded-* headers from reverse proxies When enabled, the proxy will use X-Forwarded-Proto, X-Forwarded-Host, X-Forwarded-Port, and X-Forwarded-Prefix headers to construct endpoint URLs	false
endpointPrefix string	EndpointPrefix is the path prefix to prepend to SSE endpoint URLs. This is used to handle path-based ingress routing scenarios where the ingress strips a path prefix before forwarding to the backend.
resourceOverrides api.v1alpha1.ResourceOverrides	ResourceOverrides allows overriding annotations and labels for resources created by the operator
groupRef string	GroupRef is the name of the MCPGroup this proxy belongs to Must reference an existing MCPGroup in the same namespace

api.v1alpha1.MCPRemoteProxyStatus

MCPRemoteProxyStatus defines the observed state of MCPRemoteProxy

Appears in:

• api.v1alpha1.MCPRemoteProxy

Field	Description	Default	Validation
phase api.v1alpha1.MCPRemoteProxyPhase	Phase is the current phase of the MCPRemoteProxy		Enum: [Pending Ready Failed Terminating]
url string	URL is the internal cluster URL where the proxy can be accessed
externalURL string	ExternalURL is the external URL where the proxy can be accessed (if exposed externally)
observedGeneration integer	ObservedGeneration reflects the generation of the most recently observed MCPRemoteProxy
conditions Condition array	Conditions represent the latest available observations of the MCPRemoteProxy's state
toolConfigHash string	ToolConfigHash stores the hash of the referenced ToolConfig for change detection
externalAuthConfigHash string	ExternalAuthConfigHash is the hash of the referenced MCPExternalAuthConfig spec
message string	Message provides additional information about the current phase

api.v1alpha1.MCPServer

MCPServer is the Schema for the mcpservers API

Appears in:

• api.v1alpha1.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 api.v1alpha1.MCPServerSpec
status api.v1alpha1.MCPServerStatus

api.v1alpha1.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 api.v1alpha1.MCPServer array

api.v1alpha1.MCPServerPhase

Underlying type: string

MCPServerPhase is the phase of the MCPServer

Validation:

• Enum: [Pending Running Failed Terminating]

Appears in:

• api.v1alpha1.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

api.v1alpha1.MCPServerSpec

MCPServerSpec defines the desired state of MCPServer

Appears in:

• api.v1alpha1.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]
proxyMode string	ProxyMode is the proxy mode for stdio transport (sse or streamable-http) This setting is only used when Transport is "stdio"	streamable-http	Enum: [sse streamable-http]
port integer	Port is the port to expose the MCP server on Deprecated: Use ProxyPort instead	8080	Maximum: 65535 Minimum: 1
targetPort integer	TargetPort is the port that MCP server listens to Deprecated: Use McpPort instead		Maximum: 65535 Minimum: 1
proxyPort integer	ProxyPort is the port to expose the proxy runner on	8080	Maximum: 65535 Minimum: 1
mcpPort integer	McpPort 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 api.v1alpha1.EnvVar array	Env are environment variables to set in the MCP server container
volumes api.v1alpha1.Volume array	Volumes are volumes to mount in the MCP server container
resources api.v1alpha1.ResourceRequirements	Resources defines the resource requirements for the MCP server container
secrets api.v1alpha1.SecretRef array	Secrets are references to secrets to mount in the MCP server container
serviceAccount string	ServiceAccount 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 api.v1alpha1.PermissionProfileRef	PermissionProfile defines the permission profile to use
podTemplateSpec RawExtension	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. This field accepts a PodTemplateSpec object as JSON/YAML.		Type: object
resourceOverrides api.v1alpha1.ResourceOverrides	ResourceOverrides allows overriding annotations and labels for resources created by the operator
oidcConfig api.v1alpha1.OIDCConfigRef	OIDCConfig defines OIDC authentication configuration for the MCP server
authzConfig api.v1alpha1.AuthzConfigRef	AuthzConfig defines authorization policy configuration for the MCP server
audit api.v1alpha1.AuditConfig	Audit defines audit logging configuration for the MCP server
tools string array	ToolsFilter is the filter on tools applied to the MCP server Deprecated: Use ToolConfigRef instead
toolConfigRef api.v1alpha1.ToolConfigRef	ToolConfigRef 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.
externalAuthConfigRef api.v1alpha1.ExternalAuthConfigRef	ExternalAuthConfigRef references a MCPExternalAuthConfig resource for external authentication. The referenced MCPExternalAuthConfig must exist in the same namespace as this MCPServer.
telemetry api.v1alpha1.TelemetryConfig	Telemetry defines observability configuration for the MCP server
trustProxyHeaders boolean	TrustProxyHeaders indicates whether to trust X-Forwarded-* headers from reverse proxies When enabled, the proxy will use X-Forwarded-Proto, X-Forwarded-Host, X-Forwarded-Port, and X-Forwarded-Prefix headers to construct endpoint URLs	false
endpointPrefix string	EndpointPrefix is the path prefix to prepend to SSE endpoint URLs. This is used to handle path-based ingress routing scenarios where the ingress strips a path prefix before forwarding to the backend.
groupRef string	GroupRef is the name of the MCPGroup this server belongs to Must reference an existing MCPGroup in the same namespace

api.v1alpha1.MCPServerStatus

MCPServerStatus defines the observed state of MCPServer

Appears in:

• api.v1alpha1.MCPServer

Field	Description	Default	Validation
conditions Condition array	Conditions represent the latest available observations of the MCPServer's state
toolConfigHash string	ToolConfigHash stores the hash of the referenced ToolConfig for change detection
externalAuthConfigHash string	ExternalAuthConfigHash is the hash of the referenced MCPExternalAuthConfig spec
url string	URL is the URL where the MCP server can be accessed
phase api.v1alpha1.MCPServerPhase	Phase is the current phase of the MCPServer		Enum: [Pending Running Failed Terminating]
message string	Message provides additional information about the current phase

api.v1alpha1.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:

• api.v1alpha1.MCPToolConfigList

Field	Description	Default	Validation
apiVersion string	toolhive.stacklok.dev/v1alpha1
kind string	MCPToolConfig
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 api.v1alpha1.MCPToolConfigSpec
status api.v1alpha1.MCPToolConfigStatus

api.v1alpha1.MCPToolConfigList

MCPToolConfigList contains a list of MCPToolConfig

Field	Description	Default	Validation
apiVersion string	toolhive.stacklok.dev/v1alpha1
kind string	MCPToolConfigList
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 api.v1alpha1.MCPToolConfig array

api.v1alpha1.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:

• api.v1alpha1.MCPToolConfig

Field	Description	Default	Validation
toolsFilter string array	ToolsFilter 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:api.v1alpha1.ToolOverride)	ToolsOverride is a map from actual tool names to their overridden configuration. This allows renaming tools and/or changing their descriptions.

api.v1alpha1.MCPToolConfigStatus

MCPToolConfigStatus defines the observed state of MCPToolConfig

Appears in:

• api.v1alpha1.MCPToolConfig

Field	Description	Default	Validation
observedGeneration integer	ObservedGeneration 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 string	ConfigHash is a hash of the current configuration for change detection
referencingServers string array	ReferencingServers is a list of MCPServer resources that reference this MCPToolConfig This helps track which servers need to be reconciled when this config changes

api.v1alpha1.NameFilter

NameFilter defines name-based filtering

Appears in:

• api.v1alpha1.RegistryFilter

Field	Description	Default	Validation
include string array	Include is a list of glob patterns to include
exclude string array	Exclude is a list of glob patterns to exclude

api.v1alpha1.NetworkPermissions

NetworkPermissions defines the network permissions for an MCP server

Appears in:

• api.v1alpha1.PermissionProfileSpec

Field	Description	Default	Validation
mode string	Mode specifies the network mode for the container (e.g., "host", "bridge", "none") When empty, the default container runtime network mode is used
outbound api.v1alpha1.OutboundNetworkPermissions	Outbound defines the outbound network permissions

api.v1alpha1.OIDCConfigRef

OIDCConfigRef defines a reference to OIDC configuration

Appears in:

• api.v1alpha1.IncomingAuthConfig
• api.v1alpha1.MCPRemoteProxySpec
• api.v1alpha1.MCPServerSpec

Field	Description	Default	Validation
type string	Type is the type of OIDC configuration	kubernetes	Enum: [kubernetes configMap inline]
resourceUrl string	ResourceURL is the explicit resource URL for OAuth discovery endpoint (RFC 9728) If not specified, defaults to the in-cluster Kubernetes service URL
kubernetes api.v1alpha1.KubernetesOIDCConfig	Kubernetes configures OIDC for Kubernetes service account token validation Only used when Type is "kubernetes"
configMap api.v1alpha1.ConfigMapOIDCRef	ConfigMap references a ConfigMap containing OIDC configuration Only used when Type is "configmap"
inline api.v1alpha1.InlineOIDCConfig	Inline contains direct OIDC configuration Only used when Type is "inline"

api.v1alpha1.OpenTelemetryConfig

OpenTelemetryConfig defines pure OpenTelemetry configuration

Appears in:

• api.v1alpha1.TelemetryConfig

Field	Description	Default	Validation
enabled boolean	Enabled controls whether OpenTelemetry is enabled	false
endpoint string	Endpoint is the OTLP endpoint URL for tracing and metrics
serviceName string	ServiceName is the service name for telemetry If not specified, defaults to the MCPServer name
headers string array	Headers contains authentication headers for the OTLP endpoint Specified as key=value pairs
insecure boolean	Insecure indicates whether to use HTTP instead of HTTPS for the OTLP endpoint	false
metrics api.v1alpha1.OpenTelemetryMetricsConfig	Metrics defines OpenTelemetry metrics-specific configuration
tracing api.v1alpha1.OpenTelemetryTracingConfig	Tracing defines OpenTelemetry tracing configuration

api.v1alpha1.OpenTelemetryMetricsConfig

OpenTelemetryMetricsConfig defines OpenTelemetry metrics configuration

Appears in:

• api.v1alpha1.OpenTelemetryConfig

Field	Description	Default	Validation
enabled boolean	Enabled controls whether OTLP metrics are sent	false

api.v1alpha1.OpenTelemetryTracingConfig

OpenTelemetryTracingConfig defines OpenTelemetry tracing configuration

Appears in:

• api.v1alpha1.OpenTelemetryConfig

Field	Description	Default	Validation
enabled boolean	Enabled controls whether OTLP tracing is sent	false
samplingRate string	SamplingRate is the trace sampling rate (0.0-1.0)	0.05

api.v1alpha1.OutboundNetworkPermissions

OutboundNetworkPermissions defines the outbound network permissions

Appears in:

• api.v1alpha1.NetworkPermissions

Field	Description	Default	Validation
insecureAllowAll boolean	InsecureAllowAll allows all outbound network connections (not recommended)	false
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

api.v1alpha1.OutgoingAuthConfig

OutgoingAuthConfig configures authentication from Virtual MCP to backend MCPServers

Appears in:

• api.v1alpha1.VirtualMCPServerSpec

Field	Description	Default	Validation
source string	Source defines how backend authentication configurations are determined - discovered: Automatically discover from backend's MCPServer.spec.externalAuthConfigRef - inline: Explicit per-backend configuration in VirtualMCPServer	discovered	Enum: [discovered inline]
default api.v1alpha1.BackendAuthConfig	Default defines default behavior for backends without explicit auth config
backends object (keys:string, values:api.v1alpha1.BackendAuthConfig)	Backends defines per-backend authentication overrides Works in all modes (discovered, inline)

api.v1alpha1.PVCSource

PVCSource defines PersistentVolumeClaim source configuration

Appears in:

• api.v1alpha1.MCPRegistryConfig

Field	Description	Default	Validation
claimName string	ClaimName is the name of the PersistentVolumeClaim		MinLength: 1 Required: {}
path string	Path is the relative path to the registry file within the PVC. The PVC is mounted at /config/registry/{registryName}/. The full file path becomes: /config/registry/{registryName}/{path} This design: - Each registry gets its own mount point (consistent with ConfigMap sources) - Multiple registries can share the same PVC by mounting it at different paths - Users control PVC organization freely via the path field Examples: Registry "production" using PVC "shared-data" with path "prod/registry.json": PVC contains /prod/registry.json → accessed at /config/registry/production/prod/registry.json Registry "development" using SAME PVC "shared-data" with path "dev/registry.json": PVC contains /dev/registry.json → accessed at /config/registry/development/dev/registry.json (Same PVC, different mount path) Registry "staging" using DIFFERENT PVC "other-pvc" with path "registry.json": PVC contains /registry.json → accessed at /config/registry/staging/registry.json (Different PVC, independent mount) Registry "team-a" with path "v1/servers.json": PVC contains /v1/servers.json → accessed at /config/registry/team-a/v1/servers.json (Subdirectories allowed in path)	registry.json	Pattern: ^.*\.json$

api.v1alpha1.PermissionProfileRef

PermissionProfileRef defines a reference to a permission profile

Appears in:

• api.v1alpha1.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"

api.v1alpha1.PrometheusConfig

PrometheusConfig defines Prometheus-specific configuration

Appears in:

• api.v1alpha1.TelemetryConfig

Field	Description	Default	Validation
enabled boolean	Enabled controls whether Prometheus metrics endpoint is exposed	false

api.v1alpha1.ProxyDeploymentOverrides

ProxyDeploymentOverrides defines overrides specific to the proxy deployment

Appears in:

• api.v1alpha1.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
podTemplateMetadataOverrides api.v1alpha1.ResourceMetadataOverrides
env api.v1alpha1.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 Use TOOLHIVE_DEBUG=true to enable debug logging in the proxy

api.v1alpha1.RegistryFilter

RegistryFilter defines include/exclude patterns for registry content

Appears in:

• api.v1alpha1.MCPRegistryConfig

Field	Description	Default	Validation
names api.v1alpha1.NameFilter	NameFilters defines name-based filtering
tags api.v1alpha1.TagFilter	Tags defines tag-based filtering

api.v1alpha1.ResourceList

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

Appears in:

• api.v1alpha1.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)

api.v1alpha1.ResourceMetadataOverrides

ResourceMetadataOverrides defines metadata overrides for a resource

Appears in:

• api.v1alpha1.ProxyDeploymentOverrides
• api.v1alpha1.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

api.v1alpha1.ResourceOverrides

ResourceOverrides defines overrides for annotations and labels on created resources

Appears in:

• api.v1alpha1.MCPRemoteProxySpec
• api.v1alpha1.MCPServerSpec

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

api.v1alpha1.ResourceRequirements

ResourceRequirements describes the compute resource requirements

Appears in:

• api.v1alpha1.MCPRemoteProxySpec
• api.v1alpha1.MCPServerSpec

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

api.v1alpha1.SecretKeyRef

SecretKeyRef is a reference to a key within a Secret

Appears in:

• api.v1alpha1.HeaderInjectionConfig
• api.v1alpha1.InlineOIDCConfig
• api.v1alpha1.TokenExchangeConfig

Field	Description	Default	Validation
name string	Name is the name of the secret		Required: {}
key string	Key is the key within the secret		Required: {}

api.v1alpha1.SecretRef

SecretRef is a reference to a secret

Appears in:

• api.v1alpha1.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

api.v1alpha1.StorageReference

StorageReference defines a reference to internal storage

Appears in:

• api.v1alpha1.MCPRegistryStatus

Field	Description	Default	Validation
type string	Type is the storage type (configmap)		Enum: [configmap]
configMapRef LocalObjectReference	ConfigMapRef is a reference to a ConfigMap storage Only used when Type is "configmap"

api.v1alpha1.SyncPhase

Underlying type: string

SyncPhase represents the data synchronization state

Validation:

• Enum: [Syncing Complete Failed]

Appears in:

• api.v1alpha1.SyncStatus

Field	Description
Syncing	SyncPhaseSyncing means sync is currently in progress
Complete	SyncPhaseComplete means sync completed successfully
Failed	SyncPhaseFailed means sync failed

api.v1alpha1.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:

• api.v1alpha1.MCPRegistryConfig

Field	Description	Default	Validation
interval string	Interval 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: {}

api.v1alpha1.SyncStatus

SyncStatus provides detailed information about data synchronization

Appears in:

• api.v1alpha1.MCPRegistryStatus

Field	Description	Default	Validation
phase api.v1alpha1.SyncPhase	Phase represents the current synchronization phase		Enum: [Syncing Complete Failed]
message string	Message provides additional information about the sync status
lastAttempt Time	LastAttempt is the timestamp of the last sync attempt
attemptCount integer	AttemptCount is the number of sync attempts since last success		Minimum: 0
lastSyncTime Time	LastSyncTime is the timestamp of the last successful sync
lastSyncHash string	LastSyncHash is the hash of the last successfully synced data Used to detect changes in source data
serverCount integer	ServerCount is the total number of servers in the registry		Minimum: 0

api.v1alpha1.TagFilter

TagFilter defines tag-based filtering

Appears in:

• api.v1alpha1.RegistryFilter

Field	Description	Default	Validation
include string array	Include is a list of tags to include
exclude string array	Exclude is a list of tags to exclude

api.v1alpha1.TelemetryConfig

TelemetryConfig defines observability configuration for the MCP server

Appears in:

• api.v1alpha1.MCPRemoteProxySpec
• api.v1alpha1.MCPServerSpec

Field	Description	Default	Validation
openTelemetry api.v1alpha1.OpenTelemetryConfig	OpenTelemetry defines OpenTelemetry configuration
prometheus api.v1alpha1.PrometheusConfig	Prometheus defines Prometheus-specific configuration

api.v1alpha1.TokenExchangeConfig

TokenExchangeConfig holds configuration for RFC-8693 OAuth 2.0 Token Exchange. This configuration is used to exchange incoming authentication tokens for tokens that can be used with external services. The structure matches the tokenexchange.Config from pkg/auth/tokenexchange/middleware.go

Appears in:

• api.v1alpha1.MCPExternalAuthConfigSpec

Field	Description	Default	Validation
tokenUrl string	TokenURL is the OAuth 2.0 token endpoint URL for token exchange		Required: {}
clientId string	ClientID is the OAuth 2.0 client identifier Optional for some token exchange flows (e.g., Google Cloud Workforce Identity)
clientSecretRef api.v1alpha1.SecretKeyRef	ClientSecretRef is a reference to a secret containing the OAuth 2.0 client secret Optional for some token exchange flows (e.g., Google Cloud Workforce Identity)
audience string	Audience is the target audience for the exchanged token		Required: {}
scopes string array	Scopes is a list of OAuth 2.0 scopes to request for the exchanged token
subjectTokenType string	SubjectTokenType is the type of the incoming subject token. Accepts short forms: "access_token" (default), "id_token", "jwt" Or full URNs: "urn:ietf:params:oauth:token-type:access_token", "urn:ietf:params:oauth:token-type:id_token", "urn:ietf:params:oauth:token-type:jwt" For Google Workload Identity Federation with OIDC providers (like Okta), use "id_token"		Pattern: ^(access_token|id_token|jwt|urn:ietf:params:oauth:token-type:(access_token|id_token|jwt))?$
externalTokenHeaderName string	ExternalTokenHeaderName is the name of the custom header to use for the exchanged token. If set, the exchanged token will be added to this custom header (e.g., "X-Upstream-Token"). If empty or not set, the exchanged token will replace the Authorization header (default behavior).

api.v1alpha1.ToolConfigRef

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

Appears in:

• api.v1alpha1.MCPRemoteProxySpec
• api.v1alpha1.MCPServerSpec

Field	Description	Default	Validation
name string	Name is the name of the MCPToolConfig resource in the same namespace		Required: {}

api.v1alpha1.ToolOverride

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

Appears in:

• api.v1alpha1.MCPToolConfigSpec

Field	Description	Default	Validation
name string	Name is the redefined name of the tool
description string	Description is the redefined description of the tool

api.v1alpha1.ValidationStatus

Underlying type: string

ValidationStatus represents the validation state of a workflow

Validation:

• Enum: [Valid Invalid Unknown]

Appears in:

• api.v1alpha1.VirtualMCPCompositeToolDefinitionStatus

Field	Description
Valid	ValidationStatusValid indicates the workflow is valid
Invalid	ValidationStatusInvalid indicates the workflow has validation errors
Unknown	ValidationStatusUnknown indicates validation hasn't been performed yet

api.v1alpha1.VirtualMCPCompositeToolDefinition

VirtualMCPCompositeToolDefinition is the Schema for the virtualmcpcompositetooldefinitions API VirtualMCPCompositeToolDefinition defines reusable composite workflows that can be referenced by multiple VirtualMCPServer instances

Appears in:

• api.v1alpha1.VirtualMCPCompositeToolDefinitionList

Field	Description	Default	Validation
apiVersion string	toolhive.stacklok.dev/v1alpha1
kind string	VirtualMCPCompositeToolDefinition
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 api.v1alpha1.VirtualMCPCompositeToolDefinitionSpec
status api.v1alpha1.VirtualMCPCompositeToolDefinitionStatus

api.v1alpha1.VirtualMCPCompositeToolDefinitionList

VirtualMCPCompositeToolDefinitionList contains a list of VirtualMCPCompositeToolDefinition

Field	Description	Default	Validation
apiVersion string	toolhive.stacklok.dev/v1alpha1
kind string	VirtualMCPCompositeToolDefinitionList
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 api.v1alpha1.VirtualMCPCompositeToolDefinition array

api.v1alpha1.VirtualMCPCompositeToolDefinitionSpec

VirtualMCPCompositeToolDefinitionSpec defines the desired state of VirtualMCPCompositeToolDefinition. This embeds the CompositeToolConfig from pkg/vmcp/config to share the configuration model between CLI and operator usage.

Appears in:

• api.v1alpha1.VirtualMCPCompositeToolDefinition

Field	Description	Default	Validation
name string	Name is the workflow name (unique identifier).
description string	Description describes what the workflow does.
parameters pkg.json.Map	Parameters defines input parameter schema in JSON Schema format. Should be a JSON Schema object with "type": "object" and "properties". Example: { "type": "object", "properties": { "param1": {"type": "string", "default": "value"}, "param2": {"type": "integer"} }, "required": ["param2"] } We use json.Map rather than a typed struct because JSON Schema is highly flexible with many optional fields (default, enum, minimum, maximum, pattern, items, additionalProperties, oneOf, anyOf, allOf, etc.). Using json.Map allows full JSON Schema compatibility without needing to define every possible field, and matches how the MCP SDK handles inputSchema.
timeout vmcp.config.Duration	Timeout is the maximum workflow execution time.		Pattern: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$ Type: string
steps vmcp.config.WorkflowStepConfig array	Steps are the workflow steps to execute.
output vmcp.config.OutputConfig	Output defines the structured output schema for this workflow. If not specified, the workflow returns the last step's output (backward compatible).

api.v1alpha1.VirtualMCPCompositeToolDefinitionStatus

VirtualMCPCompositeToolDefinitionStatus defines the observed state of VirtualMCPCompositeToolDefinition

Appears in:

• api.v1alpha1.VirtualMCPCompositeToolDefinition

Field	Description	Default	Validation
validationStatus api.v1alpha1.ValidationStatus	ValidationStatus indicates the validation state of the workflow - Valid: Workflow structure is valid - Invalid: Workflow has validation errors		Enum: [Valid Invalid Unknown]
validationErrors string array	ValidationErrors contains validation error messages if ValidationStatus is Invalid
referencingVirtualServers string array	ReferencingVirtualServers lists VirtualMCPServer resources that reference this workflow This helps track which servers need to be reconciled when this workflow changes
observedGeneration integer	ObservedGeneration is the most recent generation observed for this VirtualMCPCompositeToolDefinition It corresponds to the resource's generation, which is updated on mutation by the API Server
conditions Condition array	Conditions represent the latest available observations of the workflow's state

api.v1alpha1.VirtualMCPServer

VirtualMCPServer is the Schema for the virtualmcpservers API VirtualMCPServer aggregates multiple backend MCPServers into a unified endpoint

Appears in:

• api.v1alpha1.VirtualMCPServerList

Field	Description	Default	Validation
apiVersion string	toolhive.stacklok.dev/v1alpha1
kind string	VirtualMCPServer
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 api.v1alpha1.VirtualMCPServerSpec
status api.v1alpha1.VirtualMCPServerStatus

api.v1alpha1.VirtualMCPServerList

VirtualMCPServerList contains a list of VirtualMCPServer

Field	Description	Default	Validation
apiVersion string	toolhive.stacklok.dev/v1alpha1
kind string	VirtualMCPServerList
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 api.v1alpha1.VirtualMCPServer array

api.v1alpha1.VirtualMCPServerPhase

Underlying type: string

VirtualMCPServerPhase represents the lifecycle phase of a VirtualMCPServer

Validation:

• Enum: [Pending Ready Degraded Failed]

Appears in:

• api.v1alpha1.VirtualMCPServerStatus

Field	Description
Pending	VirtualMCPServerPhasePending indicates the VirtualMCPServer is being initialized
Ready	VirtualMCPServerPhaseReady indicates the VirtualMCPServer is ready and serving requests
Degraded	VirtualMCPServerPhaseDegraded indicates the VirtualMCPServer is running but some backends are unavailable
Failed	VirtualMCPServerPhaseFailed indicates the VirtualMCPServer has failed

api.v1alpha1.VirtualMCPServerSpec

VirtualMCPServerSpec defines the desired state of VirtualMCPServer

Appears in:

• api.v1alpha1.VirtualMCPServer

Field	Description	Default	Validation
incomingAuth api.v1alpha1.IncomingAuthConfig	IncomingAuth configures authentication for clients connecting to the Virtual MCP server. Must be explicitly set - use "anonymous" type when no authentication is required. This field takes precedence over config.IncomingAuth and should be preferred because it supports Kubernetes-native secret references (SecretKeyRef, ConfigMapRef) for secure dynamic discovery of credentials, rather than requiring secrets to be embedded in config.		Required: {}
outgoingAuth api.v1alpha1.OutgoingAuthConfig	OutgoingAuth configures authentication from Virtual MCP to backend MCPServers. This field takes precedence over config.OutgoingAuth and should be preferred because it supports Kubernetes-native secret references (SecretKeyRef, ConfigMapRef) for secure dynamic discovery of credentials, rather than requiring secrets to be embedded in config.
serviceType string	ServiceType specifies the Kubernetes service type for the Virtual MCP server	ClusterIP	Enum: [ClusterIP NodePort LoadBalancer]
podTemplateSpec RawExtension	PodTemplateSpec defines the pod template to use for the Virtual 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 Virtual MCP server runs in, you must specify the 'vmcp' container name in the PodTemplateSpec. This field accepts a PodTemplateSpec object as JSON/YAML.		Type: object
config vmcp.config.Config	Config is the Virtual MCP server configuration The only field currently required within config is config.groupRef. GroupRef references an existing MCPGroup that defines backend workloads. The referenced MCPGroup must exist in the same namespace. The telemetry and audit config from here are also supported, but not required.		Type: object

api.v1alpha1.VirtualMCPServerStatus

VirtualMCPServerStatus defines the observed state of VirtualMCPServer

Appears in:

• api.v1alpha1.VirtualMCPServer

Field	Description	Default	Validation
conditions Condition array	Conditions represent the latest available observations of the VirtualMCPServer's state
observedGeneration integer	ObservedGeneration is the most recent generation observed for this VirtualMCPServer
phase api.v1alpha1.VirtualMCPServerPhase	Phase is the current phase of the VirtualMCPServer	Pending	Enum: [Pending Ready Degraded Failed]
message string	Message provides additional information about the current phase
url string	URL is the URL where the Virtual MCP server can be accessed
discoveredBackends api.v1alpha1.DiscoveredBackend array	DiscoveredBackends lists discovered backend configurations from the MCPGroup
backendCount integer	BackendCount is the number of discovered backends

api.v1alpha1.Volume

Volume represents a volume to mount in a container

Appears in:

• api.v1alpha1.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