API Reference

Packages

• toolhive.stacklok.dev/audit
• toolhive.stacklok.dev/authtypes
• toolhive.stacklok.dev/config
• toolhive.stacklok.dev/json
• toolhive.stacklok.dev/ratelimit
• toolhive.stacklok.dev/telemetry
• toolhive.stacklok.dev/v1alpha1
• toolhive.stacklok.dev/v1beta1
• toolhive.stacklok.dev/vmcp

toolhive.stacklok.dev/audit

pkg.audit.Config

Config represents the audit logging configuration.

Appears in:

• vmcp.config.Config

Field	Description	Default	Validation
enabled boolean	Enabled controls whether audit logging is enabled. When true, enables audit logging with the configured options.	false	Optional: {}
component string	Component is the component name to use in audit events.		Optional: {}
eventTypes string array	EventTypes specifies which event types to audit. If empty, all events are audited.		Optional: {}
excludeEventTypes string array	ExcludeEventTypes specifies which event types to exclude from auditing. This takes precedence over EventTypes.		Optional: {}
includeRequestData boolean	IncludeRequestData determines whether to include request data in audit logs.	false	Optional: {}
includeResponseData boolean	IncludeResponseData determines whether to include response data in audit logs.	false	Optional: {}
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:

• auth.types.BackendAuthStrategy

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:

• vmcp.config.OutgoingAuthConfig

Field	Description	Default	Validation
type string	Type is the auth strategy: "unauthenticated", "header_injection", "token_exchange", "upstream_inject", "aws_sts", "obo", "xaa"
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".
obo auth.types.OBOConfig	OBO contains configuration for on-behalf-of (OBO) auth strategy. Used when Type = "obo". The default upstream build returns ErrEnterpriseRequired; an out-of-tree build registers a real strategy via auth.RegisterOBOStrategy.
xaa auth.types.XAAConfig	XAA contains configuration for XAA (Cross-Application Access) auth strategy. Used when Type = "xaa".

auth.types.HeaderInjectionConfig

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

Appears in:

• auth.types.BackendAuthStrategy

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

auth.types.OBOConfig

OBOConfig configures the on-behalf-of (OBO) authentication strategy. This strategy uses the Entra jwt-bearer / on_behalf_of grant to exchange the incoming user token for a backend-scoped token on behalf of the user.

Field names follow the OBO runtime contract (the enterprise obo.MiddlewareParameters), not the RFC-8693 TokenExchangeConfig, because OBO uses a distinct Entra-specific grant.

Appears in:

• auth.types.BackendAuthStrategy

Field	Description	Default	Validation
tokenUrl string	TokenURL is the Entra token endpoint URL for the OBO exchange.		Required: {}
clientId string	ClientID is the OAuth client ID for the OBO 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 (resource URI) for the exchanged token.
scopes string array	Scopes are the requested scopes for the exchanged token.
subjectTokenProviderName string	SubjectTokenProviderName selects which upstream provider's token to use as the subject (assertion) token for the OBO exchange. When set, the token is looked up from Identity.UpstreamTokens[SubjectTokenProviderName]; when omitted, the inbound end-user token (Identity.Token) is used directly. Matches the operator CRD's SubjectTokenProviderName field; the enterprise OBO converter maps both to the runtime contract without renaming.
cacheSkewSeconds integer	CacheSkewSeconds is the number of seconds to subtract from a cached token's expiry when deciding whether to refresh it. Defaults to zero (no skew). The operator CRD stores this as CacheSkew *metav1.Duration and converts it to an integer-seconds value for the vMCP runtime contract.

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:

• auth.types.AwsStsConfig

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:

• auth.types.BackendAuthStrategy

Field	Description	Default	Validation
tokenUrl string	TokenURL is the OAuth token endpoint URL for token exchange.
clientId string	ClientID is the OAuth client ID for the token exchange request.
clientSecret string	ClientSecret is the OAuth client secret (use ClientSecretEnv for security).
clientSecretEnv string	ClientSecretEnv is the environment variable name containing the client secret. The value will be resolved at runtime from this environment variable.
audience string	Audience is the target audience for the exchanged token.
scopes string array	Scopes are the requested scopes for the exchanged token.
subjectTokenType string	SubjectTokenType is the token type of the incoming subject token. Defaults to "urn:ietf:params:oauth:token-type:access_token" if not specified.
subjectProviderName string	SubjectProviderName selects which upstream provider's token to use as the subject token. When set, the token is looked up from Identity.UpstreamTokens instead of using Identity.Token. When left empty and an embedded authorization server is configured, the system automatically populates this field with the first configured upstream provider name. Set it explicitly to override that default or to select a specific provider when multiple upstreams are configured.

auth.types.UpstreamInjectConfig

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

Appears in:

• auth.types.BackendAuthStrategy

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

auth.types.XAAConfig

XAAConfig configures the XAA (Cross-Application Access) auth strategy. XAA implements draft-ietf-oauth-identity-assertion-authz-grant (ID-JAG) as a two-step flow:

• IdP exchange (RFC 8693): Exchange the user's ID token at their IdP for an ID-JAG JWT
• Target grant (RFC 7523): Exchange the ID-JAG at the target app's AS for an access token

Appears in:

• auth.types.BackendAuthStrategy

Field	Description	Default	Validation
idpTokenUrl string	IDPTokenURL is the IdP token endpoint for IdP exchange (RFC 8693 exchange).
idpClientId string	IDPClientID is the OAuth client ID at the IdP for IdP exchange.
idpClientSecret string	IDPClientSecret is the client secret at the IdP for IdP exchange.
idpClientSecretEnv string	IDPClientSecretEnv is the env var containing the IdP client secret.
targetTokenUrl string	TargetTokenURL is the target AS token endpoint for target grant (JWT Bearer grant).
insecureTargetTokenUrl boolean	InsecureTargetTokenURL allows plain HTTP for TargetTokenURL. WARNING: this is insecure and must only be set for in-cluster or development/testing endpoints — never in production.
targetClientId string	TargetClientID is the OAuth client ID at the target AS for target grant.
targetClientSecret string	TargetClientSecret is the client secret at the target AS for target grant.
targetClientSecretEnv string	TargetClientSecretEnv is the env var containing the target AS client secret.
targetAudience string	TargetAudience is the resource AS URL for the ID-JAG audience claim (required).
targetResource string	TargetResource is the RFC 8707 resource indicator sent as the resource parameter in IdP exchange's RFC 8693 token exchange (draft §4.3, OPTIONAL). It identifies the target resource server — not the access-token audience, which is governed by TargetAudience. For MCP backends, set to the MCP server URL.
scopes string array	Scopes are the requested scopes for IdP exchange and target grant.
subjectProviderName string	SubjectProviderName selects which upstream provider's ID token to use. Auto-populated when embedded AS is active.
subjectTokenType string	SubjectTokenType is the token-type URN of the upstream subject token used in IdP exchange. Defaults to TokenTypeIDToken when empty. Currently only urn:ietf:params:oauth:token-type:id_token is accepted; the field exists to allow future expansion to SAML upstreams without an API break.

toolhive.stacklok.dev/config

vmcp.config.AggregationConfig

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

Tool Visibility vs Routing:

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

Appears in:

• vmcp.config.Config

Field	Description	Default	Validation
conflictResolution pkg.vmcp.ConflictResolutionStrategy	ConflictResolution defines the strategy for resolving tool name conflicts. - prefix: Automatically prefix tool names with workload identifier - priority: First workload in priority order wins - manual: Explicitly define overrides for all conflicts	prefix	Enum: [prefix priority manual] Optional: {}
conflictResolutionConfig vmcp.config.ConflictResolutionConfig	ConflictResolutionConfig provides configuration for the chosen strategy.		Optional: {}
tools vmcp.config.WorkloadToolConfig array	Tools defines per-workload tool filtering and overrides.		Optional: {}
excludeAllTools boolean	ExcludeAllTools hides all backend tools from MCP clients when true. Hidden tools are NOT advertised in tools/list responses, but they ARE available in the routing table for composite tools to use. This enables the use case where you want to hide raw backend tools from direct client access while exposing curated composite tool workflows.		Optional: {}

vmcp.config.AuthzConfig

AuthzConfig configures authorization.

Appears in:

• vmcp.config.IncomingAuthConfig

Field	Description	Default	Validation
type string	Type is the authz type: "cedar", "none"
policies string array	Policies contains Cedar policy definitions (when Type = "cedar").
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:

• vmcp.config.FailureHandlingConfig

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

vmcp.config.CodeModeConfig

CodeModeConfig configures vMCP code mode (the execute_tool_script virtual tool). When enabled, agents can submit a Starlark script that calls multiple backend tools server-side — with loops, conditionals, and parallel() fan-out — and receive a single aggregated result, collapsing many tool-call round-trips into one.

Appears in:

• vmcp.config.Config

Field	Description	Default	Validation
enabled boolean	Enabled turns code mode on. When false (the default), execute_tool_script is not advertised in tools/list and scripts cannot be executed.		Optional: {}
stepLimit integer	StepLimit is the maximum number of Starlark execution steps per script. It bounds runaway loops and computation. Defaults to 100000 if unset or zero.	100000	Minimum: 1 Optional: {}
parallelMaxConcurrency integer	ParallelMaxConcurrency caps the number of goroutines a script's parallel() builtin may run concurrently. Defaults to 10 if unset or zero.	10	Minimum: 1 Optional: {}
toolCallTimeout vmcp.config.Duration	ToolCallTimeout bounds each individual backend tool call made from within a script. A call exceeding it is cancelled and surfaces a timeout error to the script. Defaults to 30s if unset.	30s	Pattern: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$ Type: string Optional: {}

vmcp.config.CompositeToolConfig

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

Appears in:

• vmcp.config.Config
• api.v1beta1.VirtualMCPCompositeToolDefinitionSpec

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

vmcp.config.CompositeToolRef

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

Appears in:

• vmcp.config.Config

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

vmcp.config.Config

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

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

Validation:

• Type: object

Appears in:

• api.v1beta1.VirtualMCPServerSpec

Field	Description	Default	Validation
name string	Name is the virtual MCP server name.		Optional: {}
groupRef string	Group references an existing MCPGroup that defines backend workloads. In 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: {}
codeMode vmcp.config.CodeModeConfig	CodeMode configures vMCP code mode: server-side execution of Starlark scripts that orchestrate multiple backend tool calls in a single request via the execute_tool_script virtual tool. When enabled, execute_tool_script is advertised alongside the backend tools; a script's inner tool calls are authorized individually, so a script can only reach tools the caller is already permitted to use. Disabled by default.		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: {}
passthroughHeaders string array	PassthroughHeaders is an allowlist of incoming client request header names forwarded verbatim to all backends. Captured at the vMCP incoming edge by headerforward.CaptureMiddleware and consumed once at session creation when the per-session backend client's HeaderForwardConfig is built. Names must not be in the restricted set (Host, hop-by-hop, X-Forwarded-*, etc.).		Optional: {}

vmcp.config.ConflictResolutionConfig

ConflictResolutionConfig provides configuration for conflict resolution strategies.

Appears in:

• vmcp.config.AggregationConfig

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

vmcp.config.Duration

Underlying type: Duration

Duration is a wrapper around time.Duration that marshals/unmarshals as a duration string. This ensures duration values are serialized as "30s", "1m", etc. instead of nanosecond integers.

Validation:

• Pattern: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
• Type: string

Appears in:

• vmcp.config.CircuitBreakerConfig
• vmcp.config.CodeModeConfig
• vmcp.config.CompositeToolConfig
• vmcp.config.FailureHandlingConfig
• vmcp.config.OptimizerConfig
• vmcp.config.StepErrorHandling
• vmcp.config.TimeoutConfig
• api.v1beta1.VirtualMCPCompositeToolDefinitionSpec
• vmcp.config.WorkflowStepConfig

vmcp.config.ElicitationResponseConfig

ElicitationResponseConfig defines how to handle user responses to elicitation requests.

Appears in:

• vmcp.config.WorkflowStepConfig

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

vmcp.config.FailureHandlingConfig

FailureHandlingConfig configures failure handling behavior.

Appears in:

• vmcp.config.OperationalConfig

Field	Description	Default	Validation
healthCheckInterval vmcp.config.Duration	HealthCheckInterval is the interval between health checks.	30s	Pattern: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$ Type: string Optional: {}
unhealthyThreshold integer	UnhealthyThreshold is the number of consecutive failures before marking unhealthy.	3	Optional: {}
healthCheckTimeout vmcp.config.Duration	HealthCheckTimeout is the maximum duration for a single health check operation. Should be less than HealthCheckInterval to prevent checks from queuing up.	10s	Pattern: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$ Type: string Optional: {}
statusReportingInterval vmcp.config.Duration	StatusReportingInterval is the interval for reporting status updates to Kubernetes. This controls how often the vMCP runtime reports backend health and phase changes. Lower values provide faster status updates but increase API server load.	30s	Pattern: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$ Type: string Optional: {}
partialFailureMode string	PartialFailureMode defines behavior when some backends are unavailable. - fail: Fail entire request if any backend is unavailable - best_effort: Continue with available backends	fail	Enum: [fail best_effort] Optional: {}
circuitBreaker vmcp.config.CircuitBreakerConfig	CircuitBreaker configures circuit breaker behavior.		Optional: {}

vmcp.config.IncomingAuthConfig

IncomingAuthConfig configures client authentication to the virtual MCP server.

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

Appears in:

• vmcp.config.Config

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

vmcp.config.OIDCConfig

OIDCConfig configures OpenID Connect authentication.

Appears in:

• vmcp.config.IncomingAuthConfig

Field	Description	Default	Validation
issuer string	Issuer is the OIDC issuer URL.		Pattern: ^https?://
clientId string	ClientID is the OAuth client ID.
clientSecretEnv string	ClientSecretEnv is the name of the environment variable containing the client secret. This is the secure way to reference secrets - the actual secret value is never stored in configuration files, only the environment variable name. The secret value will be resolved from this environment variable at runtime.
audience string	Audience is the required token audience.
resource string	Resource is the OAuth 2.0 resource indicator (RFC 8707). Used in WWW-Authenticate header and OAuth discovery metadata (RFC 9728). If not specified, defaults to Audience.
jwksUrl string	JWKSURL is the explicit JWKS endpoint URL. When set, skips OIDC discovery and fetches the JWKS directly from this URL. This is useful when the OIDC issuer does not serve a /.well-known/openid-configuration.		Optional: {}
introspectionUrl string	IntrospectionURL is the token introspection endpoint URL (RFC 7662). When set, enables token introspection for opaque (non-JWT) tokens.		Optional: {}
scopes string array	Scopes are the required OAuth scopes.
protectedResourceAllowPrivateIp boolean	ProtectedResourceAllowPrivateIP allows protected resource endpoint on private IP addresses Use with caution - only enable for trusted internal IDPs or testing
jwksAllowPrivateIp boolean	JwksAllowPrivateIP allows OIDC discovery and JWKS fetches to private IP addresses. Enable when the embedded auth server runs on a loopback address and the OIDC middleware needs to fetch its JWKS from that address. Use with caution - only enable for trusted internal IDPs or testing.
insecureAllowHttp boolean	InsecureAllowHTTP allows HTTP (non-HTTPS) OIDC issuers for development/testing WARNING: This is insecure and should NEVER be used in production

vmcp.config.OperationalConfig

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

Appears in:

• vmcp.config.Config

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

vmcp.config.OptimizerConfig

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

Appears in:

• vmcp.config.Config

Field	Description	Default	Validation
embeddingService string	EmbeddingService is the full base URL of the embedding service endpoint (e.g., http://my-embedding.default.svc.cluster.local:8080) for semantic tool discovery. In a Kubernetes environment, it is more convenient to use the VirtualMCPServerSpec.EmbeddingServerRef field instead of setting this directly. EmbeddingServerRef references an EmbeddingServer CRD by name, and the operator automatically resolves the referenced resource's Status.URL to populate this field. This provides managed lifecycle (the operator watches the EmbeddingServer for readiness and URL changes) and avoids hardcoding service URLs in the config. If both EmbeddingServerRef and this field are set, EmbeddingServerRef takes precedence and this value is overridden with a warning.		Optional: {}
embeddingServiceTimeout vmcp.config.Duration	EmbeddingServiceTimeout is the HTTP request timeout for calls to the embedding service. Defaults to 30s if not specified.	30s	Pattern: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$ Type: string Optional: {}
embeddingProvider string	EmbeddingProvider selects the wire protocol used to talk to the embedding service. "tei" speaks the HuggingFace Text Embeddings Inference API; "openai" speaks the OpenAI-compatible /embeddings API, which lets the optimizer use OpenAI, Azure OpenAI, or another OpenAI-compatible gateway. Defaults to "tei" when empty. The "openai" provider reads EmbeddingService directly and cannot be combined with EmbeddingServerRef, which provisions a managed TEI server; the operator rejects that combination at admission.	tei	Enum: [tei openai] Optional: {}
embeddingModel string	EmbeddingModel is the model name requested from the embedding service (e.g. "text-embedding-3-small"). Required when EmbeddingProvider is "openai". Ignored for the "tei" provider, where the model is fixed by the running TEI container. The API key for an OpenAI-compatible service is not configured here: it is read from the OPENAI_API_KEY environment variable so the secret never lands in a CRD spec or ConfigMap. An empty key omits the Authorization header, which supports keyless in-cluster gateways.		Optional: {}
embeddingHeaders object (keys:string, values:vmcp.config.EmbeddingHeaderValue)	EmbeddingHeaders holds additional HTTP headers sent with every embedding request. Only supported when EmbeddingProvider is "openai". Values are stored in plain text and must not contain secrets; Authorization (derived from OPENAI_API_KEY) and Content-Type cannot be set.		MaxProperties: 32 Optional: {}
maxToolsToReturn integer	MaxToolsToReturn is the maximum number of tool results returned by a search query. Defaults to 8 if not specified or zero.		Maximum: 50 Minimum: 1 Optional: {}
hybridSearchSemanticRatio string	HybridSearchSemanticRatio controls the balance between semantic (meaning-based) and keyword search results. 0.0 = all keyword, 1.0 = all semantic. Defaults to "0.5" if not specified or empty. Serialized as a string because CRDs do not support float types portably.		Pattern: ^([0-9]*[.])?[0-9]+$ Optional: {}
semanticDistanceThreshold string	SemanticDistanceThreshold is the maximum distance for semantic search results. Results exceeding this threshold are filtered out from semantic search. This threshold does not apply to keyword search. Range: 0 = identical, 2 = completely unrelated. Defaults to "1.0" if not specified or empty. Serialized as a string because CRDs do not support float types portably.		Pattern: ^([0-9]*[.])?[0-9]+$ Optional: {}

vmcp.config.OutgoingAuthConfig

OutgoingAuthConfig configures backend authentication.

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

Appears in:

• vmcp.config.Config

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

vmcp.config.OutputConfig

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

Appears in:

• vmcp.config.CompositeToolConfig
• api.v1beta1.VirtualMCPCompositeToolDefinitionSpec

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

vmcp.config.OutputProperty

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

Appears in:

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

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

vmcp.config.SessionStorageConfig

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

Appears in:

• vmcp.config.Config

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

vmcp.config.StaticBackendConfig

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

Appears in:

• vmcp.config.Config

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

vmcp.config.StepErrorHandling

StepErrorHandling defines error handling behavior for workflow steps.

Appears in:

• vmcp.config.WorkflowStepConfig

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

vmcp.config.TimeoutConfig

TimeoutConfig configures timeout settings.

Appears in:

• vmcp.config.OperationalConfig

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

vmcp.config.ToolAnnotationsOverride

Underlying type: 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""}

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

Appears in:

• vmcp.config.ToolOverride

vmcp.config.ToolConfigRef

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

Appears in:

• vmcp.config.WorkloadToolConfig

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

vmcp.config.ToolOverride

ToolOverride defines tool name, description, and annotation overrides.

Appears in:

• vmcp.config.WorkloadToolConfig

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

vmcp.config.WorkflowStepConfig

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

Appears in:

• vmcp.config.CompositeToolConfig
• api.v1beta1.VirtualMCPCompositeToolDefinitionSpec
• vmcp.config.WorkflowStepConfig

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

vmcp.config.WorkloadToolConfig

WorkloadToolConfig defines tool filtering and overrides for a specific workload.

Appears in:

• vmcp.config.AggregationConfig

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

toolhive.stacklok.dev/json

pkg.json.Any

Any is a type alias for Data[any], storing arbitrary JSON values. This is the most flexible type, suitable when the JSON structure is unknown.

Validation:

• Type: object

pkg.json.Map

Map is a type alias for Data[map[string]any], storing JSON objects. Use this when you know the data will always be a JSON object (not array, string, etc.).

Validation:

• Type: object

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:

• ratelimit.types.RateLimitConfig
• ratelimit.types.ToolRateLimitConfig

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

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:

• vmcp.config.Config
• api.v1beta1.MCPServerSpec

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:

• ratelimit.types.RateLimitConfig

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:

• vmcp.config.Config

Field	Description	Default	Validation
endpoint string	Endpoint is the OTLP endpoint URL		Optional: {}
serviceName string	ServiceName is the service name for telemetry. When omitted, defaults to the server name (e.g., VirtualMCPServer name).		Optional: {}
serviceVersion string	ServiceVersion is the service version for telemetry. When omitted, defaults to the ToolHive version.		Optional: {}
tracingEnabled boolean	TracingEnabled controls whether distributed tracing is enabled. When false, no tracer provider is created even if an endpoint is configured.	false	Optional: {}
metricsEnabled boolean	MetricsEnabled controls whether OTLP metrics are enabled. When false, OTLP metrics are not sent even if an endpoint is configured. This is independent of EnablePrometheusMetricsPath.	false	Optional: {}
samplingRate string	SamplingRate is the trace sampling rate (0.0-1.0) as a string. Only used when TracingEnabled is true. Example: "0.05" for 5% sampling.	0.05	Optional: {}
headers object (keys:string, values:string)	Headers contains authentication headers for the OTLP endpoint.		Optional: {}
insecure boolean	Insecure indicates whether to use HTTP instead of HTTPS for the OTLP endpoint.	false	Optional: {}
enablePrometheusMetricsPath boolean	EnablePrometheusMetricsPath controls whether to expose Prometheus-style /metrics endpoint. The metrics are served on the main transport port at /metrics. This is separate from OTLP metrics which are sent to the Endpoint.	false	Optional: {}
environmentVariables string array	EnvironmentVariables is a list of environment variable names that should be included in telemetry spans as attributes. Only variables in this list will be read from the host machine and included in spans for observability. Example: ["NODE_ENV", "DEPLOYMENT_ENV", "SERVICE_VERSION"]		Optional: {}
customAttributes object (keys:string, values:string)	CustomAttributes contains custom resource attributes to be added to all telemetry signals. These are parsed from CLI flags (--otel-custom-attributes) or environment variables (OTEL_RESOURCE_ATTRIBUTES) as key=value pairs.		Optional: {}
useLegacyAttributes boolean	UseLegacyAttributes controls whether legacy (pre-MCP OTEL semconv) attribute names are emitted alongside the new standard attribute names. When true, spans include both old and new attribute names for backward compatibility with existing dashboards. Currently defaults to true; this will change to false in a future release.	true	Optional: {}
caCertPath string	CACertPath is the file path to a CA certificate bundle for the OTLP endpoint. When set, the OTLP exporters use this CA to verify the collector's TLS certificate instead of relying solely on the system CA pool.		Optional: {}

toolhive.stacklok.dev/v1alpha1

Resource Types

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

api.v1alpha1.EmbeddingServer

EmbeddingServer is the deprecated v1alpha1 version of the EmbeddingServer resource.

Field	Description	Default	Validation
apiVersion string	toolhive.stacklok.dev/v1alpha1
kind string	EmbeddingServer
kind string	Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds		Optional: {}
apiVersion string	APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources		Optional: {}
metadata ObjectMeta	Refer to Kubernetes API documentation for fields of metadata.
spec api.v1beta1.EmbeddingServerSpec
status api.v1beta1.EmbeddingServerStatus

api.v1alpha1.EmbeddingServerList

EmbeddingServerList contains a list of EmbeddingServer.

Field	Description	Default	Validation
apiVersion string	toolhive.stacklok.dev/v1alpha1
kind string	EmbeddingServerList
kind string	Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds		Optional: {}
apiVersion string	APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources		Optional: {}
metadata ListMeta	Refer to Kubernetes API documentation for fields of metadata.
items api.v1alpha1.EmbeddingServer array

api.v1alpha1.MCPAuthzConfig

MCPAuthzConfig is the deprecated v1alpha1 version of the MCPAuthzConfig resource.

Field	Description	Default	Validation
apiVersion string	toolhive.stacklok.dev/v1alpha1
kind string	MCPAuthzConfig
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.MCPAuthzConfigSpec
status api.v1beta1.MCPAuthzConfigStatus

api.v1alpha1.MCPAuthzConfigList

MCPAuthzConfigList contains a list of MCPAuthzConfig.

Field	Description	Default	Validation
apiVersion string	toolhive.stacklok.dev/v1alpha1
kind string	MCPAuthzConfigList
kind string	Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds		Optional: {}
apiVersion string	APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources		Optional: {}
metadata ListMeta	Refer to Kubernetes API documentation for fields of metadata.
items api.v1alpha1.MCPAuthzConfig array

api.v1alpha1.MCPExternalAuthConfig

MCPExternalAuthConfig is the deprecated v1alpha1 version of the MCPExternalAuthConfig resource.

Field	Description	Default	Validation
apiVersion string	toolhive.stacklok.dev/v1alpha1
kind string	MCPExternalAuthConfig
kind string	Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds		Optional: {}
apiVersion string	APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources		Optional: {}
metadata ObjectMeta	Refer to Kubernetes API documentation for fields of metadata.
spec api.v1beta1.MCPExternalAuthConfigSpec
status api.v1beta1.MCPExternalAuthConfigStatus

api.v1alpha1.MCPExternalAuthConfigList

MCPExternalAuthConfigList contains a list of MCPExternalAuthConfig.

Field	Description	Default	Validation
apiVersion string	toolhive.stacklok.dev/v1alpha1
kind string	MCPExternalAuthConfigList
kind string	Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds		Optional: {}
apiVersion string	APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources		Optional: {}
metadata ListMeta	Refer to Kubernetes API documentation for fields of metadata.
items api.v1alpha1.MCPExternalAuthConfig array

api.v1alpha1.MCPGroup

MCPGroup is the deprecated v1alpha1 version of the MCPGroup resource.

Field	Description	Default	Validation
apiVersion string	toolhive.stacklok.dev/v1alpha1
kind string	MCPGroup
kind string	Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds		Optional: {}
apiVersion string	APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources		Optional: {}
metadata ObjectMeta	Refer to Kubernetes API documentation for fields of metadata.
spec api.v1beta1.MCPGroupSpec
status api.v1beta1.MCPGroupStatus

api.v1alpha1.MCPGroupList

MCPGroupList contains a list of MCPGroup.

Field	Description	Default	Validation
apiVersion string	toolhive.stacklok.dev/v1alpha1
kind string	MCPGroupList
kind string	Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds		Optional: {}
apiVersion string	APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources		Optional: {}
metadata ListMeta	Refer to Kubernetes API documentation for fields of metadata.
items api.v1alpha1.MCPGroup array

api.v1alpha1.MCPOIDCConfig

MCPOIDCConfig is the deprecated v1alpha1 version of the MCPOIDCConfig resource.

Field	Description	Default	Validation
apiVersion string	toolhive.stacklok.dev/v1alpha1
kind string	MCPOIDCConfig
kind string	Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds		Optional: {}
apiVersion string	APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources		Optional: {}
metadata ObjectMeta	Refer to Kubernetes API documentation for fields of metadata.
spec api.v1beta1.MCPOIDCConfigSpec
status api.v1beta1.MCPOIDCConfigStatus

api.v1alpha1.MCPOIDCConfigList

MCPOIDCConfigList contains a list of MCPOIDCConfig.

Field	Description	Default	Validation
apiVersion string	toolhive.stacklok.dev/v1alpha1
kind string	MCPOIDCConfigList
kind string	Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds		Optional: {}
apiVersion string	APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources		Optional: {}
metadata ListMeta	Refer to Kubernetes API documentation for fields of metadata.
items api.v1alpha1.MCPOIDCConfig array

api.v1alpha1.MCPRegistry

MCPRegistry is the deprecated v1alpha1 version of the MCPRegistry resource. The MCPRegistry CRD as a whole 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

Field	Description	Default	Validation
apiVersion string	toolhive.stacklok.dev/v1alpha1
kind string	MCPRegistry
kind string	Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds		Optional: {}
apiVersion string	APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources		Optional: {}
metadata ObjectMeta	Refer to Kubernetes API documentation for fields of metadata.
spec api.v1beta1.MCPRegistrySpec
status api.v1beta1.MCPRegistryStatus

api.v1alpha1.MCPRegistryList

MCPRegistryList contains a list of MCPRegistry.

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

api.v1alpha1.MCPRemoteProxy

MCPRemoteProxy is the deprecated v1alpha1 version of the MCPRemoteProxy resource.

Field	Description	Default	Validation
apiVersion string	toolhive.stacklok.dev/v1alpha1
kind string	MCPRemoteProxy
kind string	Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds		Optional: {}
apiVersion string	APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources		Optional: {}
metadata ObjectMeta	Refer to Kubernetes API documentation for fields of metadata.
spec api.v1beta1.MCPRemoteProxySpec
status api.v1beta1.MCPRemoteProxyStatus

api.v1alpha1.MCPRemoteProxyList

MCPRemoteProxyList contains a list of MCPRemoteProxy.

Field	Description	Default	Validation
apiVersion string	toolhive.stacklok.dev/v1alpha1
kind string	MCPRemoteProxyList
kind string	Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds		Optional: {}
apiVersion string	APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources		Optional: {}
metadata ListMeta	Refer to Kubernetes API documentation for fields of metadata.
items api.v1alpha1.MCPRemoteProxy array

api.v1alpha1.MCPServer

MCPServer is the deprecated v1alpha1 version of the MCPServer resource.

Field	Description	Default	Validation
apiVersion string	toolhive.stacklok.dev/v1alpha1
kind string	MCPServer
kind string	Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds		Optional: {}
apiVersion string	APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources		Optional: {}
metadata ObjectMeta	Refer to Kubernetes API documentation for fields of metadata.
spec api.v1beta1.MCPServerSpec
status api.v1beta1.MCPServerStatus

api.v1alpha1.MCPServerEntry

MCPServerEntry is the deprecated v1alpha1 version of the MCPServerEntry resource.

Field	Description	Default	Validation
apiVersion string	toolhive.stacklok.dev/v1alpha1
kind string	MCPServerEntry
kind string	Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds		Optional: {}
apiVersion string	APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources		Optional: {}
metadata ObjectMeta	Refer to Kubernetes API documentation for fields of metadata.
spec api.v1beta1.MCPServerEntrySpec
status api.v1beta1.MCPServerEntryStatus

api.v1alpha1.MCPServerEntryList

MCPServerEntryList contains a list of MCPServerEntry.

Field	Description	Default	Validation
apiVersion string	toolhive.stacklok.dev/v1alpha1
kind string	MCPServerEntryList
kind string	Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds		Optional: {}
apiVersion string	APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources		Optional: {}
metadata ListMeta	Refer to Kubernetes API documentation for fields of metadata.
items api.v1alpha1.MCPServerEntry array

api.v1alpha1.MCPServerList

MCPServerList contains a list of MCPServer.

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

api.v1alpha1.MCPTelemetryConfig

MCPTelemetryConfig is the deprecated v1alpha1 version of the MCPTelemetryConfig resource.

Field	Description	Default	Validation
apiVersion string	toolhive.stacklok.dev/v1alpha1
kind string	MCPTelemetryConfig
kind string	Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds		Optional: {}
apiVersion string	APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources		Optional: {}
metadata ObjectMeta	Refer to Kubernetes API documentation for fields of metadata.
spec api.v1beta1.MCPTelemetryConfigSpec
status api.v1beta1.MCPTelemetryConfigStatus

api.v1alpha1.MCPTelemetryConfigList

MCPTelemetryConfigList contains a list of MCPTelemetryConfig.

Field	Description	Default	Validation
apiVersion string	toolhive.stacklok.dev/v1alpha1
kind string	MCPTelemetryConfigList
kind string	Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds		Optional: {}
apiVersion string	APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources		Optional: {}
metadata ListMeta	Refer to Kubernetes API documentation for fields of metadata.
items api.v1alpha1.MCPTelemetryConfig array

api.v1alpha1.MCPToolConfig

MCPToolConfig is the deprecated v1alpha1 version of the MCPToolConfig resource.

Field	Description	Default	Validation
apiVersion string	toolhive.stacklok.dev/v1alpha1
kind string	MCPToolConfig
kind string	Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds		Optional: {}
apiVersion string	APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources		Optional: {}
metadata ObjectMeta	Refer to Kubernetes API documentation for fields of metadata.
spec api.v1beta1.MCPToolConfigSpec
status api.v1beta1.MCPToolConfigStatus

api.v1alpha1.MCPToolConfigList

MCPToolConfigList contains a list of MCPToolConfig.

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

api.v1alpha1.MCPWebhookConfig

MCPWebhookConfig is the Schema for the mcpwebhookconfigs API.

Field	Description	Default	Validation
apiVersion string	toolhive.stacklok.dev/v1alpha1
kind string	MCPWebhookConfig
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.MCPWebhookConfigSpec
status api.v1beta1.MCPWebhookConfigStatus

api.v1alpha1.MCPWebhookConfigList

MCPWebhookConfigList contains a list of MCPWebhookConfig.

Field	Description	Default	Validation
apiVersion string	toolhive.stacklok.dev/v1alpha1
kind string	MCPWebhookConfigList
kind string	Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds		Optional: {}
apiVersion string	APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources		Optional: {}
metadata ListMeta	Refer to Kubernetes API documentation for fields of metadata.
items api.v1alpha1.MCPWebhookConfig array

api.v1alpha1.VirtualMCPCompositeToolDefinition

VirtualMCPCompositeToolDefinition is the deprecated v1alpha1 version of the VirtualMCPCompositeToolDefinition resource.

Field	Description	Default	Validation
apiVersion string	toolhive.stacklok.dev/v1alpha1
kind string	VirtualMCPCompositeToolDefinition
kind string	Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds		Optional: {}
apiVersion string	APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources		Optional: {}
metadata ObjectMeta	Refer to Kubernetes API documentation for fields of metadata.
spec api.v1beta1.VirtualMCPCompositeToolDefinitionSpec
status api.v1beta1.VirtualMCPCompositeToolDefinitionStatus

api.v1alpha1.VirtualMCPCompositeToolDefinitionList

VirtualMCPCompositeToolDefinitionList contains a list of VirtualMCPCompositeToolDefinition.

Field	Description	Default	Validation
apiVersion string	toolhive.stacklok.dev/v1alpha1
kind string	VirtualMCPCompositeToolDefinitionList
kind string	Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds		Optional: {}
apiVersion string	APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources		Optional: {}
metadata ListMeta	Refer to Kubernetes API documentation for fields of metadata.
items api.v1alpha1.VirtualMCPCompositeToolDefinition array

api.v1alpha1.VirtualMCPServer

VirtualMCPServer is the deprecated v1alpha1 version of the VirtualMCPServer resource.

Field	Description	Default	Validation
apiVersion string	toolhive.stacklok.dev/v1alpha1
kind string	VirtualMCPServer
kind string	Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds		Optional: {}
apiVersion string	APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources		Optional: {}
metadata ObjectMeta	Refer to Kubernetes API documentation for fields of metadata.
spec api.v1beta1.VirtualMCPServerSpec
status api.v1beta1.VirtualMCPServerStatus

api.v1alpha1.VirtualMCPServerList

VirtualMCPServerList contains a list of VirtualMCPServer.

Field	Description	Default	Validation
apiVersion string	toolhive.stacklok.dev/v1alpha1
kind string	VirtualMCPServerList
kind string	Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds		Optional: {}
apiVersion string	APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources		Optional: {}
metadata ListMeta	Refer to Kubernetes API documentation for fields of metadata.
items api.v1alpha1.VirtualMCPServer array

toolhive.stacklok.dev/v1beta1

Resource Types

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

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:

• api.v1beta1.MCPExternalAuthConfigSpec

Field	Description	Default	Validation
region string	Region is the AWS region for the STS endpoint and service (e.g., "us-east-1", "eu-west-1")		MinLength: 1 Pattern: ^[a-z]\{2\}(-[a-z]+)+-\d+$ Required: {}
service string	Service is the AWS service name for SigV4 signing Defaults to "aws-mcp" for AWS MCP Server endpoints	aws-mcp	Optional: {}
fallbackRoleArn string	FallbackRoleArn is the IAM role ARN to assume when no role mappings match Used as the default role when RoleMappings is empty or no mapping matches At least one of FallbackRoleArn or RoleMappings must be configured (enforced by webhook)		Pattern: ^arn:(aws|aws-cn|aws-us-gov):iam::\d\{12\}:role/[\w+=,.@\-_/]+$ Optional: {}
roleMappings api.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:

• api.v1beta1.MCPRemoteProxySpec
• api.v1beta1.MCPServerSpec

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

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

• api.v1beta1.MCPRemoteProxySpec
• api.v1beta1.MCPServerSpec

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

api.v1beta1.AuthServerStorageConfig

AuthServerStorageConfig configures the storage backend for the embedded auth server.

Appears in:

• api.v1beta1.EmbeddedAuthServerConfig

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:

• api.v1beta1.AuthServerStorageConfig

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:

• api.v1beta1.IncomingAuthConfig
• api.v1beta1.MCPRemoteProxySpec
• api.v1beta1.MCPServerSpec

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:

• api.v1beta1.OutgoingAuthConfig

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:

• api.v1beta1.MCPExternalAuthConfigSpec

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:

• api.v1beta1.InlineOIDCSharedConfig
• api.v1beta1.MCPServerEntrySpec
• api.v1beta1.MCPTelemetryOTelConfig

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

api.v1beta1.ConfigMapAuthzRef

ConfigMapAuthzRef references a ConfigMap containing authorization configuration

Appears in:

• api.v1beta1.AuthzConfigRef

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

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

• api.v1beta1.OAuth2UpstreamConfig

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

DiscoveredBackend is an alias to the canonical definition in pkg/vmcp/types.go This provides a local name for use in the CRD status.

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:

• api.v1beta1.EmbeddedAuthServerConfig

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:

• api.v1beta1.MCPExternalAuthConfigSpec
• api.v1beta1.VirtualMCPServerSpec

Field	Description	Default	Validation
issuer string	Issuer is the issuer identifier for this authorization server. This will be included in the "iss" claim of issued tokens. Must be a valid HTTPS URL (or HTTP for localhost, or HTTP for trusted in-cluster hosts when insecureAllowHTTP is true) 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, or HTTP for trusted in-cluster hosts when insecureAllowHTTP is true) 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: {}
disableUpstreamTokenInjection boolean	DisableUpstreamTokenInjection prevents the embedded auth server from injecting upstream IdP tokens into requests forwarded to the backend MCP server. When true, the embedded auth server still handles OAuth flows for clients, but instead of swapping ToolHive JWTs for upstream tokens the proxy STRIPS the client's credential headers (Authorization, Cookie, Proxy-Authorization) after validating the JWT — the backend receives an unauthenticated request. Use headerForward to attach static credentials (e.g. an API key) if the backend needs them. Cannot be combined with token exchange or AWS STS, which would re-add credentials after the strip. This is useful when the backend MCP server does not require authentication (e.g., public documentation servers) but you still want client authentication.	false	Optional: {}
insecureAllowHTTP boolean	InsecureAllowHTTP permits an http:// issuer URL for non-localhost hosts. Only set this for in-cluster Kubernetes deployments where traffic between pods traverses a trusted network (e.g. the in-cluster service mesh). Production deployments reachable outside the cluster MUST use https://. On VirtualMCPServer: when false (the default), http:// issuers for non-localhost hosts are rejected at reconcile time with an AuthServerConfigValidated=False condition. On MCPServer and MCPRemoteProxy (via MCPExternalAuthConfig): this field is structurally present but enforcement is deferred to pod startup via Config.Validate(); a misconfigured issuer will cause the pod to crash at startup rather than surface as an operator condition.	false	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:

• api.v1beta1.EmbeddingServerSpec

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:

• api.v1beta1.EmbeddingServerList

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:

• api.v1beta1.EmbeddingServerStatus

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

api.v1beta1.EmbeddingServerRef

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

Appears in:

• api.v1beta1.VirtualMCPServerSpec

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:

• api.v1beta1.EmbeddingServer

Field	Description	Default	Validation
model string	Model is the HuggingFace embedding model to use (e.g., "sentence-transformers/all-MiniLM-L6-v2")	BAAI/bge-small-en-v1.5	Optional: {}
hfTokenSecretRef api.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:

• api.v1beta1.EmbeddingServer

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:

• api.v1beta1.EmbeddingResourceOverrides

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

api.v1beta1.EnvVar

EnvVar represents an environment variable in a container

Appears in:

• api.v1beta1.EmbeddingServerSpec
• api.v1beta1.MCPServerSpec
• api.v1beta1.ProxyDeploymentOverrides

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:

• api.v1beta1.BackendAuthConfig
• api.v1beta1.MCPRemoteProxySpec
• api.v1beta1.MCPServerEntrySpec
• api.v1beta1.MCPServerSpec

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:

• api.v1beta1.MCPExternalAuthConfigSpec

Field	Description
tokenExchange	ExternalAuthTypeTokenExchange is the type for RFC-8693 token exchange
headerInjection	ExternalAuthTypeHeaderInjection is the type for custom header injection
bearerToken	ExternalAuthTypeBearerToken is the type for bearer token authentication This allows authenticating to remote MCP servers using bearer tokens stored in Kubernetes Secrets
unauthenticated	ExternalAuthTypeUnauthenticated is the type for no authentication This should only be used for backends on trusted networks (e.g., localhost, VPC) or when authentication is handled by network-level security
embeddedAuthServer	ExternalAuthTypeEmbeddedAuthServer is the type for embedded OAuth2/OIDC authorization server This enables running an embedded auth server that delegates to upstream IDPs
awsSts	ExternalAuthTypeAWSSts is the type for AWS STS authentication
upstreamInject	ExternalAuthTypeUpstreamInject is the type for upstream token injection This injects an upstream IdP access token as the Authorization: Bearer header
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.
xaa	ExternalAuthTypeXAA is the type for XAA (Cross-Application Access) auth. XAA performs a two-step token exchange to obtain access tokens for target services: - IdP exchange (RFC 8693): Exchange the user's ID token at their IdP for an ID-JAG JWT - Target grant (RFC 7523): Exchange the ID-JAG at the target app's AS for an access token

api.v1beta1.HeaderForwardConfig

HeaderForwardConfig defines header forward configuration for remote servers.

Appears in:

• api.v1beta1.MCPRemoteProxySpec
• api.v1beta1.MCPServerEntrySpec

Field	Description	Default	Validation
addPlaintextHeaders object (keys:string, values:string)	AddPlaintextHeaders is a map of header names to literal values to inject into requests. WARNING: Values are stored in plaintext and visible via kubectl commands. Use addHeadersFromSecret for sensitive data like API keys or tokens.		Optional: {}
addHeadersFromSecret api.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:

• api.v1beta1.HeaderForwardConfig

Field	Description	Default	Validation
headerName string	HeaderName is the HTTP header name (e.g., "X-API-Key")		MaxLength: 255 MinLength: 1 Required: {}
valueSecretRef api.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:

• api.v1beta1.MCPExternalAuthConfigSpec

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:

• api.v1beta1.OAuth2UpstreamConfig

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:

• api.v1beta1.VirtualMCPServerSpec

Field	Description	Default	Validation
type string	Type defines the authentication type: anonymous or oidc When no authentication is required, explicitly set this to "anonymous"		Enum: [anonymous oidc] Required: {}
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. AuthzConfig and AuthzConfigRef are mutually exclusive.		Optional: {}
authzConfigRef api.v1beta1.MCPAuthzConfigReference	AuthzConfigRef references a shared MCPAuthzConfig resource for authorization. The referenced MCPAuthzConfig must exist in the same namespace as this VirtualMCPServer. Mutually exclusive with authzConfig. Only cedarv1 MCPAuthzConfig resources are supported for VirtualMCPServer today; referencing a non-Cedar config fails reconciliation with a clear error because the vMCP runtime authz middleware is Cedar-only.		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:

• api.v1beta1.AuthzConfigRef

Field	Description	Default	Validation
policies string array	Policies is a list of Cedar policy strings		MinItems: 1 Required: {}
entitiesJson string	EntitiesJSON is a JSON string representing Cedar entities. 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:

• api.v1beta1.MCPOIDCConfigSpec

Field	Description	Default	Validation
issuer string	Issuer is the OIDC issuer URL		Required: {}
jwksUrl string	JWKSURL is the URL to fetch the JWKS from		Optional: {}
introspectionUrl string	IntrospectionURL is the URL for token introspection endpoint		Optional: {}
clientId string	ClientID is the OIDC client ID		Optional: {}
clientSecretRef api.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:

• api.v1beta1.MCPOIDCConfigSpec

Field	Description	Default	Validation
serviceAccount string	ServiceAccount is the name of the service account to validate tokens for. If empty, uses the pod's service account.		Optional: {}
namespace string	Namespace is the namespace of the service account. If empty, uses the MCPServer's namespace.		Optional: {}
issuer string	Issuer is the OIDC issuer URL.	https://kubernetes.default.svc	Optional: {}
jwksUrl string	JWKSURL is the URL to fetch the JWKS from. If empty, OIDC discovery will be used to automatically determine the JWKS URL.		Optional: {}
introspectionUrl string	IntrospectionURL is the URL for token introspection endpoint. If empty, OIDC discovery will be used to automatically determine the introspection URL.		Optional: {}
useClusterAuth boolean	UseClusterAuth enables using the Kubernetes cluster's CA bundle and service account token. When true, uses /var/run/secrets/kubernetes.io/serviceaccount/ca.crt for TLS verification and /var/run/secrets/kubernetes.io/serviceaccount/token for bearer token authentication. Defaults to true if not specified.		Optional: {}

api.v1beta1.MCPAuthzConfig

MCPAuthzConfig is the Schema for the mcpauthzconfigs API. MCPAuthzConfig resources are namespace-scoped and can only be referenced by MCPServer, MCPRemoteProxy, or VirtualMCPServer resources within the same namespace. Cross-namespace references are not supported for security and isolation reasons.

Appears in:

• api.v1beta1.MCPAuthzConfigList

Field	Description	Default	Validation
apiVersion string	toolhive.stacklok.dev/v1beta1
kind string	MCPAuthzConfig
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.MCPAuthzConfigSpec
status api.v1beta1.MCPAuthzConfigStatus

api.v1beta1.MCPAuthzConfigList

MCPAuthzConfigList contains a list of MCPAuthzConfig

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

api.v1beta1.MCPAuthzConfigReference

MCPAuthzConfigReference references a shared MCPAuthzConfig resource. The referenced MCPAuthzConfig must be in the same namespace as the referencing workload.

Appears in:

• api.v1beta1.IncomingAuthConfig
• api.v1beta1.MCPRemoteProxySpec
• api.v1beta1.MCPServerSpec

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

api.v1beta1.MCPAuthzConfigSpec

MCPAuthzConfigSpec defines the desired state of MCPAuthzConfig. MCPAuthzConfig resources are namespace-scoped and can only be referenced by MCPServer, MCPRemoteProxy, or VirtualMCPServer resources in the same namespace.

Appears in:

• api.v1beta1.MCPAuthzConfig

Field	Description	Default	Validation
type string	Type identifies the authorizer backend (e.g., "cedarv1", "httpv1"). Must match a registered authorizer type in the factory registry.		MinLength: 1 Required: {}
config RawExtension	Config contains the backend-specific authorization configuration. The structure depends on the Type field: - cedarv1: policies ([]string), entities_json (string), primary_upstream_provider (string), group_claim_name (string) - httpv1: http ({url, timeout, insecure_skip_verify}), context ({include_args, include_operation}), claim_mapping (string)		Type: object

api.v1beta1.MCPAuthzConfigStatus

MCPAuthzConfigStatus defines the observed state of MCPAuthzConfig

Appears in:

• api.v1beta1.MCPAuthzConfig

Field	Description	Default	Validation
conditions Condition array	Conditions represent the latest available observations of the MCPAuthzConfig's state		Optional: {}
observedGeneration integer	ObservedGeneration is the most recent generation observed for this MCPAuthzConfig.		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 MCPAuthzConfig. Each entry identifies the workload by kind and name. The map key is the (kind, name) pair so two workloads of different kinds that share a name (e.g., an MCPServer "foo" and a VirtualMCPServer "foo") are distinct entries rather than colliding under merge-patch semantics.		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:

• api.v1beta1.MCPExternalAuthConfigList

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:

• api.v1beta1.MCPExternalAuthConfig

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 xaa] 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". Setting this field on an upstream-only build causes the MCPExternalAuthConfig to transition to status.conditions[Valid] = False with Reason: EnterpriseRequired, because no OBO handler is registered. See OBOConfig for the field-to-runtime contract mapping.		Optional: {}
xaa api.v1beta1.XAASpec	XAA configures XAA (Cross-Application Access) auth for backend requests. Only used when Type is "xaa".		Optional: {}

api.v1beta1.MCPExternalAuthConfigStatus

MCPExternalAuthConfigStatus defines the observed state of MCPExternalAuthConfig

Appears in:

• api.v1beta1.MCPExternalAuthConfig

Field	Description	Default	Validation
conditions Condition array	Conditions represent the latest available observations of the MCPExternalAuthConfig's state		Optional: {}
observedGeneration integer	ObservedGeneration is the most recent generation observed for this MCPExternalAuthConfig. It corresponds to the MCPExternalAuthConfig's generation, which is updated on mutation by the API Server.		Optional: {}
configHash string	ConfigHash is a hash of the current configuration for change detection		Optional: {}
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. The map key is the (kind, name) pair so two workloads of different kinds that share a name (e.g., an MCPServer "foo" and a VirtualMCPServer "foo") are distinct entries rather than colliding under merge-patch semantics.		Optional: {}

api.v1beta1.MCPGroup

MCPGroup is the Schema for the mcpgroups API

Appears in:

• api.v1beta1.MCPGroupList

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:

• api.v1beta1.MCPGroupStatus

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

api.v1beta1.MCPGroupRef

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

Appears in:

• api.v1beta1.MCPRemoteProxySpec
• api.v1beta1.MCPServerEntrySpec
• api.v1beta1.MCPServerSpec
• api.v1beta1.VirtualMCPServerSpec

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:

• api.v1beta1.MCPGroup

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

api.v1beta1.MCPGroupStatus

MCPGroupStatus defines observed state

Appears in:

• api.v1beta1.MCPGroup

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:

• api.v1beta1.MCPOIDCConfigList

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:

• api.v1beta1.IncomingAuthConfig
• api.v1beta1.MCPRemoteProxySpec
• api.v1beta1.MCPServerSpec

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

• api.v1beta1.MCPOIDCConfigSpec

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:

• api.v1beta1.MCPOIDCConfig

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:

• api.v1beta1.MCPOIDCConfig

Field	Description	Default	Validation
conditions Condition array	Conditions represent the latest available observations of the MCPOIDCConfig's state		Optional: {}
observedGeneration integer	ObservedGeneration is the most recent generation observed for this MCPOIDCConfig.		Optional: {}
configHash string	ConfigHash is a hash of the current configuration for change detection		Optional: {}
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. The map key is the (kind, name) pair so two workloads of different kinds that share a name (e.g., an MCPServer "foo" and a VirtualMCPServer "foo") are distinct entries rather than colliding under merge-patch semantics.		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:

• api.v1beta1.MCPRegistryList

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:

• api.v1beta1.MCPRegistryStatus

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

api.v1beta1.MCPRegistrySpec

MCPRegistrySpec defines the desired state of MCPRegistry

Appears in:

• api.v1beta1.MCPRegistry

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

• api.v1beta1.MCPRegistry

Field	Description	Default	Validation
conditions Condition array	Conditions represent the latest available observations of the MCPRegistry's state		Optional: {}
observedGeneration integer	ObservedGeneration reflects the generation most recently observed by the controller		Optional: {}
phase api.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:

• api.v1beta1.MCPRemoteProxyList

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:

• api.v1beta1.MCPRemoteProxyStatus

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

api.v1beta1.MCPRemoteProxySpec

MCPRemoteProxySpec defines the desired state of MCPRemoteProxy

Appears in:

• api.v1beta1.MCPRemoteProxy

Field	Description	Default	Validation
remoteUrl string	RemoteURL is the URL of the remote MCP server to proxy		Pattern: ^https?:// Required: {}
proxyPort integer	ProxyPort is the port to expose the MCP proxy on	8080	Maximum: 65535 Minimum: 1
transport string	Transport is the transport method for the remote proxy (sse or streamable-http)	streamable-http	Enum: [sse streamable-http]
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. SECURITY: if this field is omitted and no other authentication source is configured, the proxy runs UNAUTHENTICATED. It accepts every request that can reach its port and forwards it to the remote MCP server under a synthetic local-user identity, with no token or credential check. Set this field to enforce identity-based access control per request.		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. AuthzConfig and AuthzConfigRef are mutually exclusive.		Optional: {}
authzConfigRef api.v1beta1.MCPAuthzConfigReference	AuthzConfigRef references a shared MCPAuthzConfig resource for authorization. The referenced MCPAuthzConfig must exist in the same namespace as this MCPRemoteProxy. Mutually exclusive with authzConfig.		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: {}
podTemplateSpec RawExtension	PodTemplateSpec defines the pod template to use for the MCPRemoteProxy This allows for customizing the pod configuration beyond what is provided by the other fields. Note that to modify the specific container the remote proxy runs in, you must specify the toolhive container name in the PodTemplateSpec. This field accepts a PodTemplateSpec object as JSON/YAML.		Type: object 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. Interaction with sessionStorage: when running multiple replicas with sessionStorage.provider "redis", set this to "None" so requests are distributed across replicas and sessions resolve via the shared store. Conversely, "None" without Redis-backed sessionStorage breaks session continuity — any request landing on a different pod fails with "Session not found".	ClientIP	Enum: [ClientIP None] Optional: {}
replicas integer	Replicas is the desired number of proxy pod replicas. MCPRemoteProxy creates a single Deployment for the proxy process, so there is only one replicas field (mirrors VirtualMCPServer.spec.replicas). When nil, the operator does not set Deployment.Spec.Replicas, leaving replica management to an HPA or other external controller. When set above 1, also configure sessionStorage with the redis provider and sessionAffinity: "None" so sessions resolve across replicas; otherwise a SessionStorageWarning condition is surfaced on the resource status.		Minimum: 0 Optional: {}
sessionStorage api.v1beta1.SessionStorageConfig	SessionStorage configures session storage for stateful horizontal scaling. When nil, no session storage is configured and the proxy falls back to pod-local in-memory session state — incompatible with multi-replica deployments behind load balancers that don't preserve client-IP affinity (e.g. AWS ALB across multiple AZs). The transparent proxy validates Mcp-Session-Id against this store on every non-initialize request (see pkg/transport/proxy/transparent/ transparent_proxy.go) and rewrites client-facing session IDs to backend session IDs using session metadata. Both lookups require shared state across replicas. When using the Redis provider, also set sessionAffinity to "None" so the Service routes requests round-robin and all replicas rely on the shared session store rather than pod-local state. Mirrors MCPServer.spec.sessionStorage and VirtualMCPServer.spec.sessionStorage.		Optional: {}

api.v1beta1.MCPRemoteProxyStatus

MCPRemoteProxyStatus defines the observed state of MCPRemoteProxy

Appears in:

• api.v1beta1.MCPRemoteProxy

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: {}
authzConfigHash string	AuthzConfigHash is the hash of the referenced MCPAuthzConfig spec for change detection		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:

• api.v1beta1.MCPServerList

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:

• api.v1beta1.MCPServerEntryList

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:

• api.v1beta1.MCPServerEntryStatus

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

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

• api.v1beta1.MCPServerEntry

Field	Description	Default	Validation
remoteUrl string	RemoteURL is the URL of the remote MCP server. Both HTTP and HTTPS schemes are accepted at admission time.		Pattern: ^https?:// Required: {}
transport string	Transport is the transport method for the remote server (sse or streamable-http). No default is set (unlike MCPRemoteProxy) because MCPServerEntry points at external servers the user doesn't control — requiring explicit transport avoids silent mismatches.		Enum: [sse streamable-http] Required: {}
groupRef api.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:

• api.v1beta1.MCPServerEntry

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:

• api.v1beta1.MCPServerStatus

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

api.v1beta1.MCPServerSpec

MCPServerSpec defines the desired state of MCPServer

Appears in:

• api.v1beta1.MCPServer

Field	Description	Default	Validation
image string	Image is the container image for the MCP server		Required: {}
transport string	Transport is the transport method for the MCP server (stdio, streamable-http or sse)	stdio	Enum: [stdio streamable-http sse]
proxyMode string	ProxyMode is the proxy mode for stdio transport (sse or streamable-http) This setting is ONLY applicable when Transport is "stdio". For direct transports (sse, streamable-http), this field is ignored. The default value is applied by Kubernetes but will be ignored for non-stdio transports.	streamable-http	Enum: [sse streamable-http] Optional: {}
proxyPort integer	ProxyPort is the port to expose the proxy runner on	8080	Maximum: 65535 Minimum: 1
mcpPort integer	MCPPort is the port that MCP server listens to		Maximum: 65535 Minimum: 1 Optional: {}
args string array	Args are additional arguments to pass to the MCP server		Optional: {}
env api.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. SECURITY: if this field is omitted and no other authentication source is configured, the proxy runs UNAUTHENTICATED. It accepts every request that can reach its port and forwards it to the MCP server under a synthetic local-user identity, with no token or credential check. Set this field to enforce identity-based access control per request.		Optional: {}
authzConfig api.v1beta1.AuthzConfigRef	AuthzConfig defines authorization policy configuration for the MCP server. AuthzConfig and AuthzConfigRef are mutually exclusive.		Optional: {}
authzConfigRef api.v1beta1.MCPAuthzConfigReference	AuthzConfigRef references a shared MCPAuthzConfig resource for authorization. The referenced MCPAuthzConfig must exist in the same namespace as this MCPServer. Mutually exclusive with authzConfig.		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:

• api.v1beta1.MCPServer

Field	Description	Default	Validation
conditions Condition array	Conditions represent the latest available observations of the MCPServer's state		Optional: {}
observedGeneration integer	ObservedGeneration reflects the generation most recently observed by the controller		Optional: {}
toolConfigHash string	ToolConfigHash stores the hash of the referenced ToolConfig for change detection		Optional: {}
externalAuthConfigHash string	ExternalAuthConfigHash is the hash of the referenced MCPExternalAuthConfig spec		Optional: {}
authServerConfigHash string	AuthServerConfigHash is the hash of the referenced authServerRef spec, used to detect configuration changes and trigger reconciliation.		Optional: {}
authzConfigHash string	AuthzConfigHash is the hash of the referenced MCPAuthzConfig spec for change detection		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:

• api.v1beta1.MCPTelemetryConfigList

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:

• api.v1beta1.MCPRemoteProxySpec
• api.v1beta1.MCPServerSpec
• api.v1beta1.VirtualMCPServerSpec

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

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

• api.v1beta1.MCPTelemetryConfig

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:

• api.v1beta1.MCPTelemetryConfig

Field	Description	Default	Validation
conditions Condition array	Conditions represent the latest available observations of the MCPTelemetryConfig's state		Optional: {}
observedGeneration integer	ObservedGeneration is the most recent generation observed for this MCPTelemetryConfig.		Optional: {}
configHash string	ConfigHash is a hash of the current configuration for change detection		Optional: {}
referencingWorkloads api.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:

• api.v1beta1.MCPTelemetryConfigSpec

Field	Description	Default	Validation
enabled boolean	Enabled controls whether OpenTelemetry is enabled	false	Optional: {}
endpoint string	Endpoint is the OTLP endpoint URL for tracing and metrics		Optional: {}
insecure boolean	Insecure indicates whether to use HTTP instead of HTTPS for the OTLP endpoint	false	Optional: {}
headers object (keys:string, values:string)	Headers contains authentication headers for the OTLP endpoint. For secret-backed credentials, use sensitiveHeaders instead.		Optional: {}
sensitiveHeaders api.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:

• api.v1beta1.MCPToolConfigList

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:

• api.v1beta1.MCPToolConfig

Field	Description	Default	Validation
toolsFilter string array	ToolsFilter is a list of tool names to filter (allow list). Only tools in this list will be exposed by the MCP server. If empty, all tools are exposed.		Optional: {}
toolsOverride object (keys:string, values:api.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:

• api.v1beta1.MCPToolConfig

Field	Description	Default	Validation
conditions Condition array	Conditions represent the latest available observations of the MCPToolConfig's state		Optional: {}
observedGeneration integer	ObservedGeneration is the most recent generation observed for this MCPToolConfig. It corresponds to the MCPToolConfig's generation, which is updated on mutation by the API Server.		Optional: {}
configHash string	ConfigHash is a hash of the current configuration for change detection		Optional: {}
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:

• api.v1beta1.EmbeddingServerSpec

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

api.v1beta1.NetworkPermissions

NetworkPermissions defines the network permissions for an MCP server

Appears in:

• api.v1beta1.PermissionProfileSpec

Field	Description	Default	Validation
mode string	Mode specifies the network mode for the container (e.g., "host", "bridge", "none") When empty, the default container runtime network mode is used		Optional: {}
outbound api.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:

• api.v1beta1.UpstreamProviderConfig

Field	Description	Default	Validation
authorizationEndpoint string	AuthorizationEndpoint is the URL for the OAuth authorization endpoint.		Pattern: ^https?://.*$ Required: {}
tokenEndpoint string	TokenEndpoint is the URL for the OAuth token endpoint.		Pattern: ^https?://.*$ Required: {}
userInfo api.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 holds configuration for the On-Behalf-Of (OBO) external auth type. Only used when Type is "obo".

This is the user-facing CRD surface for the Microsoft Entra OBO flow. It is structurally valid in upstream (OSS) builds but inert: an upstream-only build returns obo.ErrEnterpriseRequired at reconcile (Valid=False, Reason: EnterpriseRequired) because no OBO handler is registered via controllerutil.RegisterOBOHandler. A build with the enterprise OBO handler translates these fields into the runtime wire contract obo.MiddlewareParameters, so the field names and semantics here track that contract rather than the upstream TokenExchangeConfig (which uses different names, e.g. subjectProviderName / externalTokenHeaderName). In particular there is no externalTokenHeaderName: the OBO subject is sourced from the authenticated Identity, never from an inbound request header.

Field-to-contract mapping performed by the operator's OBO handler:

• tenantId (+ optional authority) → tokenUrl (https://login.microsoftonline.com//oauth2/v2.0/token, or the configured authority base joined with the tenant for sovereign clouds)
• clientSecretRef → resolved into a pod env var; only the env var name travels in the contract, as clientSecretEnvVar
• audience / scopes → collapsed to a single exchange target by obo.MiddlewareParameters.ExchangeTarget() (space-joined scopes win, otherwise audience)
• cacheSkew → the contract's integer-seconds cacheSkewSeconds

Every field is optional at the CRD level, and the schema deliberately carries no required field and no cross-field CEL rule. spec.obo shipped as an empty placeholder ({}) in earlier releases, so adding a required field or an admission rule that rejects {} would be a backward-incompatible narrowing of an already-stored, round-trippable object. Presence and combination requirements — a tenant, a client-auth credential, and at least one of audience/scopes — are therefore enforced by the registered OBO handler at reconcile, which reports a violation as Valid=False / Reason=InvalidConfig. The per-field patterns below still apply, but only to a value that is present.

Appears in:

• api.v1beta1.MCPExternalAuthConfigSpec

Field	Description	Default	Validation
tenantId string	TenantID is the Microsoft Entra (Azure AD) directory (tenant) identifier. Optional at the CRD level (see the type doc); the operator enforces its presence, since an OBO confidential-client exchange must target a specific tenant. When set, it must be one of the two forms the Entra v2.0 token endpoint addresses: a directory GUID, or a verified domain name (e.g. contoso.onmicrosoft.com). Well-known aliases such as "common", "organizations", and "consumers" are NOT accepted. The operator interpolates it into the token endpoint (//oauth2/v2.0/token), so the value is constrained to the GUID/domain shape (no path metacharacters); the pattern and 253-char cap mirror the enterprise exchanger's validateTenant, so any tenantId admitted here is one the runtime can consume.		MaxLength: 253 Pattern: ^([0-9a-fA-F]\{8\}-[0-9a-fA-F]\{4\}-[0-9a-fA-F]\{4\}-[0-9a-fA-F]\{4\}-[0-9a-fA-F]\{12\}|([a-zA-Z0-9]([a-zA-Z0-9-]\{0,61\}[a-zA-Z0-9])?\.)+[a-zA-Z]\{2,\})$ Optional: {}
authority string	Authority overrides the default Entra login host (https://login.microsoftonline.com) for sovereign or national clouds, e.g. https://login.microsoftonline.us (US Gov) or https://login.partner.microsoftonline.cn (China). When set, the operator builds the token endpoint by joining , , and the v2.0 token path. Must be an HTTPS URL with no userinfo, query, fragment, or trailing slash; a path IS permitted and is prefixed before the tenant segment, as some sovereign / B2C / CIAM endpoints require. The OBO exchange POSTs the client secret and the end-user assertion to this host, so it is a credential trust boundary: HTTPS is required and userinfo (user@host) is rejected to prevent host confusion (per RFC 3986 the real host follows the "@", so https://login.microsoftonline.com@attacker.example targets attacker.example). This is intentionally stricter than the downstream exchanger's validateHTTPSURL, which also accepts http for loopback hosts and tolerates a trailing slash — rejecting those at admission is the safe direction.		Pattern: ^https://[^\s?#@]+[^/\s?#@]$ Optional: {}
clientId string	ClientID is the confidential client's application (client) ID registered in Entra. Emitted verbatim as the runtime contract's clientId. Optional at the CRD level so future client-authentication methods (e.g. certificate or workload-identity credentials, planned fast-follows) can be added without a breaking schema change. The operator enforces that clientId and clientSecretRef are both present for the v1 shared-secret flow.		Optional: {}
clientSecretRef api.v1beta1.SecretKeyRef	ClientSecretRef references a Kubernetes Secret containing the confidential client's secret. v1 supports a shared client secret only. The operator injects the resolved value into the proxyrunner pod as an environment variable and emits only that variable's name in the runtime contract, as clientSecretEnvVar — the secret value never travels in the contract. Optional at the CRD level for the same forward-compatibility reason as clientId (a certificate/workload-identity flow needs no client secret); the operator enforces presence for the v1 shared-secret flow.		Optional: {}
audience string	Audience is the backend target identifier requested in the exchanged token. Used as the exchange target when Scopes is empty. At least one of audience or scopes must be set; the operator enforces that at reconcile (it is not an admission-time rule — see the type doc).		Optional: {}
scopes string array	Scopes are the delegated scopes to request for the exchanged token, e.g. ["api:///.default"]. When non-empty they take precedence over Audience. At least one of audience or scopes must be set; the operator enforces that at reconcile. The MaxItems and per-item length caps are defensive bounds on an otherwise unbounded list.		MaxItems: 20 items:MaxLength: 256 items:MinLength: 1 Optional: {}
subjectTokenProviderName string	SubjectTokenProviderName selects the source of the OBO subject (assertion) token from the request's authenticated Identity: - Omitted: use the inbound end-user token the client presented (Identity.Token) — the deployment with no embedded auth server, where the client holds an Entra token directly. - Set: use the named upstream provider's token (Identity.UpstreamTokens[]) — the embedded-auth-server deployment, where the inbound token is the proxy's own session token. The value must match a configured upstream provider name. The subject is always sourced from the authenticated Identity, never from an inbound request header, so the upstream auth middleware must run first.		MaxLength: 63 MinLength: 1 Pattern: ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$ Optional: {}
cacheSkew Duration	CacheSkew overrides the OBO token cache's default expiry skew (the margin by which a cached token is treated as expired before its real expiry), e.g. "30s". The operator converts it to the runtime contract's integer-seconds cacheSkewSeconds. Should not be negative, but the schema does not enforce that — metav1.Duration carries no numeric minimum — and upstream builds do not reject it. A negative value is rejected only by an enterprise build's OBO handler once that handler validates the converted parameters; it is not enforced at admission or in upstream-only builds. When omitted, the cache default applies.		Optional: {}

api.v1beta1.OIDCUpstreamConfig

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

Appears in:

• api.v1beta1.UpstreamProviderConfig

Field	Description	Default	Validation
issuerUrl string	IssuerURL is the OIDC issuer URL for automatic endpoint discovery. Must be a valid HTTPS URL.		Pattern: ^https://.*$ Required: {}
clientId string	ClientID is the OAuth 2.0 client identifier registered with the upstream IdP.		Required: {}
clientSecretRef api.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: {}
subjectClaim string	SubjectClaim names the validated ID-token claim to use as the upstream subject. Defaults to "sub" when empty. Set it for IdPs where "sub" isn't stable per user — e.g. Entra/Azure AD, whose "sub" rotates per application and whose stable identifier is "oid". The value is looked up verbatim as a top-level claim name, so it is constrained to a claim-name shape: it must start with a letter or underscore and contain only letters, digits, and underscores. This rejects dotted, colon-namespaced, or whitespace-containing values at admission rather than letting a typo silently miss the claim at login, and keeps the field aligned with the directory service's per-issuer bindingClaim. Changing this on a live deployment re-keys existing users (the value resolves to the internal user ID), so treat it as immutable once users exist. Per-IdP notes: - Entra/Azure AD: use "oid"; it is only emitted when the upstream scopes include "profile". "oid" is unique within a single tenant — multi-tenant apps need oid+tid, which this single-claim field cannot express. - Okta: the org auth server already puts the stable id in "sub" (default works). A custom auth server's "sub" is the mutable login/email and the stable "uid" lives only in the access token, not the ID token — map a custom ID-token claim and point subjectClaim at it. The pattern matches the claim-name shape and allows empty (defaults to "sub"). Using Pattern rather than a CEL XValidation rule keeps this off the CRD's CEL cost budget — a single-field format check via CEL is rejected by the apiserver as too expensive once multiplied across the upstreams list.		MaxLength: 128 Pattern: ^([a-zA-Z_][a-zA-Z0-9_]*)?$ Optional: {}

api.v1beta1.OpenTelemetryMetricsConfig

OpenTelemetryMetricsConfig defines OpenTelemetry metrics configuration

Appears in:

• api.v1beta1.MCPTelemetryOTelConfig

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:

• api.v1beta1.MCPTelemetryOTelConfig

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:

• api.v1beta1.NetworkPermissions

Field	Description	Default	Validation
insecureAllowAll boolean	InsecureAllowAll allows all outbound network connections (not recommended)	false	Optional: {}
allowHost string array	AllowHost is a list of hosts to allow connections to		Optional: {}
allowPort integer array	AllowPort is a list of ports to allow connections to		Optional: {}

api.v1beta1.OutgoingAuthConfig

OutgoingAuthConfig configures authentication from Virtual MCP to backend MCPServers

Appears in:

• api.v1beta1.VirtualMCPServerSpec

Field	Description	Default	Validation
source string	Source defines how backend authentication configurations are determined - discovered: Automatically discover from backend's MCPServer.spec.externalAuthConfigRef - inline: Explicit per-backend configuration in VirtualMCPServer	discovered	Enum: [discovered inline] Optional: {}
default api.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:

• api.v1beta1.MCPServerSpec

Field	Description	Default	Validation
type string	Type is the type of permission profile reference	builtin	Enum: [builtin configmap]
name string	Name is the name of the permission profile If Type is "builtin", Name must be one of: "none", "network" If Type is "configmap", Name is the name of the ConfigMap		Required: {}
key string	Key is the key in the ConfigMap that contains the permission profile Only used when Type is "configmap"		Optional: {}

api.v1beta1.PermissionProfileSpec

PermissionProfileSpec defines the permissions for an MCP server

Field	Description	Default	Validation
read string array	Read is a list of paths that the MCP server can read from		Optional: {}
write string array	Write is a list of paths that the MCP server can write to		Optional: {}
network api.v1beta1.NetworkPermissions	Network defines the network permissions for the MCP server		Optional: {}

api.v1beta1.PrometheusConfig

PrometheusConfig defines Prometheus-specific configuration

Appears in:

• api.v1beta1.MCPTelemetryConfigSpec

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:

• api.v1beta1.ResourceOverrides

Field	Description	Default	Validation
annotations object (keys:string, values:string)	Annotations to add or override on the resource		Optional: {}
labels object (keys:string, values:string)	Labels to add or override on the resource		Optional: {}
podTemplateMetadataOverrides api.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.RateLimitBucket

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

api.v1beta1.RateLimitConfig

RateLimitConfig defines rate limiting configuration for an MCP server.

api.v1beta1.RedisACLUserConfig

RedisACLUserConfig configures Redis ACL user authentication.

Appears in:

• api.v1beta1.RedisStorageConfig

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:

• api.v1beta1.RedisStorageConfig

Field	Description	Default	Validation
masterName string	MasterName is the name of the Redis master monitored by Sentinel.		Required: {}
sentinelAddrs string array	SentinelAddrs is a list of Sentinel host:port addresses. Mutually exclusive with SentinelService.		Optional: {}
sentinelService api.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:

• api.v1beta1.AuthServerStorageConfig

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:

• api.v1beta1.RedisStorageConfig

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:

• api.v1beta1.ResourceRequirements

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

api.v1beta1.ResourceMetadataOverrides

ResourceMetadataOverrides defines metadata overrides for a resource

Appears in:

• api.v1beta1.EmbeddingResourceOverrides
• api.v1beta1.EmbeddingStatefulSetOverrides
• api.v1beta1.ProxyDeploymentOverrides
• api.v1beta1.ResourceOverrides

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

api.v1beta1.ResourceOverrides

ResourceOverrides defines overrides for annotations and labels on created resources

Appears in:

• api.v1beta1.MCPRemoteProxySpec
• api.v1beta1.MCPServerSpec

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:

• api.v1beta1.EmbeddingServerSpec
• api.v1beta1.MCPRemoteProxySpec
• api.v1beta1.MCPServerSpec

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:

• api.v1beta1.AWSStsConfig

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

api.v1beta1.SecretKeyRef

SecretKeyRef is a reference to a key within a Secret

Appears in:

• api.v1beta1.BearerTokenConfig
• api.v1beta1.DCRUpstreamConfig
• api.v1beta1.EmbeddedAuthServerConfig
• api.v1beta1.EmbeddingServerSpec
• api.v1beta1.HeaderFromSecret
• api.v1beta1.HeaderInjectionConfig
• api.v1beta1.InlineOIDCSharedConfig
• api.v1beta1.OAuth2UpstreamConfig
• api.v1beta1.OBOConfig
• api.v1beta1.OIDCUpstreamConfig
• api.v1beta1.RedisACLUserConfig
• api.v1beta1.RedisTLSConfig
• api.v1beta1.SensitiveHeader
• api.v1beta1.SessionStorageConfig
• api.v1beta1.TokenExchangeConfig
• api.v1beta1.WebhookSpec
• api.v1beta1.WebhookTLSConfig
• api.v1beta1.XAASpec

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:

• api.v1beta1.MCPServerSpec

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

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

• api.v1beta1.MCPTelemetryOTelConfig

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: struct{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.RedisSentinelConfig

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:

• api.v1beta1.MCPRemoteProxySpec
• api.v1beta1.MCPServerSpec
• api.v1beta1.VirtualMCPServerSpec

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

• api.v1beta1.MCPExternalAuthConfigSpec

Field	Description	Default	Validation
tokenUrl string	TokenURL is the OAuth 2.0 token endpoint URL for token exchange		Required: {}
clientId string	ClientID is the OAuth 2.0 client identifier Optional for some token exchange flows (e.g., Google Cloud Workforce Identity)		Optional: {}
clientSecretRef api.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:

• api.v1beta1.EmbeddedAuthServerConfig

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

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

• api.v1beta1.OAuth2UpstreamConfig

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

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

• api.v1beta1.ToolOverride

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

api.v1beta1.ToolConfigRef

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

Appears in:

• api.v1beta1.MCPRemoteProxySpec
• api.v1beta1.MCPServerSpec

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:

• api.v1beta1.MCPToolConfigSpec

Field	Description	Default	Validation
name string	Name is the redefined name of the tool		Optional: {}
description string	Description is the redefined description of the tool		Optional: {}
annotations api.v1beta1.ToolAnnotationsOverride	Annotations overrides specific tool annotation fields. Only specified fields are overridden; others pass through from the backend.		Optional: {}

api.v1beta1.ToolRateLimitConfig

ToolRateLimitConfig defines rate limits for a specific tool.

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:

• api.v1beta1.MCPExternalAuthConfigSpec

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

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

• api.v1beta1.EmbeddedAuthServerConfig

Field	Description	Default	Validation
name string	Name uniquely identifies this upstream provider. Used for routing decisions and session binding in multi-upstream scenarios. Must be lowercase alphanumeric with hyphens (DNS-label-like).		MaxLength: 63 MinLength: 1 Pattern: ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$ Required: {}
type api.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:

• api.v1beta1.UpstreamProviderConfig

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

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

• api.v1beta1.OAuth2UpstreamConfig
• api.v1beta1.OIDCUpstreamConfig

Field	Description	Default	Validation
endpointUrl string	EndpointURL is the URL of the userinfo endpoint.		Pattern: ^https?://.*$ Required: {}
httpMethod string	HTTPMethod is the HTTP method to use for the userinfo request. If not specified, defaults to GET.		Enum: [GET POST] Optional: {}
additionalHeaders object (keys:string, values:string)	AdditionalHeaders contains extra headers to include in the userinfo request. Useful for providers that require specific headers (e.g., GitHub's Accept header).		Optional: {}
fieldMapping api.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: struct{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.UserInfoConfig

api.v1beta1.ValidationStatus

Underlying type: string

ValidationStatus represents the validation state of a workflow

Validation:

• Enum: [Valid Invalid Unknown]

Appears in:

• api.v1beta1.VirtualMCPCompositeToolDefinitionStatus

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

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

• api.v1beta1.VirtualMCPCompositeToolDefinitionList

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:

• api.v1beta1.VirtualMCPCompositeToolDefinition

Field	Description	Default	Validation
name string	Name is the workflow name (unique identifier).
description string	Description describes what the workflow does.
parameters pkg.json.Map	Parameters defines input parameter schema in JSON Schema format. Should be a JSON Schema object with "type": "object" and "properties". Example: { "type": "object", "properties": { "param1": {"type": "string", "default": "value"}, "param2": {"type": "integer"} }, "required": ["param2"] } We use json.Map rather than a typed struct because JSON Schema is highly flexible with many optional fields (default, enum, minimum, maximum, pattern, items, additionalProperties, oneOf, anyOf, allOf, etc.). Using json.Map allows full JSON Schema compatibility without needing to define every possible field, and matches how the MCP SDK handles inputSchema.		Type: object 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:

• api.v1beta1.VirtualMCPCompositeToolDefinition

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:

• api.v1beta1.VirtualMCPServerList

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:

• api.v1beta1.VirtualMCPServerStatus

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

api.v1beta1.VirtualMCPServerSpec

VirtualMCPServerSpec defines the desired state of VirtualMCPServer

Appears in:

• api.v1beta1.VirtualMCPServer

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: {}
passthroughHeaders string array	PassthroughHeaders is an allowlist of incoming client request header names forwarded verbatim to all backends (e.g. an API key the backend resolves to a user). Takes precedence over config.PassthroughHeaders. Names must not be restricted headers (Host, hop-by-hop, X-Forwarded-*). Forwarded headers are attacker-influenceable unless a trusted upstream sets them.		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:

• api.v1beta1.VirtualMCPServer

Field	Description	Default	Validation
conditions Condition array	Conditions represent the latest available observations of the VirtualMCPServer's state		Optional: {}
observedGeneration integer	ObservedGeneration is the most recent generation observed for this VirtualMCPServer		Optional: {}
phase api.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: {}
authzConfigHash string	AuthzConfigHash is the hash of the referenced MCPAuthzConfig spec for change detection. Only populated when IncomingAuth.AuthzConfigRef is set.		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:

• api.v1beta1.MCPServerSpec

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

api.v1beta1.WebhookConfigRef

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

Appears in:

• api.v1beta1.MCPServerSpec

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:

• api.v1beta1.WebhookSpec

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:

• api.v1beta1.MCPWebhookConfigSpec

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:

• api.v1beta1.WebhookSpec

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:

• api.v1beta1.MCPAuthzConfigStatus
• api.v1beta1.MCPExternalAuthConfigStatus
• api.v1beta1.MCPOIDCConfigStatus
• api.v1beta1.MCPTelemetryConfigStatus
• api.v1beta1.MCPToolConfigStatus
• api.v1beta1.MCPWebhookConfigStatus

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

api.v1beta1.XAASpec

XAASpec holds configuration for the XAA (Cross-Application Access) auth strategy. XAA implements draft-ietf-oauth-identity-assertion-authz-grant (ID-JAG) — a two-step token exchange to obtain access tokens for target services:

• IdP exchange (RFC 8693): Exchange the user's ID token at their IdP for an ID-JAG JWT
• Target grant (RFC 7523): Exchange the ID-JAG at the target app's AS for an access token

Appears in:

• api.v1beta1.MCPExternalAuthConfigSpec

Field	Description	Default	Validation
idpTokenUrl string	IDPTokenURL is the IdP token endpoint for IdP exchange (RFC 8693). Must be a valid HTTPS URL.		Pattern: ^https://.*$ Required: {}
idpClientId string	IDPClientID is the OAuth client ID at the IdP for IdP exchange.		Optional: {}
idpClientSecretRef api.v1beta1.SecretKeyRef	IDPClientSecretRef references a Kubernetes Secret containing the IdP client secret.		Optional: {}
targetTokenUrl string	TargetTokenURL is the target AS token endpoint for target grant (RFC 7523).		Required: {}
insecureTargetTokenUrl boolean	InsecureTargetTokenURL allows plain HTTP for TargetTokenURL. WARNING: this is insecure and must only be set for in-cluster or development/testing endpoints — never in production.		Optional: {}
targetClientId string	TargetClientID is the OAuth client ID at the target AS for target grant. ID-JAG draft §9.1 RECOMMENDS confidential clients for target grant; most conformant target authorization servers will reject an unauthenticated JWT-bearer grant per the §4.4.1 client_id continuity requirement.		Optional: {}
targetClientSecretRef api.v1beta1.SecretKeyRef	TargetClientSecretRef references a Kubernetes Secret for the target AS client secret.		Optional: {}
targetAudience string	TargetAudience is the resource AS URL for the ID-JAG audience claim.		Required: {}
targetResource string	TargetResource is the RFC 8707 resource indicator sent as the resource parameter in IdP exchange (RFC 8693, draft §4.3, OPTIONAL). It identifies the target resource server — not the access-token audience, which is governed by TargetAudience. For MCP backends, set to the MCP server URL. Some authorization servers (e.g. Okta's early ID-JAG implementation) require this parameter in practice despite the draft marking it optional — set it when your IdP needs it.		Optional: {}
scopes string array	Scopes are the requested scopes for the XAA exchange (IdP exchange and target grant).		Optional: {}
subjectProviderName string	SubjectProviderName selects which upstream provider's ID token to use. When left empty and an embedded authorization server is configured, the controller automatically populates this field with the first configured upstream provider name.		Optional: {}
subjectTokenType string	SubjectTokenType is the token-type URN of the upstream subject token used in IdP exchange. Defaults to "urn:ietf:params:oauth:token-type:id_token" when empty.		Enum: [urn:ietf:params:oauth:token-type:id_token] Optional: {}

toolhive.stacklok.dev/vmcp

pkg.vmcp.ConflictResolutionStrategy

Underlying type: string

ConflictResolutionStrategy defines how to handle capability name conflicts. Placed in vmcp root package to be shared by config and aggregator packages.

Appears in:

• vmcp.config.AggregationConfig

Field	Description
prefix	ConflictStrategyPrefix prefixes all tools with workload identifier.
priority	ConflictStrategyPriority uses explicit priority ordering (first wins).
manual	ConflictStrategyManual requires explicit overrides for all conflicts.

pkg.vmcp.DiscoveredBackend

DiscoveredBackend represents a backend server discovered by vMCP runtime. This type is shared with the Kubernetes operator CRD (VirtualMCPServer.Status.DiscoveredBackends).

Field	Description	Default	Validation
name string	Name is the name of the backend MCPServer
url string	URL is the URL of the backend MCPServer		Optional: {}
status string	Status is the current status of the backend (ready, degraded, unavailable, unauthenticated, unknown). Use BackendHealthStatus.ToCRDStatus() to populate this field.		Optional: {}
authConfigRef string	AuthConfigRef is the name of the discovered MCPExternalAuthConfig (if any)		Optional: {}
authType string	AuthType is the type of authentication configured		Optional: {}
lastHealthCheck Time	LastHealthCheck is the timestamp of the last health check		Optional: {}
message string	Message provides additional information about the backend status		Optional: {}
circuitBreakerState string	CircuitBreakerState is the current circuit breaker state (closed, open, half-open). Empty when circuit breaker is disabled or not configured.		Enum: [closed open half-open] Optional: {}
circuitLastChanged Time	CircuitLastChanged is the timestamp when the circuit breaker state last changed. Empty when circuit breaker is disabled or has never changed state.		Optional: {}
consecutiveFailures integer	ConsecutiveFailures is the current count of consecutive health check failures. Resets to 0 when the backend becomes healthy again.		Optional: {}