VirtualMCPServer v1beta1 — toolhive.stacklok.dev

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

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

metadata object

spec object

VirtualMCPServerSpec defines the desired state of VirtualMCPServer

authServerConfig object

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.

authorizationEndpointBaseUrl string

AuthorizationEndpointBaseURL overrides the base URL used for the authorization_endpoint in the OAuth discovery document. When set, the discovery document will advertise `{authorizationEndpointBaseUrl}/oauth/authorize` instead of `{issuer}/oauth/authorize`. All other endpoints (token, registration, JWKS) remain derived from the issuer. This is useful when the browser-facing authorization endpoint needs to be on a different host than the issuer used for backend-to-backend calls. Must be a valid HTTPS URL (or HTTP for localhost) without query, fragment, or trailing slash.

pattern: ^https?://[^\s?#]+[^/\s?#]$

hmacSecretRefs []object

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

key string required

Key is the key within the secret

name string required

Name is the name of the secret

issuer string required

Issuer is the issuer identifier for this authorization server. This will be included in the "iss" claim of issued tokens. Must be a valid HTTPS URL (or HTTP for localhost) without query, fragment, or trailing slash (per RFC 8414).

pattern: ^https?://[^\s?#]+[^/\s?#]$

signingKeySecretRefs []object

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

key string required

Key is the key within the secret

name string required

Name is the name of the secret

storage object

Storage configures the storage backend for the embedded auth server. If not specified, defaults to in-memory storage.

redis object

Redis configures the Redis storage backend. Required when type is "redis".

aclUserConfig object required

ACLUserConfig configures Redis ACL user authentication.

passwordSecretRef object required

PasswordSecretRef references a Secret containing the Redis ACL password.

key string required

Key is the key within the secret

name string required

Name is the name of the secret

usernameSecretRef object required

UsernameSecretRef references a Secret containing the Redis ACL username.

key string required

Key is the key within the secret

name string required

Name is the name of the secret

dialTimeout string

DialTimeout is the timeout for establishing connections. Format: Go duration string (e.g., "5s", "1m").

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

readTimeout string

ReadTimeout is the timeout for socket reads. Format: Go duration string (e.g., "3s", "1m").

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

sentinelConfig object required

SentinelConfig holds Redis Sentinel configuration.

db integer

DB is the Redis database number.

format: int32

masterName string required

MasterName is the name of the Redis master monitored by Sentinel.

sentinelAddrs []string

SentinelAddrs is a list of Sentinel host:port addresses. Mutually exclusive with SentinelService.

sentinelService object

SentinelService enables automatic discovery from a Kubernetes Service. Mutually exclusive with SentinelAddrs.

name string required

Name of the Sentinel Service.

namespace string

Namespace of the Sentinel Service (defaults to same namespace).

port integer

Port of the Sentinel service.

format: int32

sentinelTls object

SentinelTLS configures TLS for connections to Sentinel instances. Presence of this field enables TLS. Omit to use plaintext. When omitted, sentinel connections use plaintext (no fallback to TLS config).

caCertSecretRef object

CACertSecretRef references a Secret containing a PEM-encoded CA certificate for verifying the server. When not specified, system root CAs are used.

key string required

Key is the key within the secret

name string required

Name is the name of the secret

insecureSkipVerify boolean

InsecureSkipVerify skips TLS certificate verification. Use when connecting to services with self-signed certificates.

tls object

TLS configures TLS for connections to the Redis/Valkey master. Presence of this field enables TLS. Omit to use plaintext.

caCertSecretRef object

CACertSecretRef references a Secret containing a PEM-encoded CA certificate for verifying the server. When not specified, system root CAs are used.

key string required

Key is the key within the secret

name string required

Name is the name of the secret

insecureSkipVerify boolean

InsecureSkipVerify skips TLS certificate verification. Use when connecting to services with self-signed certificates.

writeTimeout string

WriteTimeout is the timeout for socket writes. Format: Go duration string (e.g., "3s", "1m").

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

type string

Type specifies the storage backend type. Valid values: "memory" (default), "redis".

enum: memory, redis

tokenLifespans object

TokenLifespans configures the duration that various tokens are valid. If not specified, defaults are applied (access: 1h, refresh: 7d, authCode: 10m).

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))+$

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))+$

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))+$

upstreamProviders []object required

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

name string required

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

pattern: ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$

minLength: 1

maxLength: 63

oauth2Config object

OAuth2Config contains OAuth 2.0-specific configuration. Required when Type is "oauth2", must be nil when Type is "oidc".

additionalAuthorizationParams object

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.

authorizationEndpoint string required

AuthorizationEndpoint is the URL for the OAuth authorization endpoint.

pattern: ^https?://.*$

clientId string required

ClientID is the OAuth 2.0 client identifier registered with the upstream IDP.

clientSecretRef object

ClientSecretRef references a Kubernetes Secret containing the OAuth 2.0 client secret. Optional for public clients using PKCE instead of client secret.

key string required

Key is the key within the secret

name string required

Name is the name of the secret

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.

scopes []string

Scopes are the OAuth scopes to request from the upstream IDP.

tokenEndpoint string required

TokenEndpoint is the URL for the OAuth token endpoint.

pattern: ^https?://.*$

tokenResponseMapping object

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.

accessTokenPath string required

AccessTokenPath is the dot-notation path to the access token in the response. Example: "authed_user.access_token"

minLength: 1

expiresInPath string

ExpiresInPath is the dot-notation path to the expires_in value (in seconds). If not specified, defaults to "expires_in".

refreshTokenPath string

RefreshTokenPath is the dot-notation path to the refresh token in the response. If not specified, defaults to "refresh_token".

scopePath string

ScopePath is the dot-notation path to the scope string in the response. If not specified, defaults to "scope".

userInfo object

UserInfo contains configuration for fetching user information from the upstream provider. When omitted, 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 (e.g., MCP authorization servers per the MCP spec).

additionalHeaders object

AdditionalHeaders contains extra headers to include in the userinfo request. Useful for providers that require specific headers (e.g., GitHub's Accept header).

endpointUrl string required

EndpointURL is the URL of the userinfo endpoint.

pattern: ^https?://.*$

fieldMapping object

FieldMapping contains custom field mapping configuration for non-standard providers. If nil, standard OIDC field names are used ("sub", "name", "email").

emailFields []string

EmailFields is an ordered list of field names to try for the email address. The first non-empty value found will be used. Default: ["email"]

nameFields []string

NameFields is an ordered list of field names to try for the display name. The first non-empty value found will be used. Default: ["name"]

subjectFields []string

SubjectFields is an ordered list of field names to try for the user ID. The first non-empty value found will be used. Default: ["sub"]

httpMethod string

HTTPMethod is the HTTP method to use for the userinfo request. If not specified, defaults to GET.

enum: GET, POST

oidcConfig object

OIDCConfig contains OIDC-specific configuration. Required when Type is "oidc", must be nil when Type is "oauth2".

additionalAuthorizationParams object

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.

clientId string required

ClientID is the OAuth 2.0 client identifier registered with the upstream IDP.

clientSecretRef object

ClientSecretRef references a Kubernetes Secret containing the OAuth 2.0 client secret. Optional for public clients using PKCE instead of client secret.

key string required

Key is the key within the secret

name string required

Name is the name of the secret

issuerUrl string required

IssuerURL is the OIDC issuer URL for automatic endpoint discovery. Must be a valid HTTPS URL.

pattern: ^https://.*$

redirectUri string

scopes []string

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.

userInfoOverride object

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.

additionalHeaders object

AdditionalHeaders contains extra headers to include in the userinfo request. Useful for providers that require specific headers (e.g., GitHub's Accept header).

endpointUrl string required

EndpointURL is the URL of the userinfo endpoint.

pattern: ^https?://.*$

fieldMapping object

FieldMapping contains custom field mapping configuration for non-standard providers. If nil, standard OIDC field names are used ("sub", "name", "email").

emailFields []string

EmailFields is an ordered list of field names to try for the email address. The first non-empty value found will be used. Default: ["email"]

nameFields []string

NameFields is an ordered list of field names to try for the display name. The first non-empty value found will be used. Default: ["name"]

subjectFields []string

SubjectFields is an ordered list of field names to try for the user ID. The first non-empty value found will be used. Default: ["sub"]

httpMethod string

HTTPMethod is the HTTP method to use for the userinfo request. If not specified, defaults to GET.

enum: GET, POST

type string required

Type specifies the provider type: "oidc" or "oauth2"

enum: oidc, oauth2

config object

Config is the Virtual MCP server configuration. The audit config from here is also supported, but not required.

aggregation object

Aggregation defines tool aggregation and conflict resolution strategies. Supports ToolConfigRef for Kubernetes-native MCPToolConfig resource references.

conflictResolution string

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

enum: prefix, priority, manual

conflictResolutionConfig object

ConflictResolutionConfig provides configuration for the chosen strategy.

prefixFormat string

PrefixFormat defines the prefix format for the "prefix" strategy. Supports placeholders: {workload}, {workload}_, {workload}.

priorityOrder []string

PriorityOrder defines the workload priority order for the "priority" strategy.

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.

tools []object

Tools defines per-workload tool filtering and overrides.

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.

filter []string

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.

overrides object

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.

toolConfigRef object

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.

name string required

Name is the name of the MCPToolConfig resource in the same namespace.

workload string required

Workload is the name of the backend MCPServer workload.

audit object

Audit configures audit logging for the Virtual MCP server. When present, audit logs include MCP protocol operations. See audit.Config for available configuration options.

component string

Component is the component name to use in audit events.

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.

enabled boolean

Enabled controls whether audit logging is enabled. When true, enables audit logging with the configured options.

eventTypes []string

EventTypes specifies which event types to audit. If empty, all events are audited.

excludeEventTypes []string

ExcludeEventTypes specifies which event types to exclude from auditing. This takes precedence over EventTypes.

includeRequestData boolean

IncludeRequestData determines whether to include request data in audit logs.

includeResponseData boolean

IncludeResponseData determines whether to include response data in audit logs.

logFile string

LogFile specifies the file path for audit logs. If empty, logs to stdout.

maxDataSize integer

MaxDataSize limits the size of request/response data included in audit logs (in bytes).

backends []object

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.

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/<name>/ca.crt.

metadata object

Metadata is a custom key-value map for storing additional backend information such as labels, tags, or other arbitrary data (e.g., "env": "prod", "region": "us-east-1"). This is NOT Kubernetes ObjectMeta - it's a simple string map for user-defined metadata. Reserved keys: "group" is automatically set by vMCP and any user-provided value will be overridden.

name string required

Name is the backend identifier. Must match the backend name from the MCPGroup for auth config resolution.

transport string required

Transport is the MCP transport protocol: "sse" or "streamable-http" Only network transports supported by vMCP client are allowed.

enum: sse, streamable-http

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,

url string required

URL is the backend's MCP server base URL.

pattern: ^https?://

compositeToolRefs []object

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.

name string required

Name is the name of the VirtualMCPCompositeToolDefinition resource in the same namespace.

compositeTools []object

CompositeTools defines inline composite tool workflows. Full workflow definitions are embedded in the configuration. For Kubernetes, complex workflows can also reference VirtualMCPCompositeToolDefinition CRDs.

description string

Description describes what the workflow does.

name string required

Name is the workflow name (unique identifier).

output object

Output defines the structured output schema for this workflow. If not specified, the workflow returns the last step's output (backward compatible).

properties object required

Properties defines the output properties. Map key is the property name, value is the property definition.

required []string

Required lists property names that must be present in the output.

parameters object

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.

steps []object required

Steps are the workflow steps to execute.

arguments object

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.

collection string

Collection is a Go template expression that resolves to a JSON array or a slice. Only used when Type is "forEach".

condition string

Condition is a template expression that determines if the step should execute

defaultResults object

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.

dependsOn []string

DependsOn lists step IDs that must complete before this step

id string required

ID is the unique identifier for this step.

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

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

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

message string

Message is the elicitation message Only used when Type is "elicitation"

onCancel object

OnCancel defines the action to take when the user cancels/dismisses the elicitation Only used when Type is "elicitation"

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

enum: skip_remaining, abort, continue

onDecline object

OnDecline defines the action to take when the user explicitly declines the elicitation Only used when Type is "elicitation"

action string

enum: skip_remaining, abort, continue

onError object

OnError defines error handling behavior

action string

Action defines the action to take on error

enum: abort, continue, retry

retryCount integer

RetryCount is the maximum number of retries Only used when Action is "retry"

retryDelay string

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))+$

schema object

Schema defines the expected response schema for elicitation

step object

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.

timeout string

Timeout is the maximum execution time for this step

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

tool string

Tool is the tool to call (format: "workload.tool_name") Only used when Type is "tool"

type string

Type is the step type (tool, elicitation, etc.)

enum: tool, elicitation, forEach

timeout string

Timeout is the maximum workflow execution time.

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

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.

incomingAuth object

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.

authz object

Authz contains authorization configuration (optional).

policies []string

Policies contains Cedar policy definitions (when Type = "cedar").

primaryUpstreamProvider string

PrimaryUpstreamProvider names the upstream IDP provider whose access token should be used as the source of JWT claims for Cedar evaluation. When empty, claims from the ToolHive-issued token are used. Must match an upstream provider name configured in the embedded auth server (e.g. "default", "github"). Only relevant when the embedded auth server is active.

type string required

Type is the authz type: "cedar", "none"

oidc object

OIDC contains OIDC configuration (when Type = "oidc").

audience string required

Audience is the required token audience.

clientId string required

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.

insecureAllowHttp boolean

InsecureAllowHTTP allows HTTP (non-HTTPS) OIDC issuers for development/testing WARNING: This is insecure and should NEVER be used in production

introspectionUrl string

IntrospectionURL is the token introspection endpoint URL (RFC 7662). When set, enables token introspection for opaque (non-JWT) tokens.

issuer string required

Issuer is the OIDC issuer URL.

pattern: ^https?://

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.

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.

protectedResourceAllowPrivateIp boolean

ProtectedResourceAllowPrivateIP allows protected resource endpoint on private IP addresses Use with caution - only enable for trusted internal IDPs or testing

resource string

Resource is the OAuth 2.0 resource indicator (RFC 8707). Used in WWW-Authenticate header and OAuth discovery metadata (RFC 9728). If not specified, defaults to Audience.

scopes []string

Scopes are the required OAuth scopes.

type string required

Type is the auth type: "oidc", "local", "anonymous"

metadata object

Metadata stores additional configuration metadata.

name string

Name is the virtual MCP server name.

operational object

Operational configures operational settings.

failureHandling object

FailureHandling configures failure handling behavior.

circuitBreaker object

CircuitBreaker configures circuit breaker behavior.

enabled boolean

Enabled controls whether circuit breaker is enabled.

failureThreshold integer

FailureThreshold is the number of failures before opening the circuit. Must be >= 1.

minimum: 1

timeout string

Timeout is the duration to wait before attempting to close the circuit. Must be >= 1s to prevent thrashing.

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

healthCheckInterval string

HealthCheckInterval is the interval between health checks.

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

healthCheckTimeout string

HealthCheckTimeout is the maximum duration for a single health check operation. Should be less than HealthCheckInterval to prevent checks from queuing up.

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

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

enum: fail, best_effort

statusReportingInterval string

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.

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

unhealthyThreshold integer

UnhealthyThreshold is the number of consecutive failures before marking unhealthy.

logLevel string

LogLevel sets the logging level for the Virtual MCP server. The only valid value is "debug" to enable debug logging. When omitted or empty, the server uses info level logging.

enum: debug

timeouts object

Timeouts configures timeout settings.

default string

Default is the default timeout for backend requests.

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

perWorkload object

PerWorkload defines per-workload timeout overrides.

optimizer object

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.

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.

embeddingServiceTimeout string

EmbeddingServiceTimeout is the HTTP request timeout for calls to the embedding service. Defaults to 30s if not specified.

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

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]+$

maxToolsToReturn integer

MaxToolsToReturn is the maximum number of tool results returned by a search query. Defaults to 8 if not specified or zero.

minimum: 1

maximum: 50

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]+$

outgoingAuth object

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.

backends object

Backends contains per-backend auth configuration.

default object

Default is the default auth strategy for backends without explicit config.

awsSts object

AwsSts contains configuration for AWS STS auth strategy. Used when Type = "aws_sts".

fallbackRoleArn string

FallbackRoleArn is the IAM role ARN to assume when no role mappings match.

region string required

Region is the AWS region for the STS endpoint and service.

roleClaim string

RoleClaim is the JWT claim to use for role mapping evaluation.

roleMappings []object

RoleMappings defines claim-based role selection rules.

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.

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.

roleArn string required

RoleArn is the IAM role ARN to assume when this mapping matches.

service string

Service is the AWS service name for SigV4 signing.

sessionDuration integer

SessionDuration is the duration in seconds for the STS session.

format: int32

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.

headerInjection object

HeaderInjection contains configuration for header injection auth strategy. Used when Type = "header_injection".

headerName string required

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.

tokenExchange object

TokenExchange contains configuration for token exchange auth strategy. Used when Type = "token_exchange".

audience string

Audience is the target audience for the exchanged token.

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.

scopes []string

Scopes are the requested scopes for the exchanged token.

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.

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.

tokenUrl string required

TokenURL is the OAuth token endpoint URL for token exchange.

type string required

Type is the auth strategy: "unauthenticated", "header_injection", "token_exchange", "upstream_inject", "aws_sts"

upstreamInject object

UpstreamInject contains configuration for upstream inject auth strategy. Used when Type = "upstream_inject".

providerName string required

ProviderName is the name of the upstream provider configured in the embedded authorization server. Must match an entry in AuthServer.Upstreams.

source string required

Source defines how to discover backend auth: "inline", "discovered" - inline: Explicit configuration in OutgoingAuth - discovered: Auto-discover from backend MCPServer.externalAuthConfigRef (Kubernetes only)

sessionStorage object

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.

address string

Address is the Redis server address (required when provider is redis).

db integer

DB is the Redis database number.

format: int32

minimum: 0

keyPrefix string

KeyPrefix is an optional prefix for all Redis keys used by ToolHive.

provider string required

Provider is the session storage backend type.

enum: memory, redis

telemetry object

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.

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.

customAttributes object

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.

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.

endpoint string

Endpoint is the OTLP endpoint URL

environmentVariables []string

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"]

headers object

Headers contains authentication headers for the OTLP endpoint.

insecure boolean

Insecure indicates whether to use HTTP instead of HTTPS for the OTLP endpoint.

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.

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.

serviceName string

ServiceName is the service name for telemetry. When omitted, defaults to the server name (e.g., VirtualMCPServer name).

serviceVersion string

ServiceVersion is the service version for telemetry. When omitted, defaults to the ToolHive version.

tracingEnabled boolean

TracingEnabled controls whether distributed tracing is enabled. When false, no tracer provider is created even if an endpoint is configured.

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.

embeddingServerRef object

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.

name string required

Name is the name of the EmbeddingServer resource

groupRef object required

GroupRef references the MCPGroup that defines backend workloads. The referenced MCPGroup must exist in the same namespace.

name string required

Name is the name of the MCPGroup resource in the same namespace

minLength: 1

imagePullSecrets []object

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.

name string

Name of the referent. This field is effectively required, but due to backwards compatibility is allowed to be empty. Instances of this type with an empty value here are almost certainly wrong. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names

incomingAuth object required

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.

authzConfig object

AuthzConfig defines authorization policy configuration Reuses MCPServer authz patterns

configMap object

ConfigMap references a ConfigMap containing authorization configuration Only used when Type is "configMap"

key string

Key is the key in the ConfigMap that contains the authorization configuration

name string required

Name is the name of the ConfigMap

inline object

Inline contains direct authorization configuration Only used when Type is "inline"

entitiesJson string

EntitiesJSON is a JSON string representing Cedar entities

policies []string required

Policies is a list of Cedar policy strings

minItems: 1

type string required

Type is the type of authorization configuration

enum: configMap, inline

oidcConfigRef object

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.

audience string required

Audience is the expected audience for token validation. This MUST be unique per server to prevent token replay attacks.

minLength: 1

name string required

Name is the name of the MCPOIDCConfig resource

minLength: 1

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.

scopes []string

Scopes is the list of OAuth scopes to advertise in the well-known endpoint (RFC 9728). If empty, defaults to ["openid"].

type string required

Type defines the authentication type: anonymous or oidc When no authentication is required, explicitly set this to "anonymous"

enum: anonymous, oidc

outgoingAuth object

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.

backends object

Backends defines per-backend authentication overrides Works in all modes (discovered, inline)

default object

Default defines default behavior for backends without explicit auth config

externalAuthConfigRef object

ExternalAuthConfigRef references an MCPExternalAuthConfig resource Only used when Type is "externalAuthConfigRef"

name string required

Name is the name of the MCPExternalAuthConfig resource

type string required

Type defines the authentication type

enum: discovered, externalAuthConfigRef

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

enum: discovered, inline

podTemplateSpec object

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.

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.

format: int32

minimum: 0

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.

serviceType string

ServiceType specifies the Kubernetes service type for the Virtual MCP server

enum: ClusterIP, NodePort, LoadBalancer

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.

enum: ClientIP, None

sessionStorage object

SessionStorage configures session storage for stateful horizontal scaling. When nil, no session storage is configured.

address string

Address is the Redis server address (required when provider is redis)

minLength: 1

db integer

DB is the Redis database number

format: int32

minimum: 0

keyPrefix string

KeyPrefix is an optional prefix for all Redis keys used by ToolHive

passwordRef object

PasswordRef is a reference to a Secret key containing the Redis password

key string required

Key is the key within the secret

name string required

Name is the name of the secret

provider string required

Provider is the session storage backend type

enum: memory, redis

telemetryConfigRef object

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.

name string required

Name is the name of the MCPTelemetryConfig resource

minLength: 1

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.

status object

VirtualMCPServerStatus defines the observed state of VirtualMCPServer

backendCount integer

BackendCount is the number of routable backends (ready + unauthenticated). Excludes unavailable, degraded, and unknown backends.

format: int32

conditions []object

Conditions represent the latest available observations of the VirtualMCPServer's state

lastTransitionTime string required

lastTransitionTime is the last time the condition transitioned from one status to another. This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable.

format: date-time

message string required

message is a human readable message indicating details about the transition. This may be an empty string.

maxLength: 32768

observedGeneration integer

observedGeneration represents the .metadata.generation that the condition was set based upon. For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date with respect to the current state of the instance.

format: int64

minimum: 0

reason string required

reason contains a programmatic identifier indicating the reason for the condition's last transition. Producers of specific condition types may define expected values and meanings for this field, and whether the values are considered a guaranteed API. The value should be a CamelCase string. This field may not be empty.

pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$

minLength: 1

maxLength: 1024

status string required

status of the condition, one of True, False, Unknown.

enum: True, False, Unknown

type string required

type of condition in CamelCase or in foo.example.com/CamelCase.

pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$

maxLength: 316

discoveredBackends []object

DiscoveredBackends lists discovered backend configurations from the MCPGroup

authConfigRef string

AuthConfigRef is the name of the discovered MCPExternalAuthConfig (if any)

authType string

AuthType is the type of authentication configured

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

circuitLastChanged string

CircuitLastChanged is the timestamp when the circuit breaker state last changed. Empty when circuit breaker is disabled or has never changed state.

format: date-time

consecutiveFailures integer

ConsecutiveFailures is the current count of consecutive health check failures. Resets to 0 when the backend becomes healthy again.

lastHealthCheck string

LastHealthCheck is the timestamp of the last health check

format: date-time

message string

Message provides additional information about the backend status

name string required

Name is the name of the backend MCPServer

status string

Status is the current status of the backend (ready, degraded, unavailable, unauthenticated, unknown). Use BackendHealthStatus.ToCRDStatus() to populate this field.

url string

URL is the URL of the backend MCPServer

message string

Message provides additional information about the current phase

observedGeneration integer

ObservedGeneration is the most recent generation observed for this VirtualMCPServer

format: int64

oidcConfigHash string

OIDCConfigHash is the hash of the referenced MCPOIDCConfig spec for change detection. Only populated when IncomingAuth.OIDCConfigRef is set.

phase string

Phase is the current phase of the VirtualMCPServer

enum: Pending, Ready, Degraded, Failed

telemetryConfigHash string

TelemetryConfigHash is the hash of the referenced MCPTelemetryConfig spec for change detection. Only populated when TelemetryConfigRef is set.

url string

URL is the URL where the Virtual MCP server can be accessed