crd-spec.md

title	Kubernetes CRD reference
sidebar_label	CRD Reference
description	ToolHive Kubernetes Operator Custom Resource Definitions (CRDs) reference.
toc_max_heading_level	4
mdx	format 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	Optional: {}
component string	Component is the component name to use in audit events.		Optional: {}
eventTypes string array	EventTypes specifies which event types to audit. If empty, all events are audited.		Optional: {}
excludeEventTypes string array	ExcludeEventTypes specifies which event types to exclude from auditing. This takes precedence over EventTypes.		Optional: {}
includeRequestData boolean	IncludeRequestData determines whether to include request data in audit logs.	false	Optional: {}
includeResponseData boolean	IncludeResponseData determines whether to include response data in audit logs.	false	Optional: {}
maxDataSize integer	MaxDataSize limits the size of request/response data included in audit logs (in bytes).	1024	Optional: {}
logFile string	LogFile specifies the file path for audit logs. If empty, logs to stdout.		Optional: {}

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", "upstream_inject"
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".
upstreamInject auth.types.UpstreamInjectConfig	UpstreamInject contains configuration for upstream inject auth strategy. Used when Type = "upstream_inject".

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.
subjectProviderName string	SubjectProviderName selects which upstream provider's token to use as the subject token. When set, the token is looked up from Identity.UpstreamTokens instead of using Identity.Token. When left empty and an embedded authorization server is configured, the system automatically populates this field with the first configured upstream provider name. Set it explicitly to override that default or to select a specific provider when multiple upstreams are configured.

auth.types.UpstreamInjectConfig

UpstreamInjectConfig configures the upstream inject auth strategy. This strategy uses the embedded authorization server to obtain and inject upstream IDP tokens into backend requests.

Appears in:

• auth.types.BackendAuthStrategy

Field	Description	Default	Validation
providerName string	ProviderName is the name of the upstream provider configured in the embedded authorization server. Must match an entry in AuthServer.Upstreams.

toolhive.stacklok.dev/config

vmcp.config.AggregationConfig

AggregationConfig defines tool aggregation, filtering, and conflict resolution strategies.

Tool Visibility vs Routing:

• ExcludeAllTools, per-workload ExcludeAll, and Filter control which tools are advertised to MCP clients (visible in tools/list responses).
• ALL backend tools remain available in the internal routing table, allowing composite tools to call hidden backend tools.
• This enables curated experiences where raw backend tools are hidden from MCP clients but accessible through composite tool workflows.

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] Optional: {}
conflictResolutionConfig vmcp.config.ConflictResolutionConfig	ConflictResolutionConfig provides configuration for the chosen strategy.		Optional: {}
tools vmcp.config.WorkloadToolConfig array	Tools defines per-workload tool filtering and overrides.		Optional: {}
excludeAllTools boolean	ExcludeAllTools hides all backend tools from MCP clients when true. Hidden tools are NOT advertised in tools/list responses, but they ARE available in the routing table for composite tools to use. This enables the use case where you want to hide raw backend tools from direct client access while exposing curated composite tool workflows.		Optional: {}

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").
primaryUpstreamProvider string	PrimaryUpstreamProvider names the upstream IDP provider whose access token should be used as the source of JWT claims for Cedar evaluation. When empty, claims from the ToolHive-issued token are used. Must match an upstream provider name configured in the embedded auth server (e.g. "default", "github"). Only relevant when the embedded auth server is active.		Optional: {}

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	Optional: {}
failureThreshold integer	FailureThreshold is the number of failures before opening the circuit. Must be >= 1.	5	Minimum: 1 Optional: {}
timeout vmcp.config.Duration	Timeout is the duration to wait before attempting to close the circuit. Must be >= 1s to prevent thrashing.	60s	Pattern: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$ Type: string Optional: {}

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.		Optional: {}
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).		Optional: {}

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.		Optional: {}
groupRef string	Group references an existing MCPGroup that defines backend workloads. In Kubernetes, the referenced MCPGroup must exist in the same namespace. Deprecated: Use spec.groupRef on VirtualMCPServerSpec instead.		Optional: {}
backends vmcp.config.StaticBackendConfig array	Backends defines pre-configured backend servers for static mode. When OutgoingAuth.Source is "inline", this field contains the full list of backend servers with their URLs and transport types, eliminating the need for K8s API access. When OutgoingAuth.Source is "discovered", this field is empty and backends are discovered at runtime via Kubernetes API.		Optional: {}
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.		Optional: {}
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.		Optional: {}
aggregation vmcp.config.AggregationConfig	Aggregation defines tool aggregation and conflict resolution strategies. Supports ToolConfigRef for Kubernetes-native MCPToolConfig resource references.		Optional: {}
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.		Optional: {}
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.		Optional: {}
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. Deprecated (Kubernetes operator only): When deploying via the operator, use VirtualMCPServer.spec.telemetryConfigRef to reference a shared MCPTelemetryConfig resource instead. This field remains valid for standalone (non-operator) deployments.		Optional: {}
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.		Optional: {}
optimizer vmcp.config.OptimizerConfig	Optimizer configures the MCP optimizer for context optimization on large toolsets. When enabled, vMCP exposes only find_tool and call_tool operations to clients instead of all backend tools directly. This reduces token usage by allowing LLMs to discover relevant tools on demand rather than receiving all tool definitions.		Optional: {}
sessionStorage vmcp.config.SessionStorageConfig	SessionStorage configures session storage for stateful horizontal scaling. When provider is "redis", the operator injects Redis connection parameters (address, db, keyPrefix) here. The Redis password is provided separately via the THV_SESSION_REDIS_PASSWORD environment variable.		Optional: {}

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}_	Optional: {}
priorityOrder string array	PriorityOrder defines the workload priority order for the "priority" strategy.		Optional: {}

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] Optional: {}

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 Optional: {}
unhealthyThreshold integer	UnhealthyThreshold is the number of consecutive failures before marking unhealthy.	3	Optional: {}
healthCheckTimeout vmcp.config.Duration	HealthCheckTimeout is the maximum duration for a single health check operation. Should be less than HealthCheckInterval to prevent checks from queuing up.	10s	Pattern: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$ Type: string Optional: {}
statusReportingInterval vmcp.config.Duration	StatusReportingInterval is the interval for reporting status updates to Kubernetes. This controls how often the vMCP runtime reports backend health and phase changes. Lower values provide faster status updates but increase API server load.	30s	Pattern: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$ Type: string Optional: {}
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] Optional: {}
circuitBreaker vmcp.config.CircuitBreakerConfig	CircuitBreaker configures circuit breaker behavior.		Optional: {}

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.		Pattern: ^https?://
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.
jwksUrl string	JWKSURL is the explicit JWKS endpoint URL. When set, skips OIDC discovery and fetches the JWKS directly from this URL. This is useful when the OIDC issuer does not serve a /.well-known/openid-configuration.		Optional: {}
introspectionUrl string	IntrospectionURL is the token introspection endpoint URL (RFC 7662). When set, enables token introspection for opaque (non-JWT) tokens.		Optional: {}
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
jwksAllowPrivateIp boolean	JwksAllowPrivateIP allows OIDC discovery and JWKS fetches to private IP addresses. Enable when the embedded auth server runs on a loopback address and the OIDC middleware needs to fetch its JWKS from that address. 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] Optional: {}
timeouts vmcp.config.TimeoutConfig	Timeouts configures timeout settings.		Optional: {}
failureHandling vmcp.config.FailureHandlingConfig	FailureHandling configures failure handling behavior.		Optional: {}

vmcp.config.OptimizerConfig

OptimizerConfig configures the MCP optimizer. When enabled, vMCP exposes only find_tool and call_tool operations to clients instead of all backend tools directly.

Appears in:

• vmcp.config.Config

Field	Description	Default	Validation
embeddingService string	EmbeddingService is the full base URL of the embedding service endpoint (e.g., http://my-embedding.default.svc.cluster.local:8080) for semantic tool discovery. In a Kubernetes environment, it is more convenient to use the VirtualMCPServerSpec.EmbeddingServerRef field instead of setting this directly. EmbeddingServerRef references an EmbeddingServer CRD by name, and the operator automatically resolves the referenced resource's Status.URL to populate this field. This provides managed lifecycle (the operator watches the EmbeddingServer for readiness and URL changes) and avoids hardcoding service URLs in the config. If both EmbeddingServerRef and this field are set, EmbeddingServerRef takes precedence and this value is overridden with a warning.		Optional: {}
embeddingServiceTimeout vmcp.config.Duration	EmbeddingServiceTimeout is the HTTP request timeout for calls to the embedding service. Defaults to 30s if not specified.	30s	Pattern: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$ Type: string Optional: {}
maxToolsToReturn integer	MaxToolsToReturn is the maximum number of tool results returned by a search query. Defaults to 8 if not specified or zero.		Maximum: 50 Minimum: 1 Optional: {}
hybridSearchSemanticRatio string	HybridSearchSemanticRatio controls the balance between semantic (meaning-based) and keyword search results. 0.0 = all keyword, 1.0 = all semantic. Defaults to "0.5" if not specified or empty. Serialized as a string because CRDs do not support float types portably.		Pattern: ^([0-9]*[.])?[0-9]+$ Optional: {}
semanticDistanceThreshold string	SemanticDistanceThreshold is the maximum distance for semantic search results. Results exceeding this threshold are filtered out from semantic search. This threshold does not apply to keyword search. Range: 0 = identical, 2 = completely unrelated. Defaults to "1.0" if not specified or empty. Serialized as a string because CRDs do not support float types portably.		Pattern: ^([0-9]*[.])?[0-9]+$ Optional: {}

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.		Optional: {}

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		Optional: {}
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}}		Optional: {}
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 Optional: {}
default pkg.json.Any	Default is the fallback value if template expansion fails. Type coercion is applied to match the declared Type.		Schemaless: {} Optional: {}

vmcp.config.SessionStorageConfig

SessionStorageConfig configures session storage for stateful horizontal scaling. The Redis password is not stored here; it is injected as the THV_SESSION_REDIS_PASSWORD environment variable by the operator when spec.sessionStorage.passwordRef is set.

Appears in:

• vmcp.config.Config

Field	Description	Default	Validation
provider string	Provider is the session storage backend type.		Enum: [memory redis] Required: {}
address string	Address is the Redis server address (required when provider is redis).		Optional: {}
db integer	DB is the Redis database number.	0	Minimum: 0 Optional: {}
keyPrefix string	KeyPrefix is an optional prefix for all Redis keys used by ToolHive.		Optional: {}

vmcp.config.StaticBackendConfig

StaticBackendConfig defines a pre-configured backend server for static mode. This allows vMCP to operate without Kubernetes API access by embedding all backend information directly in the configuration.

Appears in:

• vmcp.config.Config

Field	Description	Default	Validation
name string	Name is the backend identifier. Must match the backend name from the MCPGroup for auth config resolution.		Required: {}
url string	URL is the backend's MCP server base URL.		Pattern: ^https?:// Required: {}
transport string	Transport is the MCP transport protocol: "sse" or "streamable-http" Only network transports supported by vMCP client are allowed.		Enum: [sse streamable-http] Required: {}
type string	Type is the backend workload type: "entry" for MCPServerEntry backends, or empty for container/proxy backends. Entry backends connect directly to remote MCP servers.		Enum: [entry ] Optional: {}
caBundlePath string	CABundlePath is the file path to a custom CA certificate bundle for TLS verification. Only valid when Type is "entry". The operator mounts CA bundles at /etc/toolhive/ca-bundles//ca.crt.		Optional: {}
metadata object (keys:string, values:string)	Refer to Kubernetes API documentation for fields of metadata.		Optional: {}

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] Optional: {}
retryCount integer	RetryCount is the maximum number of retries Only used when Action is "retry"		Optional: {}
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 Optional: {}

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 Optional: {}
perWorkload object (keys:string, values:vmcp.config.Duration)	PerWorkload defines per-workload timeout overrides.		Optional: {}

vmcp.config.ToolAnnotationsOverride

Underlying type: [vmcp.config.struct{Title *string "json:"title,omitempty" yaml:"title,omitempty""; ReadOnlyHint *bool "json:"readOnlyHint,omitempty" yaml:"readOnlyHint,omitempty""; DestructiveHint *bool "json:"destructiveHint,omitempty" yaml:"destructiveHint,omitempty""; IdempotentHint *bool "json:"idempotentHint,omitempty" yaml:"idempotentHint,omitempty""; OpenWorldHint *bool "json:"openWorldHint,omitempty" yaml:"openWorldHint,omitempty""}](#vmcpconfigstruct{title *string "json:"title,omitempty" yaml:"title,omitempty""; readonlyhint *bool "json:"readonlyhint,omitempty" yaml:"readonlyhint,omitempty""; destructivehint *bool "json:"destructivehint,omitempty" yaml:"destructivehint,omitempty""; idempotenthint *bool "json:"idempotenthint,omitempty" yaml:"idempotenthint,omitempty""; openworldhint *bool "json:"openworldhint,omitempty" yaml:"openworldhint,omitempty""})

ToolAnnotationsOverride defines overrides for tool annotation fields. All fields use pointers so nil means "don't override" while zero values (empty string, false) mean "explicitly set to this value."

Appears in:

• vmcp.config.ToolOverride

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, description, and annotation overrides.

Appears in:

• vmcp.config.WorkloadToolConfig

Field	Description	Default	Validation
name string	Name is the new tool name (for renaming).		Optional: {}
description string	Description is the new tool description.		Optional: {}
annotations vmcp.config.ToolAnnotationsOverride	Annotations overrides specific tool annotation fields. Only specified fields are overridden; others pass through from the backend.		Optional: {}

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
• vmcp.config.WorkflowStepConfig

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 forEach] Optional: {}
tool string	Tool is the tool to call (format: "workload.tool_name") Only used when Type is "tool"		Optional: {}
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 Optional: {}
condition string	Condition is a template expression that determines if the step should execute		Optional: {}
dependsOn string array	DependsOn lists step IDs that must complete before this step		Optional: {}
onError vmcp.config.StepErrorHandling	OnError defines error handling behavior		Optional: {}
message string	Message is the elicitation message Only used when Type is "elicitation"		Optional: {}
schema pkg.json.Map	Schema defines the expected response schema for elicitation		Type: object Optional: {}
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 Optional: {}
onDecline vmcp.config.ElicitationResponseConfig	OnDecline defines the action to take when the user explicitly declines the elicitation Only used when Type is "elicitation"		Optional: {}
onCancel vmcp.config.ElicitationResponseConfig	OnCancel defines the action to take when the user cancels/dismisses the elicitation Only used when Type is "elicitation"		Optional: {}
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: {} Optional: {}
collection string	Collection is a Go template expression that resolves to a JSON array or a slice. Only used when Type is "forEach".		Optional: {}
itemVar string	ItemVar is the variable name used to reference the current item in forEach templates. Defaults to "item" if not specified. Only used when Type is "forEach".		Optional: {}
maxParallel integer	MaxParallel limits the number of concurrent iterations in a forEach step. Defaults to the DAG executor's maxParallel (10). Only used when Type is "forEach".		Optional: {}
maxIterations integer	MaxIterations limits the number of items that can be iterated over. Defaults to 100, hard cap at 1000. Only used when Type is "forEach".		Optional: {}
step vmcp.config.WorkflowStepConfig	InnerStep defines the step to execute for each item in the collection. Only used when Type is "forEach". Only tool-type inner steps are supported.		Type: object Optional: {}

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.		Optional: {}
filter string array	Filter is an allow-list of tool names to advertise to MCP clients. Tools NOT in this list are hidden from clients (not in tools/list response) but remain available in the routing table for composite tools to use. This enables selective exposure of backend tools while allowing composite workflows to orchestrate all backend capabilities. Only used if ToolConfigRef is not specified.		Optional: {}
overrides object (keys:string, values:vmcp.config.ToolOverride)	Overrides is an inline map of tool overrides for renaming and description changes. Overrides are applied to tools before conflict resolution and affect both advertising and routing (the overridden name is used everywhere). Only used if ToolConfigRef is not specified.		Optional: {}
excludeAll boolean	ExcludeAll hides all tools from this workload from MCP clients when true. Hidden tools are NOT advertised in tools/list responses, but they ARE available in the routing table for composite tools to use. This enables the use case where you want to hide raw backend tools from direct client access while exposing curated composite tool workflows.		Optional: {}

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		Optional: {}
serviceName string	ServiceName is the service name for telemetry. When omitted, defaults to the server name (e.g., VirtualMCPServer name).		Optional: {}
serviceVersion string	ServiceVersion is the service version for telemetry. When omitted, defaults to the ToolHive version.		Optional: {}
tracingEnabled boolean	TracingEnabled controls whether distributed tracing is enabled. When false, no tracer provider is created even if an endpoint is configured.	false	Optional: {}
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	Optional: {}
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	Optional: {}
headers object (keys:string, values:string)	Headers contains authentication headers for the OTLP endpoint.		Optional: {}
insecure boolean	Insecure indicates whether to use HTTP instead of HTTPS for the OTLP endpoint.	false	Optional: {}
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	Optional: {}
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"]		Optional: {}
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.		Optional: {}
useLegacyAttributes boolean	UseLegacyAttributes controls whether legacy (pre-MCP OTEL semconv) attribute names are emitted alongside the new standard attribute names. When true, spans include both old and new attribute names for backward compatibility with existing dashboards. Currently defaults to true; this will change to false in a future release.	true	Optional: {}
caCertPath string	CACertPath is the file path to a CA certificate bundle for the OTLP endpoint. When set, the OTLP exporters use this CA to verify the collector's TLS certificate instead of relying solely on the system CA pool.		Optional: {}

toolhive.stacklok.dev/v1alpha1

Resource Types

• api.v1alpha1.EmbeddingServer
• api.v1alpha1.EmbeddingServerList
• api.v1alpha1.MCPExternalAuthConfig
• api.v1alpha1.MCPExternalAuthConfigList
• api.v1alpha1.MCPGroup
• api.v1alpha1.MCPGroupList
• api.v1alpha1.MCPOIDCConfig
• api.v1alpha1.MCPOIDCConfigList
• api.v1alpha1.MCPRegistry
• api.v1alpha1.MCPRegistryList
• api.v1alpha1.MCPRemoteProxy
• api.v1alpha1.MCPRemoteProxyList
• api.v1alpha1.MCPServer
• api.v1alpha1.MCPServerEntry
• api.v1alpha1.MCPServerEntryList
• api.v1alpha1.MCPServerList
• api.v1alpha1.MCPTelemetryConfig
• api.v1alpha1.MCPTelemetryConfigList
• api.v1alpha1.MCPToolConfig
• api.v1alpha1.MCPToolConfigList
• api.v1alpha1.VirtualMCPCompositeToolDefinition
• api.v1alpha1.VirtualMCPCompositeToolDefinitionList
• api.v1alpha1.VirtualMCPServer
• api.v1alpha1.VirtualMCPServerList

api.v1alpha1.AWSStsConfig

AWSStsConfig holds configuration for AWS STS authentication with SigV4 request signing. This configuration exchanges incoming authentication tokens (typically OIDC JWT) for AWS STS temporary credentials, then signs requests to AWS services using SigV4.

Appears in:

• api.v1alpha1.MCPExternalAuthConfigSpec

Field	Description	Default	Validation
region string	Region is the AWS region for the STS endpoint and service (e.g., "us-east-1", "eu-west-1")		MinLength: 1 Pattern: ^[a-z]\{2\}(-[a-z]+)+-\d+$ Required: {}
service string	Service is the AWS service name for SigV4 signing Defaults to "aws-mcp" for AWS MCP Server endpoints	aws-mcp	Optional: {}
fallbackRoleArn string	FallbackRoleArn is the IAM role ARN to assume when no role mappings match Used as the default role when RoleMappings is empty or no mapping matches At least one of FallbackRoleArn or RoleMappings must be configured (enforced by webhook)		Pattern: ^arn:(aws|aws-cn|aws-us-gov):iam::\d\{12\}:role/[\w+=,.@\-_/]+$ Optional: {}
roleMappings api.v1alpha1.RoleMapping array	RoleMappings defines claim-based role selection rules Allows mapping JWT claims (e.g., groups, roles) to specific IAM roles Lower priority values are evaluated first (higher priority)		Optional: {}
roleClaim string	RoleClaim is the JWT claim to use for role mapping evaluation Defaults to "groups" to match common OIDC group claims	groups	Optional: {}
sessionDuration integer	SessionDuration is the duration in seconds for the STS session Must be between 900 (15 minutes) and 43200 (12 hours) Defaults to 3600 (1 hour) if not specified	3600	Maximum: 43200 Minimum: 900 Optional: {}
sessionNameClaim string	SessionNameClaim is the JWT claim to use for role session name Defaults to "sub" to use the subject claim	sub	Optional: {}

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	Optional: {}

api.v1alpha1.AuthServerRef

AuthServerRef defines a reference to a resource that configures an embedded OAuth 2.0/OIDC authorization server. Currently only MCPExternalAuthConfig is supported; the enum will be extended when a dedicated auth server CRD is introduced.

Appears in:

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

Field	Description	Default	Validation
kind string	Kind identifies the type of the referenced resource.	MCPExternalAuthConfig	Enum: [MCPExternalAuthConfig]
name string	Name is the name of the referenced resource in the same namespace.		MinLength: 1 Required: {}

api.v1alpha1.AuthServerStorageConfig

AuthServerStorageConfig configures the storage backend for the embedded auth server.

Appears in:

• api.v1alpha1.EmbeddedAuthServerConfig

Field	Description	Default	Validation
type api.v1alpha1.AuthServerStorageType	Type specifies the storage backend type. Valid values: "memory" (default), "redis".	memory	Enum: [memory redis]
redis api.v1alpha1.RedisStorageConfig	Redis configures the Redis storage backend. Required when type is "redis".		Optional: {}

api.v1alpha1.AuthServerStorageType

Underlying type: string

AuthServerStorageType represents the type of storage backend for the embedded auth server

Appears in:

• api.v1alpha1.AuthServerStorageConfig

Field	Description
memory	AuthServerStorageTypeMemory is the in-memory storage backend (default)
redis	AuthServerStorageTypeRedis is the Redis storage backend

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"		Optional: {}
inline api.v1alpha1.InlineAuthzConfig	Inline contains direct authorization configuration Only used when Type is "inline"		Optional: {}

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 externalAuthConfigRef external_auth_config_ref] Required: {}
externalAuthConfigRef api.v1alpha1.ExternalAuthConfigRef	ExternalAuthConfigRef references an MCPExternalAuthConfig resource Only used when Type is "externalAuthConfigRef" (or deprecated "external_auth_config_ref")		Optional: {}

api.v1alpha1.BearerTokenConfig

BearerTokenConfig holds configuration for bearer token authentication. This allows authenticating to remote MCP servers using bearer tokens stored in Kubernetes Secrets. For security reasons, only secret references are supported (no plaintext values).

Appears in:

• api.v1alpha1.MCPExternalAuthConfigSpec

Field	Description	Default	Validation
tokenSecretRef api.v1alpha1.SecretKeyRef	TokenSecretRef references a Kubernetes Secret containing the bearer token		Required: {}

api.v1alpha1.CABundleSource

CABundleSource defines a source for CA certificate bundles.

Appears in:

• api.v1alpha1.ConfigMapOIDCRef
• api.v1alpha1.InlineOIDCConfig
• api.v1alpha1.InlineOIDCSharedConfig
• api.v1alpha1.MCPServerEntrySpec
• api.v1alpha1.MCPTelemetryOTelConfig

Field	Description	Default	Validation
configMapRef ConfigMapKeySelector	ConfigMapRef references a ConfigMap containing the CA certificate bundle. If Key is not specified, it defaults to "ca.crt".		Optional: {}

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	Optional: {}

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	Optional: {}
caBundleRef api.v1alpha1.CABundleSource	CABundleRef references a ConfigMap containing the CA certificate bundle. When specified, ToolHive auto-mounts the ConfigMap and auto-computes ThvCABundlePath. If the ConfigMap data contains an explicit thvCABundlePath key, it takes precedence.		Optional: {}

api.v1alpha1.EmbeddedAuthServerConfig

EmbeddedAuthServerConfig holds configuration for the embedded OAuth2/OIDC authorization server. This enables running an authorization server that delegates authentication to upstream IDPs.

Appears in:

• api.v1alpha1.MCPExternalAuthConfigSpec
• api.v1alpha1.VirtualMCPServerSpec

Field	Description	Default	Validation
issuer string	Issuer is the issuer identifier for this authorization server. This will be included in the "iss" claim of issued tokens. Must be a valid HTTPS URL (or HTTP for localhost) without query, fragment, or trailing slash (per RFC 8414).		Pattern: ^https?://[^\s?#]+[^/\s?#]$ Required: {}
authorizationEndpointBaseUrl string	AuthorizationEndpointBaseURL overrides the base URL used for the authorization_endpoint in the OAuth discovery document. When set, the discovery document will advertise \{authorizationEndpointBaseUrl\}/oauth/authorize instead of \{issuer\}/oauth/authorize. All other endpoints (token, registration, JWKS) remain derived from the issuer. This is useful when the browser-facing authorization endpoint needs to be on a different host than the issuer used for backend-to-backend calls. Must be a valid HTTPS URL (or HTTP for localhost) without query, fragment, or trailing slash.		Pattern: ^https?://[^\s?#]+[^/\s?#]$ Optional: {}
signingKeySecretRefs api.v1alpha1.SecretKeyRef array	SigningKeySecretRefs references Kubernetes Secrets containing signing keys for JWT operations. Supports key rotation by allowing multiple keys (oldest keys are used for verification only). If not specified, an ephemeral signing key will be auto-generated (development only - JWTs will be invalid after restart).		MaxItems: 5 Optional: {}
hmacSecretRefs api.v1alpha1.SecretKeyRef array	HMACSecretRefs references Kubernetes Secrets containing symmetric secrets for signing authorization codes and refresh tokens (opaque tokens). Current secret must be at least 32 bytes and cryptographically random. Supports secret rotation via multiple entries (first is current, rest are for verification). If not specified, an ephemeral secret will be auto-generated (development only - auth codes and refresh tokens will be invalid after restart).		Optional: {}
tokenLifespans api.v1alpha1.TokenLifespanConfig	TokenLifespans configures the duration that various tokens are valid. If not specified, defaults are applied (access: 1h, refresh: 7d, authCode: 10m).		Optional: {}
upstreamProviders api.v1alpha1.UpstreamProviderConfig array	UpstreamProviders configures connections to upstream Identity Providers. The embedded auth server delegates authentication to these providers. MCPServer and MCPRemoteProxy support a single upstream; VirtualMCPServer supports multiple.		MinItems: 1 Required: {}
storage api.v1alpha1.AuthServerStorageConfig	Storage configures the storage backend for the embedded auth server. If not specified, defaults to in-memory storage.		Optional: {}

api.v1alpha1.EmbeddingResourceOverrides

EmbeddingResourceOverrides defines overrides for annotations and labels on created resources

Appears in:

• api.v1alpha1.EmbeddingServerSpec

Field	Description	Default	Validation
statefulSet api.v1alpha1.EmbeddingStatefulSetOverrides	StatefulSet defines overrides for the StatefulSet resource		Optional: {}
service api.v1alpha1.ResourceMetadataOverrides	Service defines overrides for the Service resource		Optional: {}
persistentVolumeClaim api.v1alpha1.ResourceMetadataOverrides	PersistentVolumeClaim defines overrides for the PVC resource		Optional: {}

api.v1alpha1.EmbeddingServer

EmbeddingServer is the Schema for the embeddingservers API

Appears in:

• api.v1alpha1.EmbeddingServerList

Field	Description	Default	Validation
apiVersion string	toolhive.stacklok.dev/v1alpha1
kind string	EmbeddingServer
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		Optional: {}
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		Optional: {}
metadata ObjectMeta	Refer to Kubernetes API documentation for fields of metadata.
spec api.v1alpha1.EmbeddingServerSpec
status api.v1alpha1.EmbeddingServerStatus

api.v1alpha1.EmbeddingServerList

EmbeddingServerList contains a list of EmbeddingServer

Field	Description	Default	Validation
apiVersion string	toolhive.stacklok.dev/v1alpha1
kind string	EmbeddingServerList
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		Optional: {}
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		Optional: {}
metadata ListMeta	Refer to Kubernetes API documentation for fields of metadata.
items api.v1alpha1.EmbeddingServer array

api.v1alpha1.EmbeddingServerPhase

Underlying type: string

EmbeddingServerPhase is the phase of the EmbeddingServer

Validation:

• Enum: [Pending Downloading Ready Failed Terminating]

Appears in:

• api.v1alpha1.EmbeddingServerStatus

Field	Description
Pending	EmbeddingServerPhasePending means the EmbeddingServer is being created
Downloading	EmbeddingServerPhaseDownloading means the model is being downloaded
Ready	EmbeddingServerPhaseReady means the EmbeddingServer is ready
Failed	EmbeddingServerPhaseFailed means the EmbeddingServer failed to start
Terminating	EmbeddingServerPhaseTerminating means the EmbeddingServer is being deleted

api.v1alpha1.EmbeddingServerRef

EmbeddingServerRef references an existing EmbeddingServer resource by name. This follows the same pattern as ExternalAuthConfigRef and ToolConfigRef.

Appears in:

• api.v1alpha1.VirtualMCPServerSpec

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

api.v1alpha1.EmbeddingServerSpec

EmbeddingServerSpec defines the desired state of EmbeddingServer

Appears in:

• api.v1alpha1.EmbeddingServer

Field	Description	Default	Validation
model string	Model is the HuggingFace embedding model to use (e.g., "sentence-transformers/all-MiniLM-L6-v2")	BAAI/bge-small-en-v1.5	Optional: {}
hfTokenSecretRef api.v1alpha1.SecretKeyRef	HFTokenSecretRef is a reference to a Kubernetes Secret containing the huggingface token. If provided, the secret value will be provided to the embedding server for authentication with huggingface.		Optional: {}
image string	Image is the container image for the embedding inference server. Images must be from HuggingFace Text Embeddings Inference (https://github.com/huggingface/text-embeddings-inference).	ghcr.io/huggingface/text-embeddings-inference:cpu-latest	Optional: {}
imagePullPolicy string	ImagePullPolicy defines the pull policy for the container image	IfNotPresent	Enum: [Always Never IfNotPresent] Optional: {}
port integer	Port is the port to expose the embedding service on	8080	Maximum: 65535 Minimum: 1
args string array	Args are additional arguments to pass to the embedding inference server		Optional: {}
env api.v1alpha1.EnvVar array	Env are environment variables to set in the container		Optional: {}
resources api.v1alpha1.ResourceRequirements	Resources defines compute resources for the embedding server		Optional: {}
modelCache api.v1alpha1.ModelCacheConfig	ModelCache configures persistent storage for downloaded models When enabled, models are cached in a PVC and reused across pod restarts		Optional: {}
podTemplateSpec RawExtension	PodTemplateSpec allows customizing the pod (node selection, tolerations, etc.) This field accepts a PodTemplateSpec object as JSON/YAML. Note that to modify the specific container the embedding server runs in, you must specify the 'embedding' container name in the PodTemplateSpec.		Type: object Optional: {}
resourceOverrides api.v1alpha1.EmbeddingResourceOverrides	ResourceOverrides allows overriding annotations and labels for resources created by the operator		Optional: {}
replicas integer	Replicas is the number of embedding server replicas to run	1	Minimum: 1 Optional: {}

api.v1alpha1.EmbeddingServerStatus

EmbeddingServerStatus defines the observed state of EmbeddingServer

Appears in:

• api.v1alpha1.EmbeddingServer

Field	Description	Default	Validation
conditions Condition array	Conditions represent the latest available observations of the EmbeddingServer's state		Optional: {}
phase api.v1alpha1.EmbeddingServerPhase	Phase is the current phase of the EmbeddingServer		Enum: [Pending Downloading Ready Failed Terminating] Optional: {}
message string	Message provides additional information about the current phase		Optional: {}
url string	URL is the URL where the embedding service can be accessed		Optional: {}
readyReplicas integer	ReadyReplicas is the number of ready replicas		Optional: {}
observedGeneration integer	ObservedGeneration reflects the generation most recently observed by the controller		Optional: {}

api.v1alpha1.EmbeddingStatefulSetOverrides

EmbeddingStatefulSetOverrides defines overrides specific to the embedding statefulset

Appears in:

• api.v1alpha1.EmbeddingResourceOverrides

Field	Description	Default	Validation
annotations object (keys:string, values:string)	Annotations to add or override on the resource		Optional: {}
labels object (keys:string, values:string)	Labels to add or override on the resource		Optional: {}
podTemplateMetadataOverrides api.v1alpha1.ResourceMetadataOverrides	PodTemplateMetadataOverrides defines metadata overrides for the pod template		Optional: {}

api.v1alpha1.EnvVar

EnvVar represents an environment variable in a container

Appears in:

• api.v1alpha1.EmbeddingServerSpec
• 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.MCPServerEntrySpec
• 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
bearerToken	ExternalAuthTypeBearerToken is the type for bearer token authentication This allows authenticating to remote MCP servers using bearer tokens stored in Kubernetes Secrets
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
embeddedAuthServer	ExternalAuthTypeEmbeddedAuthServer is the type for embedded OAuth2/OIDC authorization server This enables running an embedded auth server that delegates to upstream IDPs
awsSts	ExternalAuthTypeAWSSts is the type for AWS STS authentication
upstreamInject	ExternalAuthTypeUpstreamInject is the type for upstream token injection This injects an upstream IDP access token as the Authorization: Bearer header

api.v1alpha1.HeaderForwardConfig

HeaderForwardConfig defines header forward configuration for remote servers.

Appears in:

• api.v1alpha1.MCPRemoteProxySpec
• api.v1alpha1.MCPServerEntrySpec

Field	Description	Default	Validation
addPlaintextHeaders object (keys:string, values:string)	AddPlaintextHeaders is a map of header names to literal values to inject into requests. WARNING: Values are stored in plaintext and visible via kubectl commands. Use addHeadersFromSecret for sensitive data like API keys or tokens.		Optional: {}
addHeadersFromSecret api.v1alpha1.HeaderFromSecret array	AddHeadersFromSecret references Kubernetes Secrets for sensitive header values.		Optional: {}

api.v1alpha1.HeaderFromSecret

HeaderFromSecret defines a header whose value comes from a Kubernetes Secret.

Appears in:

• api.v1alpha1.HeaderForwardConfig

Field	Description	Default	Validation
headerName string	HeaderName is the HTTP header name (e.g., "X-API-Key")		MaxLength: 255 MinLength: 1 Required: {}
valueSecretRef api.v1alpha1.SecretKeyRef	ValueSecretRef references the Secret and key containing the header value		Required: {}

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. Deprecated: Use OIDCConfigRef to reference a shared MCPOIDCConfig resource instead. This field will be removed in v1beta1. OIDCConfig and OIDCConfigRef are mutually exclusive.		Optional: {}
oidcConfigRef api.v1alpha1.MCPOIDCConfigReference	OIDCConfigRef references a shared MCPOIDCConfig resource for OIDC authentication. The referenced MCPOIDCConfig must exist in the same namespace as this VirtualMCPServer. Per-server overrides (audience, scopes) are specified here; shared provider config lives in the MCPOIDCConfig resource. Mutually exclusive with oidcConfig.		Optional: {}
authzConfig api.v1alpha1.AuthzConfigRef	AuthzConfig defines authorization policy configuration Reuses MCPServer authz patterns		Optional: {}

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	[]	Optional: {}

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		Optional: {}
jwksUrl string	JWKSURL is the URL to fetch the JWKS from		Optional: {}
introspectionUrl string	IntrospectionURL is the URL for token introspection endpoint		Optional: {}
clientId string	ClientID is the OIDC client ID		Optional: {}
clientSecretRef api.v1alpha1.SecretKeyRef	ClientSecretRef is a reference to a Kubernetes Secret containing the client secret		Optional: {}
caBundleRef api.v1alpha1.CABundleSource	CABundleRef references a ConfigMap containing the CA certificate bundle. When specified, ToolHive auto-mounts the ConfigMap and auto-computes the CA bundle path.		Optional: {}
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)		Optional: {}
jwksAllowPrivateIP boolean	JWKSAllowPrivateIP allows JWKS/OIDC endpoints on private IP addresses. Use with caution - only enable for trusted internal IDPs. Note: at runtime, if either JWKSAllowPrivateIP or ProtectedResourceAllowPrivateIP is true, private IPs are allowed for all OIDC HTTP requests (JWKS, discovery, introspection).	false	Optional: {}
protectedResourceAllowPrivateIP boolean	ProtectedResourceAllowPrivateIP allows protected resource endpoint on private IP addresses. Use with caution - only enable for trusted internal IDPs or testing. Note: at runtime, if either ProtectedResourceAllowPrivateIP or JWKSAllowPrivateIP is true, private IPs are allowed for all OIDC HTTP requests (JWKS, discovery, introspection).	false	Optional: {}
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	Optional: {}
scopes string array	Scopes is the list of OAuth scopes to advertise in the well-known endpoint (RFC 9728) If empty, defaults to ["openid"]		Optional: {}

api.v1alpha1.InlineOIDCSharedConfig

InlineOIDCSharedConfig contains direct OIDC configuration. This contains shared fields without audience and scopes, which are specified per-server via MCPOIDCConfigReference.

Appears in:

• api.v1alpha1.MCPOIDCConfigSpec

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

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		Optional: {}
namespace string	Namespace is the namespace of the service account If empty, uses the MCPServer's namespace		Optional: {}
audience string	Audience is the expected audience for the token	toolhive	Optional: {}
issuer string	Issuer is the OIDC issuer URL	https://kubernetes.default.svc	Optional: {}
jwksUrl string	JWKSURL is the URL to fetch the JWKS from If empty, OIDC discovery will be used to automatically determine the JWKS URL		Optional: {}
introspectionUrl string	IntrospectionURL is the URL for token introspection endpoint If empty, OIDC discovery will be used to automatically determine the introspection URL		Optional: {}
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		Optional: {}

api.v1alpha1.KubernetesServiceAccountOIDCConfig

KubernetesServiceAccountOIDCConfig configures OIDC for Kubernetes service account token validation. This contains shared fields without audience, which is specified per-server via MCPOIDCConfigReference.

Appears in:

• api.v1alpha1.MCPOIDCConfigSpec

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.		Optional: {}
namespace string	Namespace is the namespace of the service account. If empty, uses the MCPServer's namespace.		Optional: {}
issuer string	Issuer is the OIDC issuer URL.	https://kubernetes.default.svc	Optional: {}
jwksUrl string	JWKSURL is the URL to fetch the JWKS from. If empty, OIDC discovery will be used to automatically determine the JWKS URL.		Optional: {}
introspectionUrl string	IntrospectionURL is the URL for token introspection endpoint. If empty, OIDC discovery will be used to automatically determine the introspection URL.		Optional: {}
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.		Optional: {}

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		Optional: {}
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		Optional: {}
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		Optional: {}
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		Optional: {}
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 bearerToken unauthenticated embeddedAuthServer awsSts upstreamInject] Required: {}
tokenExchange api.v1alpha1.TokenExchangeConfig	TokenExchange configures RFC-8693 OAuth 2.0 Token Exchange Only used when Type is "tokenExchange"		Optional: {}
headerInjection api.v1alpha1.HeaderInjectionConfig	HeaderInjection configures custom HTTP header injection Only used when Type is "headerInjection"		Optional: {}
bearerToken api.v1alpha1.BearerTokenConfig	BearerToken configures bearer token authentication Only used when Type is "bearerToken"		Optional: {}
embeddedAuthServer api.v1alpha1.EmbeddedAuthServerConfig	EmbeddedAuthServer configures an embedded OAuth2/OIDC authorization server Only used when Type is "embeddedAuthServer"		Optional: {}
awsSts api.v1alpha1.AWSStsConfig	AWSSts configures AWS STS authentication with SigV4 request signing Only used when Type is "awsSts"		Optional: {}
upstreamInject api.v1alpha1.UpstreamInjectSpec	UpstreamInject configures upstream token injection for backend requests. Only used when Type is "upstreamInject".		Optional: {}

api.v1alpha1.MCPExternalAuthConfigStatus

MCPExternalAuthConfigStatus defines the observed state of MCPExternalAuthConfig

Appears in:

• api.v1alpha1.MCPExternalAuthConfig

Field	Description	Default	Validation
conditions Condition array	Conditions represent the latest available observations of the MCPExternalAuthConfig's state		Optional: {}
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.		Optional: {}
configHash string	ConfigHash is a hash of the current configuration for change detection		Optional: {}
referencingWorkloads api.v1alpha1.WorkloadReference array	ReferencingWorkloads is a list of workload resources that reference this MCPExternalAuthConfig. Each entry identifies the workload by kind and name.		Optional: {}

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		Optional: {}
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		Optional: {}
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		Optional: {}
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		Optional: {}
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.MCPGroupRef

MCPGroupRef defines a reference to an MCPGroup resource. The referenced MCPGroup must be in the same namespace.

Appears in:

• api.v1alpha1.MCPRemoteProxySpec
• api.v1alpha1.MCPServerEntrySpec
• api.v1alpha1.MCPServerSpec
• api.v1alpha1.VirtualMCPServerSpec

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

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		Optional: {}

api.v1alpha1.MCPGroupStatus

MCPGroupStatus defines observed state

Appears in:

• api.v1alpha1.MCPGroup

Field	Description	Default	Validation
observedGeneration integer	ObservedGeneration reflects the generation most recently observed by the controller		Optional: {}
phase api.v1alpha1.MCPGroupPhase	Phase indicates current state	Pending	Enum: [Ready Pending Failed] Optional: {}
servers string array	Servers lists MCPServer names in this group		Optional: {}
serverCount integer	ServerCount is the number of MCPServers		Optional: {}
remoteProxies string array	RemoteProxies lists MCPRemoteProxy names in this group		Optional: {}
remoteProxyCount integer	RemoteProxyCount is the number of MCPRemoteProxies		Optional: {}
entries string array	Entries lists MCPServerEntry names in this group		Optional: {}
entryCount integer	EntryCount is the number of MCPServerEntries		Optional: {}
conditions Condition array	Conditions represent observations		Optional: {}

api.v1alpha1.MCPOIDCConfig

MCPOIDCConfig is the Schema for the mcpoidcconfigs API. MCPOIDCConfig 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.MCPOIDCConfigList

Field	Description	Default	Validation
apiVersion string	toolhive.stacklok.dev/v1alpha1
kind string	MCPOIDCConfig
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		Optional: {}
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		Optional: {}
metadata ObjectMeta	Refer to Kubernetes API documentation for fields of metadata.
spec api.v1alpha1.MCPOIDCConfigSpec
status api.v1alpha1.MCPOIDCConfigStatus

api.v1alpha1.MCPOIDCConfigList

MCPOIDCConfigList contains a list of MCPOIDCConfig

Field	Description	Default	Validation
apiVersion string	toolhive.stacklok.dev/v1alpha1
kind string	MCPOIDCConfigList
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		Optional: {}
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		Optional: {}
metadata ListMeta	Refer to Kubernetes API documentation for fields of metadata.
items api.v1alpha1.MCPOIDCConfig array

api.v1alpha1.MCPOIDCConfigReference

MCPOIDCConfigReference is a reference to an MCPOIDCConfig resource with per-server overrides. The referenced MCPOIDCConfig must be in the same namespace as the MCPServer.

Appears in:

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

Field	Description	Default	Validation
name string	Name is the name of the MCPOIDCConfig resource		MinLength: 1 Required: {}
audience string	Audience is the expected audience for token validation. This MUST be unique per server to prevent token replay attacks.		MinLength: 1 Required: {}
scopes string array	Scopes is the list of OAuth scopes to advertise in the well-known endpoint (RFC 9728). If empty, defaults to ["openid"].		Optional: {}

api.v1alpha1.MCPOIDCConfigSourceType

Underlying type: string

MCPOIDCConfigSourceType represents the type of OIDC configuration source for MCPOIDCConfig

Appears in:

• api.v1alpha1.MCPOIDCConfigSpec

Field	Description
kubernetesServiceAccount	MCPOIDCConfigTypeKubernetesServiceAccount is the type for Kubernetes service account token validation
inline	MCPOIDCConfigTypeInline is the type for inline OIDC configuration

api.v1alpha1.MCPOIDCConfigSpec

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

Appears in:

• api.v1alpha1.MCPOIDCConfig

Field	Description	Default	Validation
type api.v1alpha1.MCPOIDCConfigSourceType	Type is the type of OIDC configuration source		Enum: [kubernetesServiceAccount inline] Required: {}
kubernetesServiceAccount api.v1alpha1.KubernetesServiceAccountOIDCConfig	KubernetesServiceAccount configures OIDC for Kubernetes service account token validation. Only used when Type is "kubernetesServiceAccount".		Optional: {}
inline api.v1alpha1.InlineOIDCSharedConfig	Inline contains direct OIDC configuration. Only used when Type is "inline".		Optional: {}

api.v1alpha1.MCPOIDCConfigStatus

MCPOIDCConfigStatus defines the observed state of MCPOIDCConfig

Appears in:

• api.v1alpha1.MCPOIDCConfig

Field	Description	Default	Validation
conditions Condition array	Conditions represent the latest available observations of the MCPOIDCConfig's state		Optional: {}
observedGeneration integer	ObservedGeneration is the most recent generation observed for this MCPOIDCConfig.		Optional: {}
configHash string	ConfigHash is a hash of the current configuration for change detection		Optional: {}
referencingWorkloads api.v1alpha1.WorkloadReference array	ReferencingWorkloads is a list of workload resources that reference this MCPOIDCConfig. Each entry identifies the workload by kind and name.		Optional: {}

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		Optional: {}
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		Optional: {}
metadata ObjectMeta	Refer to Kubernetes API documentation for fields of metadata.
spec api.v1alpha1.MCPRegistrySpec
status api.v1alpha1.MCPRegistryStatus

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		Optional: {}
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		Optional: {}
metadata ListMeta	Refer to Kubernetes API documentation for fields of metadata.
items api.v1alpha1.MCPRegistry array

api.v1alpha1.MCPRegistryPhase

Underlying type: string

MCPRegistryPhase represents the phase of the MCPRegistry

Validation:

• Enum: [Pending Ready Failed 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
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
configYAML string	ConfigYAML is the complete registry server config.yaml content. The operator creates a ConfigMap from this string and mounts it at /config/config.yaml in the registry-api container. The operator does NOT parse, validate, or transform this content — configuration validation is the registry server's responsibility. Security note: this content is stored in a ConfigMap, not a Secret. Do not inline credentials (passwords, tokens, client secrets) in this field. Instead, reference credentials via file paths and mount the actual secrets using the Volumes and VolumeMounts fields. For database passwords, use PGPassSecretRef.		MinLength: 1 Required: {}
volumes JSON array	Volumes defines additional volumes to add to the registry API pod. Each entry is a standard Kubernetes Volume object (JSON/YAML). The operator appends them to the pod spec alongside its own config volume. Use these to mount: - Secrets (git auth tokens, OAuth client secrets, CA certs) - ConfigMaps (registry data files) - PersistentVolumeClaims (registry data on persistent storage) - Any other volume type the registry server needs		Optional: {}
volumeMounts JSON array	VolumeMounts defines additional volume mounts for the registry-api container. Each entry is a standard Kubernetes VolumeMount object (JSON/YAML). The operator appends them to the container's volume mounts alongside the config mount. Mount paths must match the file paths referenced in configYAML. For example, if configYAML references passwordFile: /secrets/git-creds/token, a corresponding volume mount must exist with mountPath: /secrets/git-creds.		Optional: {}
pgpassSecretRef SecretKeySelector	PGPassSecretRef references a Secret containing a pre-created pgpass file. Why this is a dedicated field instead of a regular volume/volumeMount: PostgreSQL's libpq rejects pgpass files that aren't mode 0600. Kubernetes secret volumes mount files as root-owned, and the registry-api container runs as non-root (UID 65532). A root-owned 0600 file is unreadable by UID 65532, and using fsGroup changes permissions to 0640 which libpq also rejects. The only solution is an init container that copies the file to an emptyDir as the app user and runs chmod 0600. This cannot be expressed through volumes/volumeMounts alone -- it requires an init container, two extra volumes (secret + emptyDir), a subPath mount, and an environment variable, all wired together correctly. When specified, the operator generates all of that plumbing invisibly. The user creates the Secret with pgpass-formatted content; the operator handles only the Kubernetes permission mechanics. Example Secret: apiVersion: v1 kind: Secret metadata: name: my-pgpass stringData: .pgpass: | postgres:5432:registry:db_app:mypassword postgres:5432:registry:db_migrator:otherpassword Then reference it: pgpassSecretRef: name: my-pgpass key: .pgpass		Optional: {}
displayName string	DisplayName is a human-readable name for the registry.		Optional: {}
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 Optional: {}

api.v1alpha1.MCPRegistryStatus

MCPRegistryStatus defines the observed state of MCPRegistry

Appears in:

• api.v1alpha1.MCPRegistry

Field	Description	Default	Validation
conditions Condition array	Conditions represent the latest available observations of the MCPRegistry's state		Optional: {}
observedGeneration integer	ObservedGeneration reflects the generation most recently observed by the controller		Optional: {}
phase api.v1alpha1.MCPRegistryPhase	Phase represents the current overall phase of the MCPRegistry		Enum: [Pending Ready Failed Terminating] Optional: {}
message string	Message provides additional information about the current phase		Optional: {}
url string	URL is the URL where the registry API can be accessed		Optional: {}
readyReplicas integer	ReadyReplicas is the number of ready registry API replicas		Optional: {}

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		Optional: {}
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		Optional: {}
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		Optional: {}
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		Optional: {}
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: {}
proxyPort integer	ProxyPort 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. Deprecated: Use OIDCConfigRef to reference a shared MCPOIDCConfig resource instead. This field will be removed in v1beta1. OIDCConfig and OIDCConfigRef are mutually exclusive.		Optional: {}
oidcConfigRef api.v1alpha1.MCPOIDCConfigReference	OIDCConfigRef references a shared MCPOIDCConfig resource for OIDC authentication. The referenced MCPOIDCConfig must exist in the same namespace as this MCPRemoteProxy. Per-server overrides (audience, scopes) are specified here; shared provider config lives in the MCPOIDCConfig resource.		Optional: {}
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.		Optional: {}
authServerRef api.v1alpha1.AuthServerRef	AuthServerRef optionally references a resource that configures an embedded OAuth 2.0/OIDC authorization server to authenticate MCP clients. Currently the only supported kind is MCPExternalAuthConfig (type: embeddedAuthServer).		Optional: {}
headerForward api.v1alpha1.HeaderForwardConfig	HeaderForward configures headers to inject into requests to the remote MCP server. Use this to add custom headers like X-Tenant-ID or correlation IDs.		Optional: {}
authzConfig api.v1alpha1.AuthzConfigRef	AuthzConfig defines authorization policy configuration for the proxy		Optional: {}
audit api.v1alpha1.AuditConfig	Audit defines audit logging configuration for the proxy		Optional: {}
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.		Optional: {}
telemetryConfigRef api.v1alpha1.MCPTelemetryConfigReference	TelemetryConfigRef references an MCPTelemetryConfig resource for shared telemetry configuration. The referenced MCPTelemetryConfig must exist in the same namespace as this MCPRemoteProxy. Cross-namespace references are not supported for security and isolation reasons. Mutually exclusive with the deprecated inline Telemetry field.		Optional: {}
telemetry api.v1alpha1.TelemetryConfig	Telemetry defines inline observability configuration for the proxy. Deprecated: Use TelemetryConfigRef to reference a shared MCPTelemetryConfig resource instead. This field will be removed in a future release. Setting both telemetry and telemetryConfigRef is rejected by CEL validation.		Optional: {}
resources api.v1alpha1.ResourceRequirements	Resources defines the resource requirements for the proxy container		Optional: {}
serviceAccount string	ServiceAccount is the name of an already existing service account to use by the proxy. If not specified, a ServiceAccount will be created automatically and used by the proxy.		Optional: {}
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	Optional: {}
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.		Optional: {}
resourceOverrides api.v1alpha1.ResourceOverrides	ResourceOverrides allows overriding annotations and labels for resources created by the operator		Optional: {}
groupRef api.v1alpha1.MCPGroupRef	GroupRef references the MCPGroup this proxy belongs to. The referenced MCPGroup must be in the same namespace.		Optional: {}
sessionAffinity string	SessionAffinity controls whether the Service routes repeated client connections to the same pod. MCP protocols (SSE, streamable-http) are stateful, so ClientIP is the default. Set to "None" for stateless servers or when using an external load balancer with its own affinity.	ClientIP	Enum: [ClientIP None] Optional: {}

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] Optional: {}
url string	URL is the internal cluster URL where the proxy can be accessed		Optional: {}
externalUrl string	ExternalURL is the external URL where the proxy can be accessed (if exposed externally)		Optional: {}
observedGeneration integer	ObservedGeneration reflects the generation of the most recently observed MCPRemoteProxy		Optional: {}
conditions Condition array	Conditions represent the latest available observations of the MCPRemoteProxy's state		Optional: {}
toolConfigHash string	ToolConfigHash stores the hash of the referenced ToolConfig for change detection		Optional: {}
telemetryConfigHash string	TelemetryConfigHash stores the hash of the referenced MCPTelemetryConfig for change detection		Optional: {}
externalAuthConfigHash string	ExternalAuthConfigHash is the hash of the referenced MCPExternalAuthConfig spec		Optional: {}
authServerConfigHash string	AuthServerConfigHash is the hash of the referenced authServerRef spec, used to detect configuration changes and trigger reconciliation.		Optional: {}
oidcConfigHash string	OIDCConfigHash is the hash of the referenced MCPOIDCConfig spec for change detection		Optional: {}
message string	Message provides additional information about the current phase		Optional: {}

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		Optional: {}
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		Optional: {}
metadata ObjectMeta	Refer to Kubernetes API documentation for fields of metadata.
spec api.v1alpha1.MCPServerSpec
status api.v1alpha1.MCPServerStatus

api.v1alpha1.MCPServerEntry

MCPServerEntry is the Schema for the mcpserverentries API. It declares a remote MCP server endpoint for vMCP discovery and routing without deploying any infrastructure.

Appears in:

• api.v1alpha1.MCPServerEntryList

Field	Description	Default	Validation
apiVersion string	toolhive.stacklok.dev/v1alpha1
kind string	MCPServerEntry
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		Optional: {}
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		Optional: {}
metadata ObjectMeta	Refer to Kubernetes API documentation for fields of metadata.
spec api.v1alpha1.MCPServerEntrySpec
status api.v1alpha1.MCPServerEntryStatus

api.v1alpha1.MCPServerEntryList

MCPServerEntryList contains a list of MCPServerEntry.

Field	Description	Default	Validation
apiVersion string	toolhive.stacklok.dev/v1alpha1
kind string	MCPServerEntryList
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		Optional: {}
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		Optional: {}
metadata ListMeta	Refer to Kubernetes API documentation for fields of metadata.
items api.v1alpha1.MCPServerEntry array

api.v1alpha1.MCPServerEntryPhase

Underlying type: string

MCPServerEntryPhase represents the lifecycle phase of an MCPServerEntry.

Validation:

• Enum: [Valid Pending Failed]

Appears in:

• api.v1alpha1.MCPServerEntryStatus

Field	Description
Valid	MCPServerEntryPhaseValid indicates all validations passed and the entry is usable.
Pending	MCPServerEntryPhasePending is the initial state before the first reconciliation.
Failed	MCPServerEntryPhaseFailed indicates one or more referenced resources are missing or invalid.

api.v1alpha1.MCPServerEntrySpec

MCPServerEntrySpec defines the desired state of MCPServerEntry. MCPServerEntry is a zero-infrastructure catalog entry that declares a remote MCP server endpoint. Unlike MCPRemoteProxy, it creates no pods, services, or deployments.

Appears in:

• api.v1alpha1.MCPServerEntry

Field	Description	Default	Validation
remoteUrl string	RemoteURL is the URL of the remote MCP server. Both HTTP and HTTPS schemes are accepted at admission time.		Pattern: ^https?:// Required: {}
transport string	Transport is the transport method for the remote server (sse or streamable-http). No default is set (unlike MCPRemoteProxy) because MCPServerEntry points at external servers the user doesn't control — requiring explicit transport avoids silent mismatches.		Enum: [sse streamable-http] Required: {}
groupRef api.v1alpha1.MCPGroupRef	GroupRef references the MCPGroup this entry belongs to. Required — every MCPServerEntry must be part of a group for vMCP discovery.		Required: {}
externalAuthConfigRef api.v1alpha1.ExternalAuthConfigRef	ExternalAuthConfigRef references a MCPExternalAuthConfig resource for token exchange when connecting to the remote MCP server. The referenced MCPExternalAuthConfig must exist in the same namespace as this MCPServerEntry.		Optional: {}
headerForward api.v1alpha1.HeaderForwardConfig	HeaderForward configures headers to inject into requests to the remote MCP server. Use this to add custom headers like API keys or correlation IDs.		Optional: {}
caBundleRef api.v1alpha1.CABundleSource	CABundleRef references a ConfigMap containing CA certificates for TLS verification when connecting to the remote MCP server.		Optional: {}

api.v1alpha1.MCPServerEntryStatus

MCPServerEntryStatus defines the observed state of MCPServerEntry.

Appears in:

• api.v1alpha1.MCPServerEntry

Field	Description	Default	Validation
observedGeneration integer	ObservedGeneration reflects the generation most recently observed by the controller.		Optional: {}
phase api.v1alpha1.MCPServerEntryPhase	Phase indicates the current lifecycle phase of the MCPServerEntry.	Pending	Enum: [Valid Pending Failed] Optional: {}
conditions Condition array	Conditions represent the latest available observations of the MCPServerEntry's state.		Optional: {}

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		Optional: {}
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		Optional: {}
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 Ready Failed Terminating Stopped]

Appears in:

• api.v1alpha1.MCPServerStatus

Field	Description
Pending	MCPServerPhasePending means the MCPServer is being created
Ready	MCPServerPhaseReady means the MCPServer is ready
Failed	MCPServerPhaseFailed means the MCPServer failed to start
Terminating	MCPServerPhaseTerminating means the MCPServer is being deleted
Stopped	MCPServerPhaseStopped means the MCPServer is scaled to zero

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 applicable when Transport is "stdio". For direct transports (sse, streamable-http), this field is ignored. The default value is applied by Kubernetes but will be ignored for non-stdio transports.	streamable-http	Enum: [sse streamable-http] Optional: {}
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 Optional: {}
args string array	Args are additional arguments to pass to the MCP server		Optional: {}
env api.v1alpha1.EnvVar array	Env are environment variables to set in the MCP server container		Optional: {}
volumes api.v1alpha1.Volume array	Volumes are volumes to mount in the MCP server container		Optional: {}
resources api.v1alpha1.ResourceRequirements	Resources defines the resource requirements for the MCP server container		Optional: {}
secrets api.v1alpha1.SecretRef array	Secrets are references to secrets to mount in the MCP server container		Optional: {}
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.		Optional: {}
permissionProfile api.v1alpha1.PermissionProfileRef	PermissionProfile defines the permission profile to use		Optional: {}
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 Optional: {}
resourceOverrides api.v1alpha1.ResourceOverrides	ResourceOverrides allows overriding annotations and labels for resources created by the operator		Optional: {}
oidcConfig api.v1alpha1.OIDCConfigRef	OIDCConfig defines OIDC authentication configuration for the MCP server. Deprecated: Use OIDCConfigRef to reference a shared MCPOIDCConfig resource instead. This field will be removed in v1beta1. OIDCConfig and OIDCConfigRef are mutually exclusive.		Optional: {}
oidcConfigRef api.v1alpha1.MCPOIDCConfigReference	OIDCConfigRef references a shared MCPOIDCConfig resource for OIDC authentication. The referenced MCPOIDCConfig must exist in the same namespace as this MCPServer. Per-server overrides (audience, scopes) are specified here; shared provider config lives in the MCPOIDCConfig resource. Mutually exclusive with oidcConfig.		Optional: {}
authzConfig api.v1alpha1.AuthzConfigRef	AuthzConfig defines authorization policy configuration for the MCP server		Optional: {}
audit api.v1alpha1.AuditConfig	Audit defines audit logging configuration for the MCP server		Optional: {}
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.		Optional: {}
externalAuthConfigRef api.v1alpha1.ExternalAuthConfigRef	ExternalAuthConfigRef references a MCPExternalAuthConfig resource for external authentication. The referenced MCPExternalAuthConfig must exist in the same namespace as this MCPServer.		Optional: {}
authServerRef api.v1alpha1.AuthServerRef	AuthServerRef optionally references a resource that configures an embedded OAuth 2.0/OIDC authorization server to authenticate MCP clients. Currently the only supported kind is MCPExternalAuthConfig (type: embeddedAuthServer).		Optional: {}
telemetryConfigRef api.v1alpha1.MCPTelemetryConfigReference	TelemetryConfigRef references an MCPTelemetryConfig resource for shared telemetry configuration. The referenced MCPTelemetryConfig must exist in the same namespace as this MCPServer. Cross-namespace references are not supported for security and isolation reasons. Mutually exclusive with the deprecated inline Telemetry field.		Optional: {}
telemetry api.v1alpha1.TelemetryConfig	Telemetry defines inline observability configuration for the MCP server. Deprecated: Use TelemetryConfigRef to reference a shared MCPTelemetryConfig resource instead. This field will be removed in a future release. Setting both telemetry and telemetryConfigRef is rejected by CEL validation.		Optional: {}
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	Optional: {}
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.		Optional: {}
groupRef api.v1alpha1.MCPGroupRef	GroupRef references the MCPGroup this server belongs to. The referenced MCPGroup must be in the same namespace.		Optional: {}
sessionAffinity string	SessionAffinity controls whether the Service routes repeated client connections to the same pod. MCP protocols (SSE, streamable-http) are stateful, so ClientIP is the default. Set to "None" for stateless servers or when using an external load balancer with its own affinity.	ClientIP	Enum: [ClientIP None] Optional: {}
replicas integer	Replicas is the desired number of proxy runner (thv run) pod replicas. MCPServer creates two separate Deployments: one for the proxy runner and one for the MCP server backend. This field controls the proxy runner Deployment. When nil, the operator does not set Deployment.Spec.Replicas, leaving replica management to an HPA or other external controller.		Minimum: 0 Optional: {}
backendReplicas integer	BackendReplicas is the desired number of MCP server backend pod replicas. This controls the backend Deployment (the MCP server container itself), independent of the proxy runner controlled by Replicas. When nil, the operator does not set Deployment.Spec.Replicas, leaving replica management to an HPA or other external controller.		Minimum: 0 Optional: {}
sessionStorage api.v1alpha1.SessionStorageConfig	SessionStorage configures session storage for stateful horizontal scaling. When nil, no session storage is configured.		Optional: {}
rateLimiting api.v1alpha1.RateLimitConfig	RateLimiting defines rate limiting configuration for the MCP server. Requires Redis session storage to be configured for distributed rate limiting.		Optional: {}

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		Optional: {}
observedGeneration integer	ObservedGeneration reflects the generation most recently observed by the controller		Optional: {}
toolConfigHash string	ToolConfigHash stores the hash of the referenced ToolConfig for change detection		Optional: {}
externalAuthConfigHash string	ExternalAuthConfigHash is the hash of the referenced MCPExternalAuthConfig spec		Optional: {}
authServerConfigHash string	AuthServerConfigHash is the hash of the referenced authServerRef spec, used to detect configuration changes and trigger reconciliation.		Optional: {}
oidcConfigHash string	OIDCConfigHash is the hash of the referenced MCPOIDCConfig spec for change detection		Optional: {}
telemetryConfigHash string	TelemetryConfigHash is the hash of the referenced MCPTelemetryConfig spec for change detection		Optional: {}
url string	URL is the URL where the MCP server can be accessed		Optional: {}
phase api.v1alpha1.MCPServerPhase	Phase is the current phase of the MCPServer		Enum: [Pending Ready Failed Terminating Stopped] Optional: {}
message string	Message provides additional information about the current phase		Optional: {}
readyReplicas integer	ReadyReplicas is the number of ready proxy replicas		Optional: {}

api.v1alpha1.MCPTelemetryConfig

MCPTelemetryConfig is the Schema for the mcptelemetryconfigs API. MCPTelemetryConfig 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.MCPTelemetryConfigList

Field	Description	Default	Validation
apiVersion string	toolhive.stacklok.dev/v1alpha1
kind string	MCPTelemetryConfig
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		Optional: {}
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		Optional: {}
metadata ObjectMeta	Refer to Kubernetes API documentation for fields of metadata.
spec api.v1alpha1.MCPTelemetryConfigSpec
status api.v1alpha1.MCPTelemetryConfigStatus

api.v1alpha1.MCPTelemetryConfigList

MCPTelemetryConfigList contains a list of MCPTelemetryConfig

Field	Description	Default	Validation
apiVersion string	toolhive.stacklok.dev/v1alpha1
kind string	MCPTelemetryConfigList
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		Optional: {}
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		Optional: {}
metadata ListMeta	Refer to Kubernetes API documentation for fields of metadata.
items api.v1alpha1.MCPTelemetryConfig array

api.v1alpha1.MCPTelemetryConfigReference

MCPTelemetryConfigReference is a reference to an MCPTelemetryConfig resource with per-server overrides. The referenced MCPTelemetryConfig must be in the same namespace as the MCPServer.

Appears in:

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

Field	Description	Default	Validation
name string	Name is the name of the MCPTelemetryConfig resource		MinLength: 1 Required: {}
serviceName string	ServiceName overrides the telemetry service name for this specific server. This MUST be unique per server for proper observability (e.g., distinguishing traces and metrics from different servers sharing the same collector). If empty, defaults to the server name with "thv-" prefix at runtime.		Optional: {}

api.v1alpha1.MCPTelemetryConfigSpec

MCPTelemetryConfigSpec defines the desired state of MCPTelemetryConfig. The spec uses a nested structure with openTelemetry and prometheus sub-objects for clear separation of concerns.

Appears in:

• api.v1alpha1.MCPTelemetryConfig

Field	Description	Default	Validation
openTelemetry api.v1alpha1.MCPTelemetryOTelConfig	OpenTelemetry defines OpenTelemetry configuration (OTLP endpoint, tracing, metrics)		Optional: {}
prometheus api.v1alpha1.PrometheusConfig	Prometheus defines Prometheus-specific configuration		Optional: {}

api.v1alpha1.MCPTelemetryConfigStatus

MCPTelemetryConfigStatus defines the observed state of MCPTelemetryConfig

Appears in:

• api.v1alpha1.MCPTelemetryConfig

Field	Description	Default	Validation
conditions Condition array	Conditions represent the latest available observations of the MCPTelemetryConfig's state		Optional: {}
observedGeneration integer	ObservedGeneration is the most recent generation observed for this MCPTelemetryConfig.		Optional: {}
configHash string	ConfigHash is a hash of the current configuration for change detection		Optional: {}
referencingWorkloads api.v1alpha1.WorkloadReference array	ReferencingWorkloads lists workloads that reference this MCPTelemetryConfig		Optional: {}

api.v1alpha1.MCPTelemetryOTelConfig

MCPTelemetryOTelConfig defines OpenTelemetry configuration for shared MCPTelemetryConfig resources. Unlike OpenTelemetryConfig (used by inline MCPServer telemetry), this type:

• Omits ServiceName (per-server field set via MCPTelemetryConfigReference)
• Uses map[string]string for Headers (not []string)
• Adds SensitiveHeaders for Kubernetes Secret-backed credentials
• Adds ResourceAttributes for shared OTel resource attributes

Appears in:

• api.v1alpha1.MCPTelemetryConfigSpec

Field	Description	Default	Validation
enabled boolean	Enabled controls whether OpenTelemetry is enabled	false	Optional: {}
endpoint string	Endpoint is the OTLP endpoint URL for tracing and metrics		Optional: {}
insecure boolean	Insecure indicates whether to use HTTP instead of HTTPS for the OTLP endpoint	false	Optional: {}
headers object (keys:string, values:string)	Headers contains authentication headers for the OTLP endpoint. For secret-backed credentials, use sensitiveHeaders instead.		Optional: {}
sensitiveHeaders api.v1alpha1.SensitiveHeader array	SensitiveHeaders contains headers whose values are stored in Kubernetes Secrets. Use this for credential headers (e.g., API keys, bearer tokens) instead of embedding secrets in the headers field.		Optional: {}
resourceAttributes object (keys:string, values:string)	ResourceAttributes contains custom resource attributes to be added to all telemetry signals. These become OTel resource attributes (e.g., deployment.environment, service.namespace). Note: service.name is intentionally excluded — it is set per-server via MCPTelemetryConfigReference.ServiceName.		Optional: {}
metrics api.v1alpha1.OpenTelemetryMetricsConfig	Metrics defines OpenTelemetry metrics-specific configuration		Optional: {}
tracing api.v1alpha1.OpenTelemetryTracingConfig	Tracing defines OpenTelemetry tracing configuration		Optional: {}
useLegacyAttributes boolean	UseLegacyAttributes controls whether legacy attribute names are emitted alongside the new MCP OTEL semantic convention names. Defaults to true for backward compatibility. This will change to false in a future release and eventually be removed.	true	Optional: {}
caBundleRef api.v1alpha1.CABundleSource	CABundleRef references a ConfigMap containing a CA certificate bundle for the OTLP endpoint. When specified, the operator mounts the ConfigMap into the proxyrunner pod and configures the OTLP exporters to trust the custom CA. This is useful when the OTLP collector uses TLS with certificates signed by an internal or private CA.		Optional: {}

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		Optional: {}
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		Optional: {}
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		Optional: {}
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		Optional: {}
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.		Optional: {}
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.		Optional: {}

api.v1alpha1.MCPToolConfigStatus

MCPToolConfigStatus defines the observed state of MCPToolConfig

Appears in:

• api.v1alpha1.MCPToolConfig

Field	Description	Default	Validation
conditions Condition array	Conditions represent the latest available observations of the MCPToolConfig's state		Optional: {}
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.		Optional: {}
configHash string	ConfigHash is a hash of the current configuration for change detection		Optional: {}
referencingWorkloads api.v1alpha1.WorkloadReference array	ReferencingWorkloads is a list of workload resources that reference this MCPToolConfig. Each entry identifies the workload by kind and name.		Optional: {}

api.v1alpha1.ModelCacheConfig

ModelCacheConfig configures persistent storage for model caching

Appears in:

• api.v1alpha1.EmbeddingServerSpec

Field	Description	Default	Validation
enabled boolean	Enabled controls whether model caching is enabled	true	Optional: {}
storageClassName string	StorageClassName is the storage class to use for the PVC If not specified, uses the cluster's default storage class		Optional: {}
size string	Size is the size of the PVC for model caching (e.g., "10Gi")	10Gi	Optional: {}
accessMode string	AccessMode is the access mode for the PVC	ReadWriteOnce	Enum: [ReadWriteOnce ReadWriteMany ReadOnlyMany] Optional: {}

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		Optional: {}
outbound api.v1alpha1.OutboundNetworkPermissions	Outbound defines the outbound network permissions		Optional: {}

api.v1alpha1.OAuth2UpstreamConfig

OAuth2UpstreamConfig contains configuration for pure OAuth 2.0 providers. OAuth 2.0 providers require explicit endpoint configuration.

Appears in:

• api.v1alpha1.UpstreamProviderConfig

Field	Description	Default	Validation
authorizationEndpoint string	AuthorizationEndpoint is the URL for the OAuth authorization endpoint.		Pattern: ^https?://.*$ Required: {}
tokenEndpoint string	TokenEndpoint is the URL for the OAuth token endpoint.		Pattern: ^https?://.*$ Required: {}
userInfo api.v1alpha1.UserInfoConfig	UserInfo contains configuration for fetching user information from the upstream provider. Required for OAuth2 providers to resolve user identity.		Required: {}
clientId string	ClientID is the OAuth 2.0 client identifier registered with the upstream IDP.		Required: {}
clientSecretRef api.v1alpha1.SecretKeyRef	ClientSecretRef references a Kubernetes Secret containing the OAuth 2.0 client secret. Optional for public clients using PKCE instead of client secret.		Optional: {}
redirectUri string	RedirectURI is the callback URL where the upstream IDP will redirect after authentication. When not specified, defaults to \{resourceUrl\}/oauth/callback where resourceUrl is the URL associated with the resource (e.g., MCPServer or vMCP) using this config.		Optional: {}
scopes string array	Scopes are the OAuth scopes to request from the upstream IDP.		Optional: {}
tokenResponseMapping api.v1alpha1.TokenResponseMapping	TokenResponseMapping configures custom field extraction from non-standard token responses. Some OAuth providers (e.g., GovSlack) nest token fields under non-standard paths instead of returning them at the top level. When set, ToolHive performs the token exchange HTTP call directly and extracts fields using the configured dot-notation paths. If nil, standard OAuth 2.0 token response parsing is used.		Optional: {}

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		Optional: {}
kubernetes api.v1alpha1.KubernetesOIDCConfig	Kubernetes configures OIDC for Kubernetes service account token validation Only used when Type is "kubernetes"		Optional: {}
configMap api.v1alpha1.ConfigMapOIDCRef	ConfigMap references a ConfigMap containing OIDC configuration Only used when Type is "configmap"		Optional: {}
inline api.v1alpha1.InlineOIDCConfig	Inline contains direct OIDC configuration Only used when Type is "inline"		Optional: {}

api.v1alpha1.OIDCUpstreamConfig

OIDCUpstreamConfig contains configuration for OIDC providers. OIDC providers support automatic endpoint discovery via the issuer URL.

Appears in:

• api.v1alpha1.UpstreamProviderConfig

Field	Description	Default	Validation
issuerUrl string	IssuerURL is the OIDC issuer URL for automatic endpoint discovery. Must be a valid HTTPS URL.		Pattern: ^https://.*$ Required: {}
clientId string	ClientID is the OAuth 2.0 client identifier registered with the upstream IDP.		Required: {}
clientSecretRef api.v1alpha1.SecretKeyRef	ClientSecretRef references a Kubernetes Secret containing the OAuth 2.0 client secret. Optional for public clients using PKCE instead of client secret.		Optional: {}
redirectUri string	RedirectURI is the callback URL where the upstream IDP will redirect after authentication. When not specified, defaults to \{resourceUrl\}/oauth/callback where resourceUrl is the URL associated with the resource (e.g., MCPServer or vMCP) using this config.		Optional: {}
scopes string array	Scopes are the OAuth scopes to request from the upstream IDP. If not specified, defaults to ["openid", "offline_access"].		Optional: {}
userInfoOverride api.v1alpha1.UserInfoConfig	UserInfoOverride allows customizing UserInfo fetching behavior for OIDC providers. By default, the UserInfo endpoint is discovered automatically via OIDC discovery. Use this to override the endpoint URL, HTTP method, or field mappings for providers that return non-standard claim names in their UserInfo response.		Optional: {}

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	Optional: {}
endpoint string	Endpoint is the OTLP endpoint URL for tracing and metrics		Optional: {}
serviceName string	ServiceName is the service name for telemetry If not specified, defaults to the MCPServer name		Optional: {}
headers string array	Headers contains authentication headers for the OTLP endpoint Specified as key=value pairs		Optional: {}
insecure boolean	Insecure indicates whether to use HTTP instead of HTTPS for the OTLP endpoint	false	Optional: {}
metrics api.v1alpha1.OpenTelemetryMetricsConfig	Metrics defines OpenTelemetry metrics-specific configuration		Optional: {}
tracing api.v1alpha1.OpenTelemetryTracingConfig	Tracing defines OpenTelemetry tracing configuration		Optional: {}
useLegacyAttributes boolean	UseLegacyAttributes controls whether legacy attribute names are emitted alongside the new MCP OTEL semantic convention names. Defaults to true for backward compatibility. This will change to false in a future release and eventually be removed.	true	Optional: {}

api.v1alpha1.OpenTelemetryMetricsConfig

OpenTelemetryMetricsConfig defines OpenTelemetry metrics configuration

Appears in:

• api.v1alpha1.MCPTelemetryOTelConfig
• api.v1alpha1.OpenTelemetryConfig

Field	Description	Default	Validation
enabled boolean	Enabled controls whether OTLP metrics are sent	false	Optional: {}

api.v1alpha1.OpenTelemetryTracingConfig

OpenTelemetryTracingConfig defines OpenTelemetry tracing configuration

Appears in:

• api.v1alpha1.MCPTelemetryOTelConfig
• api.v1alpha1.OpenTelemetryConfig

Field	Description	Default	Validation
enabled boolean	Enabled controls whether OTLP tracing is sent	false	Optional: {}
samplingRate string	SamplingRate is the trace sampling rate (0.0-1.0)	0.05	Pattern: ^(0(\.\d+)?|1(\.0+)?)$ Optional: {}

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	Optional: {}
allowHost string array	AllowHost is a list of hosts to allow connections to		Optional: {}
allowPort integer array	AllowPort is a list of ports to allow connections to		Optional: {}

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] Optional: {}
default api.v1alpha1.BackendAuthConfig	Default defines default behavior for backends without explicit auth config		Optional: {}
backends object (keys:string, values:api.v1alpha1.BackendAuthConfig)	Backends defines per-backend authentication overrides Works in all modes (discovered, inline)		Optional: {}

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"		Optional: {}

api.v1alpha1.PrometheusConfig

PrometheusConfig defines Prometheus-specific configuration

Appears in:

• api.v1alpha1.MCPTelemetryConfigSpec
• api.v1alpha1.TelemetryConfig

Field	Description	Default	Validation
enabled boolean	Enabled controls whether Prometheus metrics endpoint is exposed	false	Optional: {}

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		Optional: {}
labels object (keys:string, values:string)	Labels to add or override on the resource		Optional: {}
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		Optional: {}
imagePullSecrets LocalObjectReference array	ImagePullSecrets allows specifying image pull secrets for the proxy runner These are applied to both the Deployment and the ServiceAccount		Optional: {}

api.v1alpha1.RateLimitBucket

RateLimitBucket defines a token bucket configuration with a maximum capacity and a refill period. Used by both shared (global) and per-user rate limits.

Appears in:

• api.v1alpha1.RateLimitConfig
• api.v1alpha1.ToolRateLimitConfig

Field	Description	Default	Validation
maxTokens integer	MaxTokens is the maximum number of tokens (bucket capacity). This is also the burst size: the maximum number of requests that can be served instantaneously before the bucket is depleted.		Minimum: 1 Required: {}
refillPeriod Duration	RefillPeriod is the duration to fully refill the bucket from zero to maxTokens. The effective refill rate is maxTokens / refillPeriod tokens per second. Format: Go duration string (e.g., "1m0s", "30s", "1h0m0s").		Required: {}

api.v1alpha1.RateLimitConfig

RateLimitConfig defines rate limiting configuration for an MCP server. At least one of shared, perUser, or tools must be configured.

Appears in:

• api.v1alpha1.MCPServerSpec

Field	Description	Default	Validation
shared api.v1alpha1.RateLimitBucket	Shared is a token bucket shared across all users for the entire server.		Optional: {}
perUser api.v1alpha1.RateLimitBucket	PerUser is a token bucket applied independently to each authenticated user at the server level. Requires authentication to be enabled. Each unique userID creates Redis keys that expire after 2x refillPeriod. Memory formula: unique_users_per_TTL_window * (1 + num_tools_with_per_user_limits) keys.		Optional: {}
tools api.v1alpha1.ToolRateLimitConfig array	Tools defines per-tool rate limit overrides. Each entry applies additional rate limits to calls targeting a specific tool name. A request must pass both the server-level limit and the per-tool limit.		Optional: {}

api.v1alpha1.RedisACLUserConfig

RedisACLUserConfig configures Redis ACL user authentication.

Appears in:

• api.v1alpha1.RedisStorageConfig

Field	Description	Default	Validation
usernameSecretRef api.v1alpha1.SecretKeyRef	UsernameSecretRef references a Secret containing the Redis ACL username.		Required: {}
passwordSecretRef api.v1alpha1.SecretKeyRef	PasswordSecretRef references a Secret containing the Redis ACL password.		Required: {}

api.v1alpha1.RedisSentinelConfig

RedisSentinelConfig configures Redis Sentinel connection.

Appears in:

• api.v1alpha1.RedisStorageConfig

Field	Description	Default	Validation
masterName string	MasterName is the name of the Redis master monitored by Sentinel.		Required: {}
sentinelAddrs string array	SentinelAddrs is a list of Sentinel host:port addresses. Mutually exclusive with SentinelService.		Optional: {}
sentinelService api.v1alpha1.SentinelServiceRef	SentinelService enables automatic discovery from a Kubernetes Service. Mutually exclusive with SentinelAddrs.		Optional: {}
db integer	DB is the Redis database number.	0	Optional: {}

api.v1alpha1.RedisStorageConfig

RedisStorageConfig configures Redis connection for auth server storage. Redis is deployed in Sentinel mode with ACL user authentication (the only supported configuration).

Appears in:

• api.v1alpha1.AuthServerStorageConfig

Field	Description	Default	Validation
sentinelConfig api.v1alpha1.RedisSentinelConfig	SentinelConfig holds Redis Sentinel configuration.		Required: {}
aclUserConfig api.v1alpha1.RedisACLUserConfig	ACLUserConfig configures Redis ACL user authentication.		Required: {}
dialTimeout string	DialTimeout is the timeout for establishing connections. Format: Go duration string (e.g., "5s", "1m").	5s	Pattern: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$ Optional: {}
readTimeout string	ReadTimeout is the timeout for socket reads. Format: Go duration string (e.g., "3s", "1m").	3s	Pattern: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$ Optional: {}
writeTimeout string	WriteTimeout is the timeout for socket writes. Format: Go duration string (e.g., "3s", "1m").	3s	Pattern: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$ Optional: {}
tls api.v1alpha1.RedisTLSConfig	TLS configures TLS for connections to the Redis/Valkey master. Presence of this field enables TLS. Omit to use plaintext.		Optional: {}
sentinelTls api.v1alpha1.RedisTLSConfig	SentinelTLS configures TLS for connections to Sentinel instances. Presence of this field enables TLS. Omit to use plaintext. When omitted, sentinel connections use plaintext (no fallback to TLS config).		Optional: {}

api.v1alpha1.RedisTLSConfig

RedisTLSConfig configures TLS for Redis connections. Presence of this struct on a connection type enables TLS for that connection.

Appears in:

• api.v1alpha1.RedisStorageConfig

Field	Description	Default	Validation
insecureSkipVerify boolean	InsecureSkipVerify skips TLS certificate verification. Use when connecting to services with self-signed certificates.		Optional: {}
caCertSecretRef api.v1alpha1.SecretKeyRef	CACertSecretRef references a Secret containing a PEM-encoded CA certificate for verifying the server. When not specified, system root CAs are used.		Optional: {}

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)		Optional: {}
memory string	Memory is the memory limit in bytes (e.g., "64Mi" for 64 megabytes)		Optional: {}

api.v1alpha1.ResourceMetadataOverrides

ResourceMetadataOverrides defines metadata overrides for a resource

Appears in:

• api.v1alpha1.EmbeddingResourceOverrides
• api.v1alpha1.EmbeddingStatefulSetOverrides
• api.v1alpha1.ProxyDeploymentOverrides
• api.v1alpha1.ResourceOverrides

Field	Description	Default	Validation
annotations object (keys:string, values:string)	Annotations to add or override on the resource		Optional: {}
labels object (keys:string, values:string)	Labels to add or override on the resource		Optional: {}

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)		Optional: {}
proxyService api.v1alpha1.ResourceMetadataOverrides	ProxyService defines overrides for the Proxy Service resource (points to the proxy deployment)		Optional: {}

api.v1alpha1.ResourceRequirements

ResourceRequirements describes the compute resource requirements

Appears in:

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

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

api.v1alpha1.RoleMapping

RoleMapping defines a rule for mapping JWT claims to IAM roles. Mappings are evaluated in priority order (lower number = higher priority), and the first matching rule determines which IAM role to assume. Exactly one of Claim or Matcher must be specified.

Appears in:

• api.v1alpha1.AWSStsConfig

Field	Description	Default	Validation
claim string	Claim is a simple claim value to match against The claim type is specified by AWSStsConfig.RoleClaim For example, if RoleClaim is "groups", this would be a group name Internally compiled to a CEL expression: "<claim_value>" in claims["<role_claim>"] Mutually exclusive with Matcher		MinLength: 1 Optional: {}
matcher string	Matcher is a CEL expression for complex matching against JWT claims The expression has access to a "claims" variable containing all JWT claims as map[string]any Examples: - "admins" in claims["groups"] - claims["sub"] == "user123" && !("act" in claims) Mutually exclusive with Claim		MinLength: 1 Optional: {}
roleArn string	RoleArn is the IAM role ARN to assume when this mapping matches		Pattern: ^arn:(aws|aws-cn|aws-us-gov):iam::\d\{12\}:role/[\w+=,.@\-_/]+$ Required: {}
priority integer	Priority determines evaluation order (lower values = higher priority) Allows fine-grained control over role selection precedence When omitted, this mapping has the lowest possible priority and configuration order acts as tie-breaker via stable sort		Minimum: 0 Optional: {}

api.v1alpha1.SecretKeyRef

SecretKeyRef is a reference to a key within a Secret

Appears in:

• api.v1alpha1.BearerTokenConfig
• api.v1alpha1.EmbeddedAuthServerConfig
• api.v1alpha1.EmbeddingServerSpec
• api.v1alpha1.HeaderFromSecret
• api.v1alpha1.HeaderInjectionConfig
• api.v1alpha1.InlineOIDCConfig
• api.v1alpha1.InlineOIDCSharedConfig
• api.v1alpha1.OAuth2UpstreamConfig
• api.v1alpha1.OIDCUpstreamConfig
• api.v1alpha1.RedisACLUserConfig
• api.v1alpha1.RedisTLSConfig
• api.v1alpha1.SensitiveHeader
• api.v1alpha1.SessionStorageConfig
• 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		Optional: {}

api.v1alpha1.SensitiveHeader

SensitiveHeader represents a header whose value is stored in a Kubernetes Secret. This allows credential headers (e.g., API keys, bearer tokens) to be securely referenced without embedding secrets inline in the MCPTelemetryConfig resource.

Appears in:

• api.v1alpha1.MCPTelemetryOTelConfig

Field	Description	Default	Validation
name string	Name is the header name (e.g., "Authorization", "X-API-Key")		MinLength: 1 Required: {}
secretKeyRef api.v1alpha1.SecretKeyRef	SecretKeyRef is a reference to a Kubernetes Secret key containing the header value		Required: {}

api.v1alpha1.SentinelServiceRef

Underlying type: [api.v1alpha1.struct{Name string "json:"name""; Namespace string "json:"namespace,omitempty""; Port int32 "json:"port,omitempty""}](#apiv1alpha1struct{name string "json:"name""; namespace string "json:"namespace,omitempty""; port int32 "json:"port,omitempty""})

SentinelServiceRef references a Kubernetes Service for Sentinel discovery.

Appears in:

• api.v1alpha1.RedisSentinelConfig

api.v1alpha1.SessionStorageConfig

SessionStorageConfig defines session storage configuration for horizontal scaling.

This is the CRD/K8s-aware surface: it uses SecretKeyRef for secret resolution. The reconciler resolves PasswordRef to a plain string and builds a session.RedisConfig (pkg/transport/session) for the actual storage backend. The operator also populates pkg/vmcp/config.SessionStorageConfig (without PasswordRef) into the vMCP ConfigMap so the vMCP process receives connection parameters at startup.

Appears in:

• api.v1alpha1.MCPServerSpec
• api.v1alpha1.VirtualMCPServerSpec

Field	Description	Default	Validation
provider string	Provider is the session storage backend type		Enum: [memory redis] Required: {}
address string	Address is the Redis server address (required when provider is redis)		MinLength: 1 Optional: {}
db integer	DB is the Redis database number	0	Minimum: 0 Optional: {}
keyPrefix string	KeyPrefix is an optional prefix for all Redis keys used by ToolHive		Optional: {}
passwordRef api.v1alpha1.SecretKeyRef	PasswordRef is a reference to a Secret key containing the Redis password		Optional: {}

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		Optional: {}
prometheus api.v1alpha1.PrometheusConfig	Prometheus defines Prometheus-specific configuration		Optional: {}

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)		Optional: {}
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)		Optional: {}
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		Optional: {}
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))?$ Optional: {}
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).		Optional: {}
subjectProviderName string	SubjectProviderName is the name of the upstream provider whose token is used as the RFC 8693 subject token instead of identity.Token when performing token exchange. When left empty and an embedded authorization server is configured on the VirtualMCPServer, the controller automatically populates this field with the first configured upstream provider name. Set it explicitly to override that default or to select a specific provider when multiple upstreams are configured.		Optional: {}

api.v1alpha1.TokenLifespanConfig

TokenLifespanConfig holds configuration for token lifetimes.

Appears in:

• api.v1alpha1.EmbeddedAuthServerConfig

Field	Description	Default	Validation
accessTokenLifespan string	AccessTokenLifespan is the duration that access tokens are valid. Format: Go duration string (e.g., "1h", "30m", "24h"). If empty, defaults to 1 hour.		Pattern: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$ Optional: {}
refreshTokenLifespan string	RefreshTokenLifespan is the duration that refresh tokens are valid. Format: Go duration string (e.g., "168h", "7d" as "168h"). If empty, defaults to 7 days (168h).		Pattern: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$ Optional: {}
authCodeLifespan string	AuthCodeLifespan is the duration that authorization codes are valid. Format: Go duration string (e.g., "10m", "5m"). If empty, defaults to 10 minutes.		Pattern: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$ Optional: {}

api.v1alpha1.TokenResponseMapping

TokenResponseMapping maps non-standard token response fields to standard OAuth 2.0 fields using dot-notation JSON paths. This supports upstream providers like GovSlack that nest the access token under paths like "authed_user.access_token".

Appears in:

• api.v1alpha1.OAuth2UpstreamConfig

Field	Description	Default	Validation
accessTokenPath string	AccessTokenPath is the dot-notation path to the access token in the response. Example: "authed_user.access_token"		MinLength: 1 Required: {}
scopePath string	ScopePath is the dot-notation path to the scope string in the response. If not specified, defaults to "scope".		Optional: {}
refreshTokenPath string	RefreshTokenPath is the dot-notation path to the refresh token in the response. If not specified, defaults to "refresh_token".		Optional: {}
expiresInPath string	ExpiresInPath is the dot-notation path to the expires_in value (in seconds). If not specified, defaults to "expires_in".		Optional: {}

api.v1alpha1.ToolAnnotationsOverride

ToolAnnotationsOverride defines overrides for tool annotation fields. All fields use pointers so nil means "don't override" while zero values (empty string, false) mean "explicitly set to this value."

Appears in:

• api.v1alpha1.ToolOverride

Field	Description	Default	Validation
title string	Title overrides the human-readable title annotation.		Optional: {}
readOnlyHint boolean	ReadOnlyHint overrides the read-only hint annotation.		Optional: {}
destructiveHint boolean	DestructiveHint overrides the destructive hint annotation.		Optional: {}
idempotentHint boolean	IdempotentHint overrides the idempotent hint annotation.		Optional: {}
openWorldHint boolean	OpenWorldHint overrides the open-world hint annotation.		Optional: {}

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		Optional: {}
description string	Description is the redefined description of the tool		Optional: {}
annotations api.v1alpha1.ToolAnnotationsOverride	Annotations overrides specific tool annotation fields. Only specified fields are overridden; others pass through from the backend.		Optional: {}

api.v1alpha1.ToolRateLimitConfig

ToolRateLimitConfig defines rate limits for a specific tool. At least one of shared or perUser must be configured.

Appears in:

• api.v1alpha1.RateLimitConfig

Field	Description	Default	Validation
name string	Name is the MCP tool name this limit applies to.		MinLength: 1 Required: {}
shared api.v1alpha1.RateLimitBucket	Shared token bucket for this specific tool.		Optional: {}
perUser api.v1alpha1.RateLimitBucket	PerUser token bucket configuration for this tool.		Optional: {}

api.v1alpha1.UpstreamInjectSpec

UpstreamInjectSpec holds configuration for upstream token injection. This strategy injects an upstream IDP access token obtained by the embedded authorization server into backend requests as the Authorization: Bearer header.

Appears in:

• api.v1alpha1.MCPExternalAuthConfigSpec

Field	Description	Default	Validation
providerName string	ProviderName is the name of the upstream IDP provider whose access token should be injected as the Authorization: Bearer header.		MinLength: 1 Required: {}

api.v1alpha1.UpstreamProviderConfig

UpstreamProviderConfig defines configuration for an upstream Identity Provider.

Appears in:

• api.v1alpha1.EmbeddedAuthServerConfig

Field	Description	Default	Validation
name string	Name uniquely identifies this upstream provider. Used for routing decisions and session binding in multi-upstream scenarios. Must be lowercase alphanumeric with hyphens (DNS-label-like).		MaxLength: 63 MinLength: 1 Pattern: ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$ Required: {}
type api.v1alpha1.UpstreamProviderType	Type specifies the provider type: "oidc" or "oauth2"		Enum: [oidc oauth2] Required: {}
oidcConfig api.v1alpha1.OIDCUpstreamConfig	OIDCConfig contains OIDC-specific configuration. Required when Type is "oidc", must be nil when Type is "oauth2".		Optional: {}
oauth2Config api.v1alpha1.OAuth2UpstreamConfig	OAuth2Config contains OAuth 2.0-specific configuration. Required when Type is "oauth2", must be nil when Type is "oidc".		Optional: {}

api.v1alpha1.UpstreamProviderType

Underlying type: string

UpstreamProviderType identifies the type of upstream Identity Provider.

Appears in:

• api.v1alpha1.UpstreamProviderConfig

Field	Description
oidc	UpstreamProviderTypeOIDC is for OIDC providers with discovery support
oauth2	UpstreamProviderTypeOAuth2 is for pure OAuth 2.0 providers with explicit endpoints

api.v1alpha1.UserInfoConfig

UserInfoConfig contains configuration for fetching user information from an upstream provider. This supports both standard OIDC UserInfo endpoints and custom provider-specific endpoints like GitHub's /user API.

Appears in:

• api.v1alpha1.OAuth2UpstreamConfig
• api.v1alpha1.OIDCUpstreamConfig

Field	Description	Default	Validation
endpointUrl string	EndpointURL is the URL of the userinfo endpoint.		Pattern: ^https?://.*$ Required: {}
httpMethod string	HTTPMethod is the HTTP method to use for the userinfo request. If not specified, defaults to GET.		Enum: [GET POST] Optional: {}
additionalHeaders object (keys:string, values:string)	AdditionalHeaders contains extra headers to include in the userinfo request. Useful for providers that require specific headers (e.g., GitHub's Accept header).		Optional: {}
fieldMapping api.v1alpha1.UserInfoFieldMapping	FieldMapping contains custom field mapping configuration for non-standard providers. If nil, standard OIDC field names are used ("sub", "name", "email").		Optional: {}

api.v1alpha1.UserInfoFieldMapping

Underlying type: [api.v1alpha1.struct{SubjectFields []string "json:"subjectFields,omitempty""; NameFields []string "json:"nameFields,omitempty""; EmailFields []string "json:"emailFields,omitempty""}](#apiv1alpha1struct{subjectfields []string "json:"subjectfields,omitempty""; namefields []string "json:"namefields,omitempty""; emailfields []string "json:"emailfields,omitempty""})

UserInfoFieldMapping maps provider-specific field names to standard UserInfo fields. This allows adapting non-standard provider responses to the canonical UserInfo structure. Each field supports an ordered list of claim names to try. The first non-empty value found will be used.

Example for GitHub:

fieldMapping:
  subjectFields: ["id", "login"]
  nameFields: ["name", "login"]
  emailFields: ["email"]

Appears in:

• api.v1alpha1.UserInfoConfig

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		Optional: {}
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		Optional: {}
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		Optional: {}
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		Optional: {}
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.		Optional: {}
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).		Optional: {}

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] Optional: {}
validationErrors string array	ValidationErrors contains validation error messages if ValidationStatus is Invalid		Optional: {}
referencingVirtualServers string array	ReferencingVirtualServers lists VirtualMCPServer resources that reference this workflow This helps track which servers need to be reconciled when this workflow changes		Optional: {}
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		Optional: {}
conditions Condition array	Conditions represent the latest available observations of the workflow's state		Optional: {}

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		Optional: {}
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		Optional: {}
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		Optional: {}
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		Optional: {}
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.		Optional: {}
serviceType string	ServiceType specifies the Kubernetes service type for the Virtual MCP server	ClusterIP	Enum: [ClusterIP NodePort LoadBalancer] Optional: {}
sessionAffinity string	SessionAffinity controls whether the Service routes repeated client connections to the same pod. MCP protocols (SSE, streamable-http) are stateful, so ClientIP is the default. Set to "None" for stateless servers or when using an external load balancer with its own affinity.	ClientIP	Enum: [ClientIP None] Optional: {}
serviceAccount string	ServiceAccount is the name of an already existing service account to use by the Virtual MCP server. If not specified, a ServiceAccount will be created automatically and used by the Virtual MCP server.		Optional: {}
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 Optional: {}
groupRef api.v1alpha1.MCPGroupRef	GroupRef references the MCPGroup that defines backend workloads. The referenced MCPGroup must exist in the same namespace. This field takes precedence over config.groupRef and should be preferred.		Optional: {}
config vmcp.config.Config	Config is the Virtual MCP server configuration. The audit config from here is also supported, but not required. Note: config.groupRef is deprecated in favor of spec.groupRef. Note: config.telemetry is deprecated — use spec.telemetryConfigRef to reference a shared MCPTelemetryConfig resource instead.		Type: object Optional: {}
telemetryConfigRef api.v1alpha1.MCPTelemetryConfigReference	TelemetryConfigRef references an MCPTelemetryConfig resource for shared telemetry configuration. The referenced MCPTelemetryConfig must exist in the same namespace as this VirtualMCPServer. Cross-namespace references are not supported for security and isolation reasons. Mutually exclusive with the deprecated inline config.telemetry field.		Optional: {}
embeddingServerRef api.v1alpha1.EmbeddingServerRef	EmbeddingServerRef references an existing EmbeddingServer resource by name. When the optimizer is enabled, this field is required to point to a ready EmbeddingServer that provides embedding capabilities. The referenced EmbeddingServer must exist in the same namespace and be ready.		Optional: {}
authServerConfig api.v1alpha1.EmbeddedAuthServerConfig	AuthServerConfig configures an embedded OAuth authorization server. When set, the vMCP server acts as an OIDC issuer, drives users through upstream IDPs, and issues ToolHive JWTs. The embedded AS becomes the IncomingAuth OIDC provider — its issuer must match IncomingAuth.OIDCConfig so that tokens it issues are accepted by the vMCP's incoming auth middleware. When nil, IncomingAuth uses an external IDP and behavior is unchanged.		Optional: {}
replicas integer	Replicas is the desired number of vMCP pod replicas. VirtualMCPServer creates a single Deployment for the vMCP aggregator process, so there is only one replicas field (unlike MCPServer which has separate Replicas and BackendReplicas for its two Deployments). When nil, the operator does not set Deployment.Spec.Replicas, leaving replica management to an HPA or other external controller.		Minimum: 0 Optional: {}
sessionStorage api.v1alpha1.SessionStorageConfig	SessionStorage configures session storage for stateful horizontal scaling. When nil, no session storage is configured.		Optional: {}

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		Optional: {}
observedGeneration integer	ObservedGeneration is the most recent generation observed for this VirtualMCPServer		Optional: {}
phase api.v1alpha1.VirtualMCPServerPhase	Phase is the current phase of the VirtualMCPServer	Pending	Enum: [Pending Ready Degraded Failed] Optional: {}
message string	Message provides additional information about the current phase		Optional: {}
url string	URL is the URL where the Virtual MCP server can be accessed		Optional: {}
discoveredBackends api.v1alpha1.DiscoveredBackend array	DiscoveredBackends lists discovered backend configurations from the MCPGroup		Optional: {}
backendCount integer	BackendCount is the number of healthy/ready backends (excludes unavailable, degraded, and unknown backends)		Optional: {}
oidcConfigHash string	OIDCConfigHash is the hash of the referenced MCPOIDCConfig spec for change detection. Only populated when IncomingAuth.OIDCConfigRef is set.		Optional: {}
telemetryConfigHash string	TelemetryConfigHash is the hash of the referenced MCPTelemetryConfig spec for change detection. Only populated when TelemetryConfigRef is set.		Optional: {}

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	Optional: {}

api.v1alpha1.WorkloadReference

WorkloadReference identifies a workload that references a shared configuration resource. Namespace is implicit — cross-namespace references are not supported.

Appears in:

• api.v1alpha1.MCPExternalAuthConfigStatus
• api.v1alpha1.MCPOIDCConfigStatus
• api.v1alpha1.MCPTelemetryConfigStatus
• api.v1alpha1.MCPToolConfigStatus

Field	Description	Default	Validation
kind string	Kind is the type of workload resource		Enum: [MCPServer VirtualMCPServer MCPRemoteProxy] Required: {}
name string	Name is the name of the workload resource		MinLength: 1 Required: {}