Skip to content

crd-api.md

Latest commit

 

History

History
3811 lines (2157 loc) · 244 KB

crd-api.md

File metadata and controls

3811 lines (2157 loc) · 244 KB
Raw

API Reference

Packages

toolhive.stacklok.dev/audit

pkg.audit.Config

Config represents the audit logging configuration.

Appears in:

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: {}
detectApplicationErrors boolean DetectApplicationErrors controls whether the audit middleware inspects
JSON-RPC response bodies for application-level errors when the HTTP
status code indicates success (2xx). When enabled, a small prefix of
the response body is buffered to detect JSON-RPC error fields,
independent of the IncludeResponseData setting.		 true 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.AwsStsConfig

AwsStsConfig configures AWS STS authentication with SigV4 request signing. This strategy exchanges incoming tokens for AWS STS temporary credentials.

Appears in:

Field Description Default Validation
region string Region is the AWS region for the STS endpoint and service.
service string Service is the AWS service name for SigV4 signing.
fallbackRoleArn string FallbackRoleArn is the IAM role ARN to assume when no role mappings match.
roleMappings auth.types.RoleMapping array RoleMappings defines claim-based role selection rules.
roleClaim string RoleClaim is the JWT claim to use for role mapping evaluation.
sessionDuration integer SessionDuration is the duration in seconds for the STS session.
sessionNameClaim string SessionNameClaim is the JWT claim to use for the role session name.
subjectProviderName string SubjectProviderName selects which upstream provider's token to use as the
web identity token for AssumeRoleWithWebIdentity. When set, the token is
looked up from Identity.UpstreamTokens instead of the request's
Authorization header.

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:

Field Description Default Validation
type string Type is the auth strategy: "unauthenticated", "header_injection", "token_exchange", "upstream_inject", "aws_sts", "obo"
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".
awsSts auth.types.AwsStsConfig AwsSts contains configuration for AWS STS auth strategy.
Used when Type = "aws_sts".

auth.types.HeaderInjectionConfig

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

Appears in:

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.RoleMapping

RoleMapping defines a rule for mapping JWT claims to IAM roles. Mappings are evaluated in priority order (lower number = higher priority).

Appears in:

Field Description Default Validation
claim string Claim is a simple claim value to match against the RoleClaim field.
matcher string Matcher is a CEL expression for complex matching against JWT claims.
roleArn string RoleArn is the IAM role ARN to assume when this mapping matches.
priority integer Priority determines evaluation order (lower values = higher priority).
Mirrors awssts.RoleMapping.Priority, which is *int because the role mapper
uses math.MaxInt for nil-priority semantics in effectivePriority.

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:

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:

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:

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:

Field Description Default Validation
type string Type is the authz type: "cedar", "none"
policies string array Policies contains Cedar policy definitions (when Type = "cedar").
entitiesJson string EntitiesJSON is a JSON string representing Cedar entities. Required for
enterprise policies that rely on transitive relationships (e.g.
ClaimGroup → PlatformRole) — without it the Cedar authorizer is
constructed with an empty entity store and in checks against absent
entities silently evaluate to false. Defaults to "[]" when empty.		 Optional: {}
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: {}
groupClaimName string GroupClaimName is the JWT claim key that contains group membership for
the principal. When set, takes priority over the well-known defaults
("groups", "roles", "cognito:groups"). Use this for IDPs that place
groups under a URI-style claim (e.g. "https://example.com/groups").
When empty, only the well-known claim names are checked.		 Optional: {}
roleClaimName string RoleClaimName is the JWT claim key that contains role membership for the
principal. When set, the claim is extracted separately from GroupClaimName
and both are mapped to the configured group entity type. When empty, no
role extraction is performed.		 Optional: {}
groupEntityType string GroupEntityType is the Cedar entity type name used for principal parent
UIDs synthesised from JWT group/role claims. Defaults to "THVGroup" when
empty. Must match the entity type used in EntitiesJSON for transitive
in checks to resolve. Namespaced names (Foo::Bar) are not yet supported.		 Optional: {}

vmcp.config.CircuitBreakerConfig

CircuitBreakerConfig configures circuit breaker behavior.

Appears in:

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:

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:

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:

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 standalone CLI mode, this is set from the YAML config file.
In Kubernetes, the operator populates this from spec.groupRef during conversion.		 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: {}
rateLimiting ratelimit.types.RateLimitConfig RateLimiting defines rate limiting configuration for the Virtual MCP server.
Requires Redis session storage to be configured for distributed rate limiting.		 Optional: {}

vmcp.config.ConflictResolutionConfig

ConflictResolutionConfig provides configuration for conflict resolution strategies.

Appears in:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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.ToolConfigRef

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

Appears in:

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:

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:

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:

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/ratelimit

ratelimit.types.RateLimitBucket

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

Appears in:

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

ratelimit.types.RateLimitConfig

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

Appears in:

Field Description Default Validation
shared ratelimit.types.RateLimitBucket Shared is a token bucket shared across all users for the entire server. Optional: {}
perUser ratelimit.types.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 ratelimit.types.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: {}

ratelimit.types.ToolRateLimitConfig

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

Appears in:

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

toolhive.stacklok.dev/telemetry

pkg.telemetry.Config

Config holds the configuration for OpenTelemetry instrumentation.

Appears in:

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

toolhive.stacklok.dev/v1beta1

Resource Types

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

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.v1beta1.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: {}
subjectProviderName string SubjectProviderName is the name of the upstream provider whose access token
is used as the web identity token for STS AssumeRoleWithWebIdentity.
This field is used exclusively by VirtualMCPServer, where there is no
upstream swap middleware to replace the bearer token before the strategy runs.
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.
When no embedded auth server is present, the bearer token from the incoming
request's Authorization header is used instead.		 Optional: {}

api.v1beta1.AuditConfig

AuditConfig defines audit logging configuration for the MCP server

Appears in:

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

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

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.v1beta1.AuthServerStorageConfig

AuthServerStorageConfig configures the storage backend for the embedded auth server.

Appears in:

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

api.v1beta1.AuthServerStorageType

Underlying type: string

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

Appears in:

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

api.v1beta1.AuthzConfigRef

AuthzConfigRef defines a reference to authorization configuration

Appears in:

Field Description Default Validation
type string Type is the type of authorization configuration configMap Enum: [configMap inline]
configMap api.v1beta1.ConfigMapAuthzRef ConfigMap references a ConfigMap containing authorization configuration
Only used when Type is "configMap"		 Optional: {}
inline api.v1beta1.InlineAuthzConfig Inline contains direct authorization configuration
Only used when Type is "inline"		 Optional: {}
groupClaimName string GroupClaimName is the JWT claim key that contains group membership for the
principal. When set, takes priority over the well-known defaults
("groups", "roles", "cognito:groups"). Use this for IDPs that place
groups under a URI-style claim (e.g. "https://example.com/groups"). When
Type is "configMap", a group_claim_name entry in the referenced ConfigMap
is overridden by this field if both are set.		 MaxLength: 253
Optional: {}
roleClaimName string RoleClaimName is the JWT claim key that contains role membership for the
principal. When set, the claim is extracted separately from GroupClaimName
and both are mapped to the configured GroupEntityType. When Type is
"configMap", a role_claim_name entry in the referenced ConfigMap is
overridden by this field if both are set.		 MaxLength: 253
Optional: {}
groupEntityType string GroupEntityType is the Cedar entity type name used for principal parent
UIDs synthesised from JWT group/role claims. Defaults to "THVGroup" when
empty. Must match the entity type used in the static entity store for
transitive in checks (e.g. ClaimGroup → PlatformRole) to resolve.
Namespaced names (Foo::Bar) are not yet supported. When Type is
"configMap", a group_entity_type entry in the referenced ConfigMap is
overridden by this field if both are set.		 MaxLength: 63
Pattern: ^[A-Za-z_][A-Za-z0-9_]*$
Optional: {}

api.v1beta1.BackendAuthConfig

BackendAuthConfig defines authentication configuration for a backend MCPServer

Appears in:

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

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

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

api.v1beta1.CABundleSource

CABundleSource defines a source for CA certificate bundles.

Appears in:

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.v1beta1.ConfigMapAuthzRef

ConfigMapAuthzRef references a ConfigMap containing authorization configuration

Appears in:

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.v1beta1.DCRUpstreamConfig

DCRUpstreamConfig configures RFC 7591 Dynamic Client Registration for an OAuth 2.0 upstream. When present on an OAuth2 upstream, the authserver performs registration at runtime to obtain client credentials, replacing the need to pre-provision a ClientID.

Exactly one of DiscoveryURL or RegistrationEndpoint must be set. DiscoveryURL points at an RFC 8414 / OIDC Discovery document from which the registration endpoint is resolved; RegistrationEndpoint is used directly when the upstream does not publish discovery metadata.

The XOR rule uses has() alone (not has() + size() > 0) to keep the rule's estimated CEL cost under the apiserver's per-rule static budget. With omitempty on both fields, an unset field is absent on the wire and has() returns false; the explicit-empty-string edge case is rejected at reconcile time by ValidateOAuth2DCRConfig.

Appears in:

Field Description Default Validation
discoveryUrl string DiscoveryURL is the RFC 8414 / OIDC Discovery document URL. The resolver
issues a single GET against this URL (no well-known-path fallback) and
reads registration_endpoint, authorization_endpoint, token_endpoint,
token_endpoint_auth_methods_supported, and scopes_supported from the
response.
Mutually exclusive with RegistrationEndpoint.
HTTPS is required because the registration endpoint resolved from this
document carries the initial access token and the issued client_secret
(RFC 7591 §3, RFC 8414 §3). MaxLength is a defensive size cap (etcd
object budget, regex evaluation cost) and matches the conventional URL
length cap.		 MaxLength: 2048
Pattern: ^https://[^\s?#]+[^/\s?#]$
Optional: {}
registrationEndpoint string RegistrationEndpoint is the RFC 7591 registration endpoint URL used
directly, bypassing discovery. When using this field, the caller is
expected to also supply AuthorizationEndpoint, TokenEndpoint, and an
explicit Scopes list on the parent OAuth2UpstreamConfig.
Mutually exclusive with DiscoveryURL.
HTTPS is required because the registration endpoint carries the initial
access token and the issued client_secret (RFC 7591 §3, RFC 8414 §3).
MaxLength is a defensive size cap (etcd object budget, regex evaluation
cost) and matches the conventional URL length cap.		 MaxLength: 2048
Pattern: ^https://[^\s?#]+[^/\s?#]$
Optional: {}
initialAccessTokenRef api.v1beta1.SecretKeyRef InitialAccessTokenRef is an optional reference to a Kubernetes Secret
carrying an RFC 7591 §3 initial access token. When set, the resolver
presents the token value as a Bearer credential on the registration
request. Mirrors the ClientSecretRef pattern.		 Optional: {}
softwareId string SoftwareID is the RFC 7591 "software_id" registration metadata value,
identifying the client software independent of any particular
registration instance. Typically a UUID or short identifier.		 MaxLength: 255
Optional: {}
softwareStatement string SoftwareStatement is the RFC 7591 "software_statement" JWT asserting
metadata about the client software, signed by a party the authorization
server trusts.
Stored inline on the CR. The JWT is signed but not encrypted, so its
contents are visible to anyone with get/list/watch on this resource and
appear in etcd backups in plaintext. Treat the value as non-confidential
(signed attestation, not a secret). Operators that rotate software
statements like bearer credentials should keep them at the authorization
server side and rely on the registration endpoint's initial access
token (see InitialAccessTokenRef) instead of placing them on the CR.
Bounded to 16384 characters as a defensive size cap (etcd object
budget, regex evaluation cost). Real-world signed statements with
embedded x5c certificate chains, JWKS keys, or OIDC-Federation
trust-framework metadata routinely exceed 4 KB.		 MaxLength: 16384
Optional: {}

api.v1beta1.EmbeddedAuthServerCIMDConfig

EmbeddedAuthServerCIMDConfig configures Client ID Metadata Document (CIMD) support on the embedded authorization server. When enabled, the AS accepts HTTPS URLs as client_id values and resolves them via the CIMD protocol, allowing clients such as VS Code to authenticate without prior Dynamic Client Registration.

Appears in:

Field Description Default Validation
enabled boolean Enabled activates CIMD client lookup. When false (the default), the AS only
accepts client_id values that were registered via DCR.		 false
cacheMaxSize integer CacheMaxSize is the maximum number of CIMD documents held in the LRU cache.
Defaults to 256 when Enabled is true and this field is omitted.		 Minimum: 1
Optional: {}
cacheFallbackTtl string CacheFallbackTTL is the fixed TTL applied to every cached CIMD document.
Cache-Control header parsing is not yet implemented; all entries use this value.
Format: Go duration string (e.g. "5m", "10m", "1h").
Defaults to 5 minutes when Enabled is true and this field is omitted.		 Pattern: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
Optional: {}

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

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.v1beta1.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.v1beta1.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.v1beta1.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.v1beta1.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: {}
primaryUpstreamProvider string PrimaryUpstreamProvider names the upstream IDP whose access token Cedar
should read claims from when authorising a request. Must match the name
of one of the entries in UpstreamProviders. When empty, the controller
auto-selects the first entry of UpstreamProviders.
Only meaningful on VirtualMCPServer, where multiple upstream providers
can be configured and Cedar needs to pick which token's claims to
evaluate. The VirtualMCPServer controller validates this field against
UpstreamProviders at admission and rejects unresolvable values.
On MCPServer and MCPRemoteProxy this field is structurally present (the
EmbeddedAuthServerConfig struct is shared) but has no runtime effect:
those CRDs are restricted to a single upstream so there is no choice to
make. Setting it on those CRDs is silently ignored.		 MaxLength: 63
MinLength: 1
Pattern: ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$
Optional: {}
storage api.v1beta1.AuthServerStorageConfig Storage configures the storage backend for the embedded auth server.
If not specified, defaults to in-memory storage.		 Optional: {}
baselineClientScopes string array BaselineClientScopes is a baseline set of OAuth 2.0 scopes guaranteed to be
included in every client registration. The embedded auth server unions these
scopes into the registered set returned by RFC 7591 Dynamic Client
Registration, so a client that narrows the scope field at /oauth/register
can still request the baseline scopes at /oauth/authorize. All values must
be present in the upstream-derived scopesSupported set; the auth server
fails to start if any value is missing.
Security: every client registered via /oauth/register will gain the
ability to request these scopes at /oauth/authorize, regardless of what
the client itself requested. Keep the baseline narrow (typically
"openid" and "offline_access"). Adding a privileged scope here — e.g.
"admin:read" — would grant it to every DCR-registered client, including
public clients like Claude Code, Cursor, and VS Code.
When cimd.enabled is true, every dynamically resolved CIMD client will
also gain the ability to request these scopes, including third-party
clients resolved from arbitrary HTTPS URLs.		 MaxItems: 10
items:MinLength: 1
items:Pattern: ^[\x21\x23-\x5B\x5D-\x7E]+$
Optional: {}
cimd api.v1beta1.EmbeddedAuthServerCIMDConfig CIMD configures Client ID Metadata Document support. When omitted, CIMD is disabled. Optional: {}

api.v1beta1.EmbeddingResourceOverrides

EmbeddingResourceOverrides defines overrides for annotations and labels on created resources

Appears in:

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

api.v1beta1.EmbeddingServer

EmbeddingServer is the Schema for the embeddingservers API

Appears in:

Field Description Default Validation
apiVersion string toolhive.stacklok.dev/v1beta1
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.v1beta1.EmbeddingServerSpec
status api.v1beta1.EmbeddingServerStatus

api.v1beta1.EmbeddingServerList

EmbeddingServerList contains a list of EmbeddingServer

Field Description Default Validation
apiVersion string toolhive.stacklok.dev/v1beta1
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.v1beta1.EmbeddingServer array

api.v1beta1.EmbeddingServerPhase

Underlying type: string

EmbeddingServerPhase is the phase of the EmbeddingServer

Validation:

  • Enum: [Pending Downloading Ready Failed Terminating]

Appears in:

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.v1beta1.EmbeddingServerRef

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

Appears in:

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

api.v1beta1.EmbeddingServerSpec

EmbeddingServerSpec defines the desired state of EmbeddingServer

Appears in:

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.v1beta1.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 PullPolicy 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.v1beta1.EnvVar array Env are environment variables to set in the container Optional: {}
resources api.v1beta1.ResourceRequirements Resources defines compute resources for the embedding server Optional: {}
modelCache api.v1beta1.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.v1beta1.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.v1beta1.EmbeddingServerStatus

EmbeddingServerStatus defines the observed state of EmbeddingServer

Appears in:

Field Description Default Validation
conditions Condition array Conditions represent the latest available observations of the EmbeddingServer's state Optional: {}
phase api.v1beta1.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.v1beta1.EmbeddingStatefulSetOverrides

EmbeddingStatefulSetOverrides defines overrides specific to the embedding statefulset

Appears in:

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.v1beta1.ResourceMetadataOverrides PodTemplateMetadataOverrides defines metadata overrides for the pod template Optional: {}

api.v1beta1.EnvVar

EnvVar represents an environment variable in a container

Appears in:

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

api.v1beta1.ExternalAuthConfigRef

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

Appears in:

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

api.v1beta1.ExternalAuthType

Underlying type: string

ExternalAuthType represents the type of external authentication

Appears in:

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
obo ExternalAuthTypeOBO is the type for on-behalf-of (OBO) flows.
This type requires a build with an OBO handler registered via
controllerutil.RegisterOBOHandler; an upstream-only build surfaces
status.conditions[Valid] = False with Reason: EnterpriseRequired
when an obo-typed MCPExternalAuthConfig is applied.

api.v1beta1.HeaderForwardConfig

HeaderForwardConfig defines header forward configuration for remote servers.

Appears in:

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.v1beta1.HeaderFromSecret array AddHeadersFromSecret references Kubernetes Secrets for sensitive header values. Optional: {}

api.v1beta1.HeaderFromSecret

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

Appears in:

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

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

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

api.v1beta1.IdentityFromTokenConfig

IdentityFromTokenConfig extracts user identity (subject, name, email) directly from the OAuth2 token-endpoint response body using gjson dot-notation paths. When configured on an OAuth2UpstreamConfig, the embedded auth server skips the userinfo HTTP call entirely and resolves identity from the token response.

Paths use gjson dot-notation, where each segment is a JSON object key. For example, "username" extracts a top-level field, and "authed_user.id" extracts a nested field.

Trust-model warning: Identity claims extracted via this block are not cryptographically verified — they are trusted only via the TLS connection to the token endpoint. Prefer OIDC + ID token validation when verifiable claims are required.

Subject uniqueness is scoped to the upstream provider entry. To keep identity namespaces separate across multiple instances of the same provider (e.g., two Snowflake accounts), use distinct upstream provider entries.

Appears in:

Field Description Default Validation
subjectPath string SubjectPath is the dot-notation path to the subject (user ID) field in the token response.
Warning: claims read from the token response are trusted only via TLS, not
cryptographically verified; prefer OIDC ID tokens when verifiable claims are required.
Example: "authed_user.id" for Slack (top-level token-response field). For providers
whose token response embeds the access token as a JWT (e.g. Snowflake), use the
"@upstreamjwt" modifier to decode the payload, e.g. "access_token|@upstreamjwt|sub".
The "@upstreamjwt" modifier performs no signature verification either.		 MaxLength: 256
MinLength: 1
Required: {}
namePath string NamePath is the dot-notation path to the display name field in the token response.
If not specified or if the path does not resolve to a string, the display name is omitted.
Omit the field entirely rather than setting it to an empty string.		 MaxLength: 256
MinLength: 1
Optional: {}
emailPath string EmailPath is the dot-notation path to the email address field in the token response.
If not specified or if the path does not resolve to a string, the email is omitted.
Omit the field entirely rather than setting it to an empty string.		 MaxLength: 256
MinLength: 1
Optional: {}

api.v1beta1.IncomingAuthConfig

IncomingAuthConfig configures authentication for clients connecting to the Virtual MCP server

Appears in:

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: {}
oidcConfigRef api.v1beta1.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.		 Optional: {}
authzConfig api.v1beta1.AuthzConfigRef AuthzConfig defines authorization policy configuration
Reuses MCPServer authz patterns		 Optional: {}

api.v1beta1.InlineAuthzConfig

InlineAuthzConfig contains direct authorization configuration.

Source-agnostic Cedar JWT-claim mapping settings (GroupClaimName, RoleClaimName, GroupEntityType) live on the parent AuthzConfigRef so they work the same way for inline and configMap-sourced authz.

Appears in:

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. Required when
transitive policies (e.g. ClaimGroup → PlatformRole) need a static
entity store; defaults to "[]".		 [] Optional: {}
primaryUpstreamProvider string PrimaryUpstreamProvider names the upstream IDP whose access token's
claims Cedar should evaluate.
Deprecated: on VirtualMCPServer this field has moved to
spec.authServerConfig.primaryUpstreamProvider. The old location is
still read for one release for backward compatibility; the
VirtualMCPServer controller emits an AuthzPrimaryUpstreamProviderDeprecated
Warning event whenever it is consumed, and removal is planned for the
release after the deprecation cycle.
On MCPServer and MCPRemoteProxy this field has always been a structural
no-op (those CRDs do not run an embedded auth server). Setting it
continues to surface the AuthzPrimaryUpstreamProviderIgnored advisory
condition; the deprecation does not change that behaviour.		 MaxLength: 63
MinLength: 1
Pattern: ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$
Optional: {}

api.v1beta1.InlineOIDCSharedConfig

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

Appears in:

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.v1beta1.SecretKeyRef ClientSecretRef is a reference to a Kubernetes Secret containing the client secret Optional: {}
caBundleRef api.v1beta1.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.v1beta1.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:

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.v1beta1.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:

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

api.v1beta1.MCPExternalAuthConfigList

MCPExternalAuthConfigList contains a list of MCPExternalAuthConfig

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

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

Field Description Default Validation
type api.v1beta1.ExternalAuthType Type is the type of external authentication to configure.
When set to "obo", the cluster must run a build that has registered an
OBO handler via controllerutil.RegisterOBOHandler; upstream-only builds
surface status.conditions[Valid] = False with Reason: EnterpriseRequired
for obo-typed configs.		 Enum: [tokenExchange headerInjection bearerToken unauthenticated embeddedAuthServer awsSts upstreamInject obo]
Required: {}
tokenExchange api.v1beta1.TokenExchangeConfig TokenExchange configures RFC-8693 OAuth 2.0 Token Exchange
Only used when Type is "tokenExchange"		 Optional: {}
headerInjection api.v1beta1.HeaderInjectionConfig HeaderInjection configures custom HTTP header injection
Only used when Type is "headerInjection"		 Optional: {}
bearerToken api.v1beta1.BearerTokenConfig BearerToken configures bearer token authentication
Only used when Type is "bearerToken"		 Optional: {}
embeddedAuthServer api.v1beta1.EmbeddedAuthServerConfig EmbeddedAuthServer configures an embedded OAuth2/OIDC authorization server
Only used when Type is "embeddedAuthServer"		 Optional: {}
awsSts api.v1beta1.AWSStsConfig AWSSts configures AWS STS authentication with SigV4 request signing
Only used when Type is "awsSts"		 Optional: {}
upstreamInject api.v1beta1.UpstreamInjectSpec UpstreamInject configures upstream token injection for backend requests.
Only used when Type is "upstreamInject".		 Optional: {}
obo api.v1beta1.OBOConfig OBO configures On-Behalf-Of (OBO) authentication.
Only used when Type is "obo". The inner schema is intentionally empty in
this revision; sub-fields land in a follow-up. Setting this field on an
upstream-only build will cause the MCPExternalAuthConfig to transition to
status.conditions[Valid] = False with Reason: EnterpriseRequired.		 Optional: {}

api.v1beta1.MCPExternalAuthConfigStatus

MCPExternalAuthConfigStatus defines the observed state of MCPExternalAuthConfig

Appears in:

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: {}
referenceCount integer ReferenceCount is the number of workloads referencing this config. Optional: {}
referencingWorkloads api.v1beta1.WorkloadReference array ReferencingWorkloads is a list of workload resources that reference this MCPExternalAuthConfig.
Each entry identifies the workload by kind and name.		 Optional: {}

api.v1beta1.MCPGroup

MCPGroup is the Schema for the mcpgroups API

Appears in:

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

api.v1beta1.MCPGroupList

MCPGroupList contains a list of MCPGroup

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

api.v1beta1.MCPGroupPhase

Underlying type: string

MCPGroupPhase represents the lifecycle phase of an MCPGroup

Validation:

  • Enum: [Ready Pending Failed]

Appears in:

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

api.v1beta1.MCPGroupRef

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

Appears in:

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

api.v1beta1.MCPGroupSpec

MCPGroupSpec defines the desired state of MCPGroup

Appears in:

Field Description Default Validation
description string Description provides human-readable context Optional: {}

api.v1beta1.MCPGroupStatus

MCPGroupStatus defines observed state

Appears in:

Field Description Default Validation
observedGeneration integer ObservedGeneration reflects the generation most recently observed by the controller Optional: {}
phase api.v1beta1.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.v1beta1.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:

Field Description Default Validation
apiVersion string toolhive.stacklok.dev/v1beta1
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.v1beta1.MCPOIDCConfigSpec
status api.v1beta1.MCPOIDCConfigStatus

api.v1beta1.MCPOIDCConfigList

MCPOIDCConfigList contains a list of MCPOIDCConfig

Field Description Default Validation
apiVersion string toolhive.stacklok.dev/v1beta1
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.v1beta1.MCPOIDCConfig array

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

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: {}
resourceUrl string ResourceURL is the public URL for OAuth protected resource metadata (RFC 9728).
When the server is exposed via Ingress or gateway, set this to the external
URL that MCP clients connect to. If not specified, defaults to the internal
Kubernetes service URL.		 Optional: {}

api.v1beta1.MCPOIDCConfigSourceType

Underlying type: string

MCPOIDCConfigSourceType represents the type of OIDC configuration source for MCPOIDCConfig

Appears in:

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

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

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

api.v1beta1.MCPOIDCConfigStatus

MCPOIDCConfigStatus defines the observed state of MCPOIDCConfig

Appears in:

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: {}
referenceCount integer ReferenceCount is the number of workloads referencing this config. Optional: {}
referencingWorkloads api.v1beta1.WorkloadReference array ReferencingWorkloads is a list of workload resources that reference this MCPOIDCConfig.
Each entry identifies the workload by kind and name.		 Optional: {}

api.v1beta1.MCPRegistry

MCPRegistry is the Schema for the mcpregistries API.

The MCPRegistry CRD is deprecated and will be removed in a future release. Install the ToolHive registry server via the toolhive-registry-server Helm chart instead: https://github.com/stacklok/toolhive-registry-server

Appears in:

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

api.v1beta1.MCPRegistryList

MCPRegistryList contains a list of MCPRegistry

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

api.v1beta1.MCPRegistryPhase

Underlying type: string

MCPRegistryPhase represents the phase of the MCPRegistry

Validation:

  • Enum: [Pending Ready Failed Terminating]

Appears in:

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.v1beta1.MCPRegistrySpec

MCPRegistrySpec defines the desired state of MCPRegistry

Appears in:

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: {}
imagePullSecrets LocalObjectReference array ImagePullSecrets allows specifying image pull secrets for the registry API workload.
These are applied to both the registry-api Deployment's PodSpec.ImagePullSecrets
and to the operator-managed ServiceAccount the registry API runs as, so private
images are pullable through either path.
Use this field for new manifests.
Important: this is the ONLY way to attach image-pull credentials to the
operator-managed ServiceAccount. The legacy
spec.podTemplateSpec.spec.imagePullSecrets path populates the Deployment's pod
spec ONLY — it does NOT touch the ServiceAccount. On managed Kubernetes
platforms that rely on ServiceAccount-level credential injection (for example
GKE Workload Identity, OpenShift's per-SA dockercfg secrets, EKS IRSA), using
only the legacy PodTemplateSpec path can fail to pull private images even when
the secret exists in the namespace. Always set spec.imagePullSecrets when
SA-level credentials matter.
Precedence with PodTemplateSpec:
- This field is applied first as the controller-generated default.
- Values set under spec.podTemplateSpec.spec.imagePullSecrets are user overrides
and win on overlap. If the user supplies imagePullSecrets via PodTemplateSpec,
those replace the default list on the Deployment (the list is treated atomically).
- The ServiceAccount is always populated from this field — PodTemplateSpec does not
affect the ServiceAccount.
An omitted field and an explicitly empty list are equivalent: both leave the
ServiceAccount's existing ImagePullSecrets unchanged. This preserves
platform-managed pull secrets (for example OpenShift's per-SA dockercfg
entries) when overlays or patches emit an empty list. Truly clearing the
ServiceAccount's pull secrets requires recreating the resource.		 Optional: {}

api.v1beta1.MCPRegistryStatus

MCPRegistryStatus defines the observed state of MCPRegistry

Appears in:

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.v1beta1.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.v1beta1.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:

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

api.v1beta1.MCPRemoteProxyList

MCPRemoteProxyList contains a list of MCPRemoteProxy

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

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

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.v1beta1.MCPRemoteProxySpec

MCPRemoteProxySpec defines the desired state of MCPRemoteProxy

Appears in:

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]
oidcConfigRef api.v1beta1.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.v1beta1.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.v1beta1.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.v1beta1.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.v1beta1.AuthzConfigRef AuthzConfig defines authorization policy configuration for the proxy Optional: {}
audit api.v1beta1.AuditConfig Audit defines audit logging configuration for the proxy Optional: {}
toolConfigRef api.v1beta1.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.v1beta1.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.		 Optional: {}
resources api.v1beta1.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.v1beta1.ResourceOverrides ResourceOverrides allows overriding annotations and labels for resources created by the operator Optional: {}
groupRef api.v1beta1.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.v1beta1.MCPRemoteProxyStatus

MCPRemoteProxyStatus defines the observed state of MCPRemoteProxy

Appears in:

Field Description Default Validation
phase api.v1beta1.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.v1beta1.MCPServer

MCPServer is the Schema for the mcpservers API

Appears in:

Field Description Default Validation
apiVersion string toolhive.stacklok.dev/v1beta1
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.v1beta1.MCPServerSpec
status api.v1beta1.MCPServerStatus

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

Field Description Default Validation
apiVersion string toolhive.stacklok.dev/v1beta1
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.v1beta1.MCPServerEntrySpec
status api.v1beta1.MCPServerEntryStatus

api.v1beta1.MCPServerEntryList

MCPServerEntryList contains a list of MCPServerEntry.

Field Description Default Validation
apiVersion string toolhive.stacklok.dev/v1beta1
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.v1beta1.MCPServerEntry array

api.v1beta1.MCPServerEntryPhase

Underlying type: string

MCPServerEntryPhase represents the lifecycle phase of an MCPServerEntry.

Validation:

  • Enum: [Valid Pending Failed]

Appears in:

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.v1beta1.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:

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.v1beta1.MCPGroupRef GroupRef references the MCPGroup this entry belongs to.
Required — every MCPServerEntry must be part of a group for vMCP discovery.		 Required: {}
externalAuthConfigRef api.v1beta1.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.v1beta1.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.v1beta1.CABundleSource CABundleRef references a ConfigMap containing CA certificates for TLS verification
when connecting to the remote MCP server.		 Optional: {}

api.v1beta1.MCPServerEntryStatus

MCPServerEntryStatus defines the observed state of MCPServerEntry.

Appears in:

Field Description Default Validation
observedGeneration integer ObservedGeneration reflects the generation most recently observed by the controller. Optional: {}
phase api.v1beta1.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.v1beta1.MCPServerList

MCPServerList contains a list of MCPServer

Field Description Default Validation
apiVersion string toolhive.stacklok.dev/v1beta1
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.v1beta1.MCPServer array

api.v1beta1.MCPServerPhase

Underlying type: string

MCPServerPhase is the phase of the MCPServer

Validation:

  • Enum: [Pending Ready Failed Terminating Stopped]

Appears in:

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.v1beta1.MCPServerSpec

MCPServerSpec defines the desired state of MCPServer

Appears in:

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.v1beta1.EnvVar array Env are environment variables to set in the MCP server container Optional: {}
volumes api.v1beta1.Volume array Volumes are volumes to mount in the MCP server container Optional: {}
resources api.v1beta1.ResourceRequirements Resources defines the resource requirements for the MCP server container Optional: {}
secrets api.v1beta1.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.v1beta1.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.v1beta1.ResourceOverrides ResourceOverrides allows overriding annotations and labels for resources created by the operator Optional: {}
oidcConfigRef api.v1beta1.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.		 Optional: {}
authzConfig api.v1beta1.AuthzConfigRef AuthzConfig defines authorization policy configuration for the MCP server Optional: {}
audit api.v1beta1.AuditConfig Audit defines audit logging configuration for the MCP server Optional: {}
toolConfigRef api.v1beta1.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.v1beta1.ExternalAuthConfigRef ExternalAuthConfigRef references a MCPExternalAuthConfig resource for external authentication.
The referenced MCPExternalAuthConfig must exist in the same namespace as this MCPServer.		 Optional: {}
webhookConfigRef api.v1beta1.WebhookConfigRef WebhookConfigRef references a MCPWebhookConfig resource for webhook middleware configuration.
The referenced MCPWebhookConfig must exist in the same namespace as this MCPServer.		 Optional: {}
authServerRef api.v1beta1.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.v1beta1.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.		 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.v1beta1.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.v1beta1.SessionStorageConfig SessionStorage configures session storage for stateful horizontal scaling.
When nil, no session storage is configured.		 Optional: {}
rateLimiting ratelimit.types.RateLimitConfig RateLimiting defines rate limiting configuration for the MCP server.
Requires Redis session storage to be configured for distributed rate limiting.		 Optional: {}

api.v1beta1.MCPServerStatus

MCPServerStatus defines the observed state of MCPServer

Appears in:

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: {}
webhookConfigHash string WebhookConfigHash is the hash of the referenced MCPWebhookConfig spec Optional: {}
url string URL is the URL where the MCP server can be accessed Optional: {}
phase api.v1beta1.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.v1beta1.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:

Field Description Default Validation
apiVersion string toolhive.stacklok.dev/v1beta1
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.v1beta1.MCPTelemetryConfigSpec
status api.v1beta1.MCPTelemetryConfigStatus

api.v1beta1.MCPTelemetryConfigList

MCPTelemetryConfigList contains a list of MCPTelemetryConfig

Field Description Default Validation
apiVersion string toolhive.stacklok.dev/v1beta1
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.v1beta1.MCPTelemetryConfig array

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

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.v1beta1.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:

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

api.v1beta1.MCPTelemetryConfigStatus

MCPTelemetryConfigStatus defines the observed state of MCPTelemetryConfig

Appears in:

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.v1beta1.WorkloadReference array ReferencingWorkloads lists workloads that reference this MCPTelemetryConfig Optional: {}

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

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.v1beta1.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.v1beta1.OpenTelemetryMetricsConfig Metrics defines OpenTelemetry metrics-specific configuration Optional: {}
tracing api.v1beta1.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.v1beta1.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.v1beta1.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:

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

api.v1beta1.MCPToolConfigList

MCPToolConfigList contains a list of MCPToolConfig

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

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

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.v1beta1.ToolOverride) ToolsOverride is a map from actual tool names to their overridden configuration.
This allows renaming tools and/or changing their descriptions.		 Optional: {}

api.v1beta1.MCPToolConfigStatus

MCPToolConfigStatus defines the observed state of MCPToolConfig

Appears in:

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: {}
referenceCount integer ReferenceCount is the number of workloads referencing this config. Optional: {}
referencingWorkloads api.v1beta1.WorkloadReference array ReferencingWorkloads is a list of workload resources that reference this MCPToolConfig.
Each entry identifies the workload by kind and name.		 Optional: {}

api.v1beta1.MCPWebhookConfigSpec

MCPWebhookConfigSpec defines the desired state of MCPWebhookConfig

Field Description Default Validation
validating api.v1beta1.WebhookSpec array Validating webhooks are called to approve or deny MCP requests. Optional: {}
mutating api.v1beta1.WebhookSpec array Mutating webhooks are called to transform MCP requests before processing. Optional: {}

api.v1beta1.MCPWebhookConfigStatus

MCPWebhookConfigStatus defines the observed state of MCPWebhookConfig

Field Description Default Validation
conditions Condition array Conditions represent the latest available observations Optional: {}
observedGeneration integer ObservedGeneration is the last observed generation corresponding to the current status Optional: {}
configHash string ConfigHash is a hash of the spec, used for detecting changes Optional: {}
referencingWorkloads api.v1beta1.WorkloadReference array ReferencingWorkloads is a list of workload resources that reference this MCPWebhookConfig.
Each entry identifies the workload by kind and name.		 Optional: {}

api.v1beta1.ModelCacheConfig

ModelCacheConfig configures persistent storage for model caching

Appears in:

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.v1beta1.NetworkPermissions

NetworkPermissions defines the network permissions for an MCP server

Appears in:

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

api.v1beta1.OAuth2UpstreamConfig

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

Exactly one of ClientID or DCRConfig must be set: ClientID is used when the client is pre-provisioned out of band, DCRConfig enables RFC 7591 Dynamic Client Registration at runtime.

ClientSecretRef is mutually exclusive with DCRConfig: when DCRConfig is set, the client_secret is obtained from the registration response (RFC 7591 §3.2.1) and any static ClientSecretRef would be either dead config or a competing source of truth. The XValidation rule below rejects the combination at admission; ValidateOAuth2DCRConfig is the matching reconcile-time backstop.

Layered XOR behavior: the ClientID/DCRConfig rule treats clientId: "" as absent (size>0) but treats dcrConfig: {} as present (has() is true for an empty object). For input { clientId: "", dcrConfig: {} } the outer rule passes and the inner DCRUpstreamConfig XOR fires with "exactly one of discoveryUrl or registrationEndpoint must be set". This is intentional — adding a non-empty subfield check (e.g., has(self.dcrConfig.discoveryUrl) || has(self.dcrConfig.registrationEndpoint)) would inflate CEL cost on an already-budget-bound rule, and the inner message is still actionable.

Appears in:

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.v1beta1.UserInfoConfig UserInfo contains configuration for fetching user information from the upstream provider.
When omitted and IdentityFromToken is also unset, the embedded auth server runs in
synthesis mode for this upstream: a non-PII subject derived from the access token, no
Name/Email. Use this shape for upstreams with no userinfo surface and no identity in
the token response (e.g., MCP authorization servers per the MCP spec). When
IdentityFromToken is set instead, identity is resolved from the token response body
(e.g., Snowflake's "username" field, Slack's "authed_user.id"); the userinfo HTTP call
is skipped entirely.		 Optional: {}
clientId string ClientID is the OAuth 2.0 client identifier registered with the upstream IDP.
Mutually exclusive with DCRConfig: when DCRConfig is set, ClientID is obtained
at runtime via RFC 7591 Dynamic Client Registration and must be left empty.		 Optional: {}
clientSecretRef api.v1beta1.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.v1beta1.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.
For extracting user identity from the token response, see IdentityFromToken.		 Optional: {}
identityFromToken api.v1beta1.IdentityFromTokenConfig IdentityFromToken extracts user identity (subject, name, email) directly
from the OAuth2 token-endpoint response body using gjson dot-notation paths.
When set, the embedded auth server skips the userinfo HTTP call entirely
and resolves identity from the token response. See IdentityFromTokenConfig
for trust-model and uniqueness considerations.		 Optional: {}
additionalAuthorizationParams object (keys:string, values:string) AdditionalAuthorizationParams are extra query parameters to include in
authorization requests sent to the upstream provider.
This is useful for providers that require custom parameters, such as
Google's access_type=offline for obtaining refresh tokens.
Framework-managed parameters (response_type, client_id, redirect_uri,
scope, state, code_challenge, code_challenge_method, nonce) are not allowed.		 MaxProperties: 16
Optional: {}
dcrConfig api.v1beta1.DCRUpstreamConfig DCRConfig enables RFC 7591 Dynamic Client Registration against the upstream
authorization server. When set, the client credentials are obtained at
runtime rather than being pre-provisioned, and ClientID must be left empty.
Mutually exclusive with ClientID.		 Optional: {}

api.v1beta1.OBOConfig

OBOConfig is a placeholder for On-Behalf-Of (OBO) external auth configuration. The inner schema is intentionally empty in this revision; sub-fields land in a follow-up RFC. The struct exists so OBO *OBOConfig compiles and the CRD schema admits spec.obo: {} — the CEL rule "obo configuration must be set if and only if type is 'obo'" requires has(self.obo), which evaluates true for an empty object. Stored objects with obo: {} will round-trip cleanly when sub-fields land, because Go zero values fill in.

Appears in:

api.v1beta1.OIDCUpstreamConfig

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

Appears in:

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.v1beta1.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"].
When using additionalAuthorizationParams with provider-specific refresh token
mechanisms (e.g., Google's access_type=offline), set explicit scopes to avoid
sending both offline_access and the provider-specific parameter.		 Optional: {}
userInfoOverride api.v1beta1.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: {}
additionalAuthorizationParams object (keys:string, values:string) AdditionalAuthorizationParams are extra query parameters to include in
authorization requests sent to the upstream provider.
This is useful for providers that require custom parameters, such as
Google's access_type=offline for obtaining refresh tokens.
Note: when using access_type=offline, also set explicit scopes to avoid
the default offline_access scope being sent alongside it.
Framework-managed parameters (response_type, client_id, redirect_uri,
scope, state, code_challenge, code_challenge_method, nonce) are not allowed.		 MaxProperties: 16
Optional: {}

api.v1beta1.OpenTelemetryMetricsConfig

OpenTelemetryMetricsConfig defines OpenTelemetry metrics configuration

Appears in:

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

api.v1beta1.OpenTelemetryTracingConfig

OpenTelemetryTracingConfig defines OpenTelemetry tracing configuration

Appears in:

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.v1beta1.OutboundNetworkPermissions

OutboundNetworkPermissions defines the outbound network permissions

Appears in:

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.v1beta1.OutgoingAuthConfig

OutgoingAuthConfig configures authentication from Virtual MCP to backend MCPServers

Appears in:

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

api.v1beta1.PermissionProfileRef

PermissionProfileRef defines a reference to a permission profile

Appears in:

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.v1beta1.PrometheusConfig

PrometheusConfig defines Prometheus-specific configuration

Appears in:

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

api.v1beta1.ProxyDeploymentOverrides

ProxyDeploymentOverrides defines overrides specific to the proxy deployment

Appears in:

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.v1beta1.ResourceMetadataOverrides
env api.v1beta1.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.v1beta1.RedisACLUserConfig

RedisACLUserConfig configures Redis ACL user authentication.

Appears in:

Field Description Default Validation
usernameSecretRef api.v1beta1.SecretKeyRef UsernameSecretRef references a Secret containing the Redis ACL username.
When omitted, connections use legacy password-only AUTH. Omit for managed
Redis tiers that do not support ACL users (e.g. GCP Memorystore Basic/Standard
HA, Azure Cache for Redis). Set for services that support ACL users (e.g. AWS
ElastiCache non-cluster with Redis 6+ RBAC).		 Optional: {}
passwordSecretRef api.v1beta1.SecretKeyRef PasswordSecretRef references a Secret containing the Redis ACL password. Required: {}

api.v1beta1.RedisSentinelConfig

RedisSentinelConfig configures Redis Sentinel connection.

Appears in:

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.v1beta1.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.v1beta1.RedisStorageConfig

RedisStorageConfig configures Redis connection for auth server storage. Exactly one of addr or sentinelConfig must be set. Set clusterMode to true when addr points to a Redis Cluster discovery endpoint (GCP Memorystore Cluster, AWS ElastiCache cluster mode enabled).

Appears in:

Field Description Default Validation
addr string Addr is the Redis server address (host:port). Required for standalone and cluster modes.
Use for managed Redis services that expose a single endpoint (GCP Memorystore basic tier,
AWS ElastiCache without cluster mode, or cluster-mode services when clusterMode is true).
Mutually exclusive with sentinelConfig.		 Optional: {}
clusterMode boolean ClusterMode enables the Redis Cluster protocol. Set to true when addr points to a
Redis Cluster discovery endpoint (e.g., GCP Memorystore Cluster, AWS ElastiCache
cluster mode enabled). Requires addr to be set.		 Optional: {}
sentinelConfig api.v1beta1.RedisSentinelConfig SentinelConfig holds Redis Sentinel configuration.
Use for self-managed Redis with Sentinel-based HA. Mutually exclusive with addr.		 Optional: {}
aclUserConfig api.v1beta1.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.v1beta1.RedisTLSConfig TLS configures TLS for connections to the Redis/Valkey master or cluster nodes.
Presence of this field enables TLS. Omit to use plaintext.		 Optional: {}
sentinelTls api.v1beta1.RedisTLSConfig SentinelTLS configures TLS for connections to Sentinel instances.
Only applies when sentinelConfig is set. Presence of this field enables TLS.		 Optional: {}

api.v1beta1.RedisTLSConfig

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

Appears in:

Field Description Default Validation
insecureSkipVerify boolean InsecureSkipVerify skips TLS certificate verification.
Use when connecting to services with self-signed certificates.		 Optional: {}
caCertSecretRef api.v1beta1.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.v1beta1.ResourceList

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

Appears in:

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.v1beta1.ResourceMetadataOverrides

ResourceMetadataOverrides defines metadata overrides for a resource

Appears in:

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.v1beta1.ResourceOverrides

ResourceOverrides defines overrides for annotations and labels on created resources

Appears in:

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

api.v1beta1.ResourceRequirements

ResourceRequirements describes the compute resource requirements

Appears in:

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

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

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.v1beta1.SecretKeyRef

SecretKeyRef is a reference to a key within a Secret

Appears in:

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.v1beta1.SecretRef

SecretRef is a reference to a secret

Appears in:

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.v1beta1.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:

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

api.v1beta1.SentinelServiceRef

Underlying type: [api.v1beta1.struct{Name string "json:"name""; Namespace string "json:"namespace,omitempty""; Port int32 "json:"port,omitempty""}](#apiv1beta1struct{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.v1beta1.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:

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.v1beta1.SecretKeyRef PasswordRef is a reference to a Secret key containing the Redis password Optional: {}

api.v1beta1.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/oauthproto/tokenexchange/middleware.go

Appears in:

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.v1beta1.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.v1beta1.TokenLifespanConfig

TokenLifespanConfig holds configuration for token lifetimes.

Appears in:

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.v1beta1.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".

For extracting user identity from the token response, see IdentityFromToken.

Appears in:

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.v1beta1.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:

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.v1beta1.ToolConfigRef

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

Appears in:

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

api.v1beta1.ToolOverride

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

Appears in:

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.v1beta1.ToolAnnotationsOverride Annotations overrides specific tool annotation fields.
Only specified fields are overridden; others pass through from the backend.		 Optional: {}

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

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.v1beta1.UpstreamProviderConfig

UpstreamProviderConfig defines configuration for an upstream Identity Provider.

Exactly one of OIDCConfig or OAuth2Config must be set and must match the declared Type: oidc-typed providers set OIDCConfig, oauth2-typed providers set OAuth2Config. The CEL rule below enforces the pairing at admission; the matching Go-level check in validateUpstreamProvider provides defense-in-depth for stored objects.

The rule is structured as a chain of equality checks ending in an explicit false, so adding a new UpstreamProviderType value without extending this rule fails admission instead of silently demanding the OAuth2 shape. When adding a new type, extend both this rule and validateUpstreamProvider.

Appears in:

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.v1beta1.UpstreamProviderType Type specifies the provider type: "oidc" or "oauth2" Enum: [oidc oauth2]
Required: {}
oidcConfig api.v1beta1.OIDCUpstreamConfig OIDCConfig contains OIDC-specific configuration.
Required when Type is "oidc", must be nil when Type is "oauth2".		 Optional: {}
oauth2Config api.v1beta1.OAuth2UpstreamConfig OAuth2Config contains OAuth 2.0-specific configuration.
Required when Type is "oauth2", must be nil when Type is "oidc".		 Optional: {}

api.v1beta1.UpstreamProviderType

Underlying type: string

UpstreamProviderType identifies the type of upstream Identity Provider.

Appears in:

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

api.v1beta1.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. For providers that do not expose a usable userinfo endpoint but include identity in the OAuth2 token response, use IdentityFromToken on OAuth2UpstreamConfig instead.

Appears in:

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.v1beta1.UserInfoFieldMapping FieldMapping contains custom field mapping configuration for non-standard providers.
If nil, standard OIDC field names are used ("sub", "name", "email").		 Optional: {}

api.v1beta1.UserInfoFieldMapping

Underlying type: [api.v1beta1.struct{SubjectFields []string "json:"subjectFields,omitempty""; NameFields []string "json:"nameFields,omitempty""; EmailFields []string "json:"emailFields,omitempty""}](#apiv1beta1struct{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.v1beta1.ValidationStatus

Underlying type: string

ValidationStatus represents the validation state of a workflow

Validation:

  • Enum: [Valid Invalid Unknown]

Appears in:

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.v1beta1.VirtualMCPCompositeToolDefinition

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

Appears in:

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

api.v1beta1.VirtualMCPCompositeToolDefinitionList

VirtualMCPCompositeToolDefinitionList contains a list of VirtualMCPCompositeToolDefinition

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

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

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.v1beta1.VirtualMCPCompositeToolDefinitionStatus

VirtualMCPCompositeToolDefinitionStatus defines the observed state of VirtualMCPCompositeToolDefinition

Appears in:

Field Description Default Validation
validationStatus api.v1beta1.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.v1beta1.VirtualMCPServer

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

Appears in:

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

api.v1beta1.VirtualMCPServerList

VirtualMCPServerList contains a list of VirtualMCPServer

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

api.v1beta1.VirtualMCPServerPhase

Underlying type: string

VirtualMCPServerPhase represents the lifecycle phase of a VirtualMCPServer

Validation:

  • Enum: [Pending Ready Degraded Failed]

Appears in:

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.v1beta1.VirtualMCPServerSpec

VirtualMCPServerSpec defines the desired state of VirtualMCPServer

Appears in:

Field Description Default Validation
incomingAuth api.v1beta1.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.v1beta1.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.v1beta1.MCPGroupRef GroupRef references the MCPGroup that defines backend workloads.
The referenced MCPGroup must exist in the same namespace.		 Required: {}
config vmcp.config.Config Config is the Virtual MCP server configuration.
The audit config from here is also supported, but not required.		 Type: object
Optional: {}
telemetryConfigRef api.v1beta1.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.		 Optional: {}
embeddingServerRef api.v1beta1.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.v1beta1.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.OIDCConfigRef
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.v1beta1.SessionStorageConfig SessionStorage configures session storage for stateful horizontal scaling.
When nil, no session storage is configured.		 Optional: {}
imagePullSecrets LocalObjectReference array ImagePullSecrets allows specifying image pull secrets for the vMCP workload.
These are applied to both the vMCP Deployment's PodSpec.ImagePullSecrets
and to the operator-managed ServiceAccount the vMCP server runs as, so private
images are pullable through either path.
Merge semantics with PodTemplateSpec:
The deployed PodSpec.ImagePullSecrets is the Kubernetes-native strategic-merge
union of this field and spec.podTemplateSpec.spec.imagePullSecrets, merged by
the patchStrategy:"merge" / patchMergeKey:"name" tags on corev1.PodSpec.
- This field is rendered first as the controller-generated default.
- spec.podTemplateSpec.spec.imagePullSecrets is then strategic-merge-patched
on top, keyed by Name. Distinct names from the two sources are unioned in
the resulting list; entries with the same Name are deduplicated and the
PodTemplateSpec entry wins on overlap (user override).
- Order in the resulting list is not guaranteed and should not be relied on:
strategic merge by name is order-insensitive.
- The operator-managed ServiceAccount's imagePullSecrets list is populated
ONLY from this field. spec.podTemplateSpec.spec.imagePullSecrets does not
reach the ServiceAccount because PodTemplateSpec has no notion of a
ServiceAccount. To make a secret usable via the ServiceAccount path
(e.g. for sidecars or init containers that pull images independently),
list it here rather than under spec.podTemplateSpec.
Note on cross-CRD consistency:
MCPRegistry currently uses an atomic-replace strategy for its imagePullSecrets
(the user-provided value replaces the controller-generated list rather than
being merged on top). VirtualMCPServer follows the Kubernetes-native
strategic-merge-by-name behavior described above. Aligning the two is tracked
as a separate follow-up; until then, manifests that set imagePullSecrets on
both CRDs will see different override behavior between them.		 Optional: {}

api.v1beta1.VirtualMCPServerStatus

VirtualMCPServerStatus defines the observed state of VirtualMCPServer

Appears in:

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.v1beta1.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.v1beta1.DiscoveredBackend array DiscoveredBackends lists discovered backend configurations from the MCPGroup Optional: {}
backendCount integer BackendCount is the number of routable backends (ready + unauthenticated).
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.v1beta1.Volume

Volume represents a volume to mount in a container

Appears in:

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.v1beta1.WebhookConfigRef

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

Appears in:

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

api.v1beta1.WebhookFailurePolicy

Underlying type: string

WebhookFailurePolicy defines how webhook errors are handled.

Appears in:

Field Description
fail WebhookFailurePolicyFail denies the request on webhook error.
ignore WebhookFailurePolicyIgnore allows the request on webhook error.

api.v1beta1.WebhookSpec

WebhookSpec defines the configuration for a single webhook middleware

Appears in:

Field Description Default Validation
name string Name is a unique identifier for this webhook MaxLength: 63
MinLength: 1
url string URL is the endpoint to call for this webhook. Must be an HTTP/HTTPS URL. Format: uri
timeout Duration Timeout configures the maximum time to wait for the webhook to respond.
Defaults to 10s if not specified. Maximum is 30s.		 Format: duration
Type: string
Optional: {}
failurePolicy api.v1beta1.WebhookFailurePolicy FailurePolicy defines how to handle errors when communicating with the webhook.
Supported values: "fail", "ignore". Defaults to "fail".		 fail Enum: [fail ignore]
Optional: {}
tlsConfig api.v1beta1.WebhookTLSConfig TLSConfig contains optional TLS configuration for the webhook connection. Optional: {}
hmacSecretRef api.v1beta1.SecretKeyRef HMACSecretRef references a Kubernetes Secret containing the HMAC signing key
used to sign the webhook payload. If set, the X-Toolhive-Signature header will be injected.		 Optional: {}

api.v1beta1.WebhookTLSConfig

WebhookTLSConfig contains TLS configuration for secure webhook connections

Appears in:

Field Description Default Validation
caSecretRef api.v1beta1.SecretKeyRef CASecretRef references a Secret containing the CA certificate bundle used to verify the webhook server's certificate.
Contains a bundle of PEM-encoded X.509 certificates.		 Optional: {}
clientCertSecretRef api.v1beta1.SecretKeyRef ClientCertSecretRef references a Secret containing the client certificate for mTLS authentication.
The referenced key must contain a PEM-encoded client certificate.
Use ClientKeySecretRef to provide the corresponding private key.		 Optional: {}
clientKeySecretRef api.v1beta1.SecretKeyRef ClientKeySecretRef references a Secret containing the private key for the client certificate.
Required when ClientCertSecretRef is set to enable mTLS.		 Optional: {}
insecureSkipVerify boolean InsecureSkipVerify disables server certificate verification.
WARNING: This should only be used for development/testing and not in production environments.		 Optional: {}

api.v1beta1.WorkloadReference

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

Appears in:

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