Skip to content

crd-api.md

Latest commit

 

History

History
2067 lines (1144 loc) · 96.1 KB

crd-api.md

File metadata and controls

2067 lines (1144 loc) · 96.1 KB

API Reference

Packages

toolhive.stacklok.dev/v1alpha1

Package v1alpha1 contains API Schema definitions for the toolhive v1alpha1 API group

Resource Types

APIPhase

Underlying type: string

APIPhase represents the API service state

Validation:

  • Enum: [NotStarted Deploying Ready Unhealthy Error]

Appears in:

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

APISource

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

Appears in:

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

APIStatus

APIStatus provides detailed information about the API service

Appears in:

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

AggregationConfig

AggregationConfig defines tool aggregation and conflict resolution strategies

Appears in:

Field Description Default Validation
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		 prefix Enum: [prefix priority manual]
conflictResolutionConfig ConflictResolutionConfig ConflictResolutionConfig provides configuration for the chosen strategy
tools WorkloadToolConfig array Tools defines per-workload tool filtering and overrides
References existing MCPToolConfig resources

AuditConfig

AuditConfig defines audit logging configuration for the MCP server

Appears in:

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

AuthzConfigRef

AuthzConfigRef defines a reference to authorization configuration

Appears in:

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

BackendAuthConfig

BackendAuthConfig defines authentication configuration for a backend MCPServer

Appears in:

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

CircuitBreakerConfig

CircuitBreakerConfig configures circuit breaker behavior

Appears in:

Field Description Default Validation
enabled boolean Enabled controls whether circuit breaker is enabled false
failureThreshold integer FailureThreshold is the number of failures before opening the circuit 5
timeout string Timeout is the duration to wait before attempting to close the circuit 60s

CompositeToolDefinitionRef

CompositeToolDefinitionRef references a VirtualMCPCompositeToolDefinition resource

Appears in:

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

CompositeToolSpec

CompositeToolSpec defines an inline composite tool For complex workflows, reference VirtualMCPCompositeToolDefinition resources instead

Appears in:

Field Description Default Validation
name string Name is the name of the composite tool Required: {}
description string Description describes the composite tool Required: {}
parameters RawExtension Parameters defines the input parameter schema in JSON Schema format.
Should be a JSON Schema object with "type": "object" and "properties".
Per MCP specification, this should follow standard JSON Schema for tool inputSchema.
Example:
{
"type": "object",
"properties": {
"param1": {"type": "string", "default": "value"},
"param2": {"type": "integer"}
},
"required": ["param2"]
}		 Type: object
steps WorkflowStep array Steps defines the workflow steps MinItems: 1
Required: {}
timeout string Timeout is the maximum execution time for the composite tool 30m
output OutputSpec Output defines the structured output schema for the composite tool.
Specifies how to construct the final output from workflow step results.
If not specified, the workflow returns the last step's output (backward compatible).

ConfigMapAuthzRef

ConfigMapAuthzRef references a ConfigMap containing authorization configuration

Appears in:

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

ConfigMapOIDCRef

ConfigMapOIDCRef references a ConfigMap containing OIDC configuration

Appears in:

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

ConflictResolutionConfig

ConflictResolutionConfig provides configuration for conflict resolution strategies

Appears in:

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

DiscoveredBackend

DiscoveredBackend represents a discovered backend MCPServer in the MCPGroup

Appears in:

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

EnvVar

EnvVar represents an environment variable in a container

Appears in:

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

ErrorHandling

ErrorHandling defines error handling behavior for workflow steps

Appears in:

Field Description Default Validation
action string Action defines the action to take on error abort Enum: [abort continue retry]
maxRetries integer MaxRetries 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]+)?(ms|s|m))+$

ExternalAuthConfigRef

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

Appears in:

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

ExternalAuthType

Underlying type: string

ExternalAuthType represents the type of external authentication

Appears in:

Field Description
tokenExchange ExternalAuthTypeTokenExchange is the type for RFC-8693 token exchange
headerInjection ExternalAuthTypeHeaderInjection is the type for custom header injection

FailureHandlingConfig

FailureHandlingConfig configures failure handling behavior

Appears in:

Field Description Default Validation
healthCheckInterval string HealthCheckInterval is the interval between health checks 30s
unhealthyThreshold integer UnhealthyThreshold is the number of consecutive failures before marking unhealthy 3
partialFailureMode string PartialFailureMode defines behavior when some backends are unavailable
- fail: Fail entire request if any backend is unavailable
- best_effort: Continue with available backends		 fail Enum: [fail best_effort]
circuitBreaker CircuitBreakerConfig CircuitBreaker configures circuit breaker behavior

GitSource

GitSource defines Git repository source configuration

Appears in:

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

GroupRef

GroupRef references an MCPGroup resource

Appears in:

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

HeaderInjectionConfig

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

Appears in:

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

IncomingAuthConfig

IncomingAuthConfig configures authentication for clients connecting to the Virtual MCP server

Appears in:

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

InlineAuthzConfig

InlineAuthzConfig contains direct authorization configuration

Appears in:

Field Description Default Validation
policies string array Policies is a list of Cedar policy strings MinItems: 1
Required: {}
entitiesJson string EntitiesJSON is a JSON string representing Cedar entities []

InlineOIDCConfig

InlineOIDCConfig contains direct OIDC configuration

Appears in:

Field Description Default Validation
issuer string Issuer is the OIDC issuer URL Required: {}
audience string Audience is the expected audience for the token
jwksUrl string JWKSURL is the URL to fetch the JWKS from
introspectionUrl string IntrospectionURL is the URL for token introspection endpoint
clientId string ClientID is the OIDC client ID
clientSecret string ClientSecret is the client secret for introspection (optional)
Deprecated: Use ClientSecretRef instead for better security
clientSecretRef SecretKeyRef ClientSecretRef is a reference to a Kubernetes Secret containing the client secret
If both ClientSecret and ClientSecretRef are provided, ClientSecretRef takes precedence
thvCABundlePath string ThvCABundlePath is the path to CA certificate bundle file for HTTPS requests
The file must be mounted into the pod (e.g., via ConfigMap or Secret volume)
jwksAuthTokenPath string JWKSAuthTokenPath is the path to file containing bearer token for JWKS/OIDC requests
The file must be mounted into the pod (e.g., via Secret volume)
jwksAllowPrivateIP boolean JWKSAllowPrivateIP allows JWKS/OIDC endpoints on private IP addresses
Use with caution - only enable for trusted internal IDPs		 false
protectedResourceAllowPrivateIP boolean ProtectedResourceAllowPrivateIP allows protected resource endpoint on private IP addresses
Use with caution - only enable for trusted internal IDPs or testing		 false
insecureAllowHTTP boolean InsecureAllowHTTP allows HTTP (non-HTTPS) OIDC issuers for development/testing
WARNING: This is insecure and should NEVER be used in production
Only enable for local development, testing, or trusted internal networks		 false

KubernetesOIDCConfig

KubernetesOIDCConfig configures OIDC for Kubernetes service account token validation

Appears in:

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

MCPExternalAuthConfig

MCPExternalAuthConfig is the Schema for the mcpexternalauthconfigs API. MCPExternalAuthConfig resources are namespace-scoped and can only be referenced by MCPServer resources within the same namespace. Cross-namespace references are not supported for security and isolation reasons.

Appears in:

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

MCPExternalAuthConfigList

MCPExternalAuthConfigList contains a list of MCPExternalAuthConfig

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

MCPExternalAuthConfigSpec

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

Appears in:

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

MCPExternalAuthConfigStatus

MCPExternalAuthConfigStatus defines the observed state of MCPExternalAuthConfig

Appears in:

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

MCPGroup

MCPGroup is the Schema for the mcpgroups API

Appears in:

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

MCPGroupList

MCPGroupList contains a list of MCPGroup

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

MCPGroupPhase

Underlying type: string

MCPGroupPhase represents the lifecycle phase of an MCPGroup

Validation:

  • Enum: [Ready Pending Failed]

Appears in:

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

MCPGroupSpec

MCPGroupSpec defines the desired state of MCPGroup

Appears in:

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

MCPGroupStatus

MCPGroupStatus defines observed state

Appears in:

Field Description Default Validation
phase MCPGroupPhase Phase indicates current state Pending Enum: [Ready Pending Failed]
servers string array Servers lists server names in this group
serverCount integer ServerCount is the number of servers
conditions Condition array Conditions represent observations

MCPRegistry

MCPRegistry is the Schema for the mcpregistries API

Appears in:

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

MCPRegistryConfig

MCPRegistryConfig defines the configuration for a registry data source

Appears in:

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

MCPRegistryDatabaseConfig

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

Appears in:

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

MCPRegistryList

MCPRegistryList contains a list of MCPRegistry

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

MCPRegistryPhase

Underlying type: string

MCPRegistryPhase represents the phase of the MCPRegistry

Validation:

  • Enum: [Pending Ready Failed Syncing Terminating]

Appears in:

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

MCPRegistrySpec

MCPRegistrySpec defines the desired state of MCPRegistry

Appears in:

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

MCPRegistryStatus

MCPRegistryStatus defines the observed state of MCPRegistry

Appears in:

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

MCPRemoteProxy

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

Appears in:

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

MCPRemoteProxyList

MCPRemoteProxyList contains a list of MCPRemoteProxy

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

MCPRemoteProxyPhase

Underlying type: string

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

Validation:

  • Enum: [Pending Ready Failed Terminating]

Appears in:

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

MCPRemoteProxySpec

MCPRemoteProxySpec defines the desired state of MCPRemoteProxy

Appears in:

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

MCPRemoteProxyStatus

MCPRemoteProxyStatus defines the observed state of MCPRemoteProxy

Appears in:

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

MCPServer

MCPServer is the Schema for the mcpservers API

Appears in:

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

MCPServerList

MCPServerList contains a list of MCPServer

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

MCPServerPhase

Underlying type: string

MCPServerPhase is the phase of the MCPServer

Validation:

  • Enum: [Pending Running Failed Terminating]

Appears in:

Field Description
Pending MCPServerPhasePending means the MCPServer is being created
Running MCPServerPhaseRunning means the MCPServer is running
Failed MCPServerPhaseFailed means the MCPServer failed to start
Terminating MCPServerPhaseTerminating means the MCPServer is being deleted

MCPServerSpec

MCPServerSpec defines the desired state of MCPServer

Appears in:

Field Description Default Validation
image string Image is the container image for the MCP server Required: {}
transport string Transport is the transport method for the MCP server (stdio, streamable-http or sse) stdio Enum: [stdio streamable-http sse]
proxyMode string ProxyMode is the proxy mode for stdio transport (sse or streamable-http)
This setting is only used when Transport is "stdio"		 streamable-http Enum: [sse streamable-http]
port integer Port is the port to expose the MCP server on
Deprecated: Use ProxyPort instead		 8080 Maximum: 65535
Minimum: 1
targetPort integer TargetPort is the port that MCP server listens to
Deprecated: Use McpPort instead		 Maximum: 65535
Minimum: 1
proxyPort integer ProxyPort is the port to expose the proxy runner on 8080 Maximum: 65535
Minimum: 1
mcpPort integer McpPort is the port that MCP server listens to Maximum: 65535
Minimum: 1
args string array Args are additional arguments to pass to the MCP server
env EnvVar array Env are environment variables to set in the MCP server container
volumes Volume array Volumes are volumes to mount in the MCP server container
resources ResourceRequirements Resources defines the resource requirements for the MCP server container
secrets SecretRef array Secrets are references to secrets to mount in the MCP server container
serviceAccount string ServiceAccount is the name of an already existing service account to use by the MCP server.
If not specified, a ServiceAccount will be created automatically and used by the MCP server.
permissionProfile PermissionProfileRef PermissionProfile defines the permission profile to use
podTemplateSpec RawExtension PodTemplateSpec defines the pod template to use for the MCP server
This allows for customizing the pod configuration beyond what is provided by the other fields.
Note that to modify the specific container the MCP server runs in, you must specify
the mcp container name in the PodTemplateSpec.
This field accepts a PodTemplateSpec object as JSON/YAML.		 Type: object
resourceOverrides ResourceOverrides ResourceOverrides allows overriding annotations and labels for resources created by the operator
oidcConfig OIDCConfigRef OIDCConfig defines OIDC authentication configuration for the MCP server
authzConfig AuthzConfigRef AuthzConfig defines authorization policy configuration for the MCP server
audit AuditConfig Audit defines audit logging configuration for the MCP server
tools string array ToolsFilter is the filter on tools applied to the MCP server
Deprecated: Use ToolConfigRef instead
toolConfigRef ToolConfigRef ToolConfigRef references a MCPToolConfig resource for tool filtering and renaming.
The referenced MCPToolConfig must exist in the same namespace as this MCPServer.
Cross-namespace references are not supported for security and isolation reasons.
If specified, this takes precedence over the inline ToolsFilter field.
externalAuthConfigRef ExternalAuthConfigRef ExternalAuthConfigRef references a MCPExternalAuthConfig resource for external authentication.
The referenced MCPExternalAuthConfig must exist in the same namespace as this MCPServer.
telemetry TelemetryConfig Telemetry defines observability configuration for the MCP server
trustProxyHeaders boolean TrustProxyHeaders indicates whether to trust X-Forwarded-* headers from reverse proxies
When enabled, the proxy will use X-Forwarded-Proto, X-Forwarded-Host, X-Forwarded-Port,
and X-Forwarded-Prefix headers to construct endpoint URLs		 false
groupRef string GroupRef is the name of the MCPGroup this server belongs to
Must reference an existing MCPGroup in the same namespace

MCPServerStatus

MCPServerStatus defines the observed state of MCPServer

Appears in:

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

MCPToolConfig

MCPToolConfig is the Schema for the mcptoolconfigs API. MCPToolConfig resources are namespace-scoped and can only be referenced by MCPServer resources within the same namespace. Cross-namespace references are not supported for security and isolation reasons.

Appears in:

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

MCPToolConfigList

MCPToolConfigList contains a list of MCPToolConfig

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

MCPToolConfigSpec

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

Appears in:

Field Description Default Validation
toolsFilter string array ToolsFilter is a list of tool names to filter (allow list).
Only tools in this list will be exposed by the MCP server.
If empty, all tools are exposed.
toolsOverride object (keys:string, values:ToolOverride) ToolsOverride is a map from actual tool names to their overridden configuration.
This allows renaming tools and/or changing their descriptions.

MCPToolConfigStatus

MCPToolConfigStatus defines the observed state of MCPToolConfig

Appears in:

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

NameFilter

NameFilter defines name-based filtering

Appears in:

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

NetworkPermissions

NetworkPermissions defines the network permissions for an MCP server

Appears in:

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

OIDCConfigRef

OIDCConfigRef defines a reference to OIDC configuration

Appears in:

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

OpenTelemetryConfig

OpenTelemetryConfig defines pure OpenTelemetry configuration

Appears in:

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

OpenTelemetryMetricsConfig

OpenTelemetryMetricsConfig defines OpenTelemetry metrics configuration

Appears in:

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

OpenTelemetryTracingConfig

OpenTelemetryTracingConfig defines OpenTelemetry tracing configuration

Appears in:

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

OperationalConfig

OperationalConfig defines operational settings

Appears in:

Field Description Default Validation
logLevel string LogLevel sets the logging level for the Virtual MCP server.
Set to "debug" to enable debug logging. When not set, defaults to info level.		 Enum: [debug]
timeouts TimeoutConfig Timeouts configures timeout settings
failureHandling FailureHandlingConfig FailureHandling configures failure handling behavior

OutboundNetworkPermissions

OutboundNetworkPermissions defines the outbound network permissions

Appears in:

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

OutgoingAuthConfig

OutgoingAuthConfig configures authentication from Virtual MCP to backend MCPServers

Appears in:

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

OutputPropertySpec

OutputPropertySpec defines a single output property

Appears in:

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

OutputSpec

OutputSpec defines the structured output schema for a composite tool workflow

Appears in:

Field Description Default Validation
properties object (keys:string, values:OutputPropertySpec) 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

PVCSource

PVCSource defines PersistentVolumeClaim source configuration

Appears in:

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

PermissionProfileRef

PermissionProfileRef defines a reference to a permission profile

Appears in:

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

PrometheusConfig

PrometheusConfig defines Prometheus-specific configuration

Appears in:

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

ProxyDeploymentOverrides

ProxyDeploymentOverrides defines overrides specific to the proxy deployment

Appears in:

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

RegistryFilter

RegistryFilter defines include/exclude patterns for registry content

Appears in:

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

ResourceList

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

Appears in:

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

ResourceMetadataOverrides

ResourceMetadataOverrides defines metadata overrides for a resource

Appears in:

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

ResourceOverrides

ResourceOverrides defines overrides for annotations and labels on created resources

Appears in:

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

ResourceRequirements

ResourceRequirements describes the compute resource requirements

Appears in:

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

RetryPolicy

RetryPolicy defines retry behavior for workflow steps

Appears in:

Field Description Default Validation
maxRetries integer MaxRetries is the maximum number of retry attempts 3 Maximum: 10
Minimum: 1
backoffStrategy string BackoffStrategy defines the backoff strategy
- fixed: Fixed delay between retries
- exponential: Exponential backoff		 exponential Enum: [fixed exponential]
initialDelay string InitialDelay is the initial delay before first retry 1s Pattern: ^([0-9]+(\.[0-9]+)?(ms|s|m))+$
maxDelay string MaxDelay is the maximum delay between retries 30s Pattern: ^([0-9]+(\.[0-9]+)?(ms|s|m))+$
retryableErrors string array RetryableErrors defines which errors should trigger retry
If empty, all errors are retryable
Supports regex patterns

SecretKeyRef

SecretKeyRef is a reference to a key within a Secret

Appears in:

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

SecretRef

SecretRef is a reference to a secret

Appears in:

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

StorageReference

StorageReference defines a reference to internal storage

Appears in:

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

SyncPhase

Underlying type: string

SyncPhase represents the data synchronization state

Validation:

  • Enum: [Syncing Complete Failed]

Appears in:

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

SyncPolicy

SyncPolicy defines automatic synchronization behavior. When specified, enables automatic synchronization at the given interval. Manual synchronization via annotation-based triggers is always available regardless of this policy setting.

Appears in:

Field Description Default Validation
interval string Interval is the sync interval for automatic synchronization (Go duration format)
Examples: "1h", "30m", "24h"		 Pattern: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
Required: {}

SyncStatus

SyncStatus provides detailed information about data synchronization

Appears in:

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

TagFilter

TagFilter defines tag-based filtering

Appears in:

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

TelemetryConfig

TelemetryConfig defines observability configuration for the MCP server

Appears in:

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

TimeoutConfig

TimeoutConfig configures timeout settings

Appears in:

Field Description Default Validation
default string Default is the default timeout for backend requests 30s
perWorkload object (keys:string, values:string) PerWorkload defines per-workload timeout overrides

TokenExchangeConfig

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

Appears in:

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

ToolConfigRef

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

Appears in:

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

ToolOverride

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

Appears in:

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

ValidationStatus

Underlying type: string

ValidationStatus represents the validation state of a workflow

Validation:

  • Enum: [Valid Invalid Unknown]

Appears in:

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

VirtualMCPCompositeToolDefinition

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

Appears in:

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

VirtualMCPCompositeToolDefinitionList

VirtualMCPCompositeToolDefinitionList contains a list of VirtualMCPCompositeToolDefinition

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

VirtualMCPCompositeToolDefinitionSpec

VirtualMCPCompositeToolDefinitionSpec defines the desired state of VirtualMCPCompositeToolDefinition

Appears in:

Field Description Default Validation
name string Name is the workflow name exposed as a composite tool MaxLength: 64
MinLength: 1
Pattern: ^[a-z0-9]([a-z0-9_-]*[a-z0-9])?$
Required: {}
description string Description is a human-readable description of the workflow MinLength: 1
Required: {}
parameters RawExtension Parameters defines the input parameter schema for the workflow in JSON Schema format.
Should be a JSON Schema object with "type": "object" and "properties".
Per MCP specification, this should follow standard JSON Schema for tool inputSchema.
Example:
{
"type": "object",
"properties": {
"param1": {"type": "string", "default": "value"},
"param2": {"type": "integer"}
},
"required": ["param2"]
}		 Type: object
steps WorkflowStep array Steps defines the workflow step definitions
Steps are executed sequentially in Phase 1
Phase 2 will support DAG execution via dependsOn		 MinItems: 1
Required: {}
timeout string Timeout is the overall workflow timeout
Defaults to 30m if not specified		 30m Pattern: ^([0-9]+(\.[0-9]+)?(ms|s|m|h))+$
failureMode string FailureMode defines the failure handling strategy
- abort: Stop execution on first failure (default)
- continue: Continue executing remaining steps		 abort Enum: [abort continue]
output OutputSpec Output defines the structured output schema for the composite tool.
Specifies how to construct the final output from workflow step results.
If not specified, the workflow returns the last step's output (backward compatible).

VirtualMCPCompositeToolDefinitionStatus

VirtualMCPCompositeToolDefinitionStatus defines the observed state of VirtualMCPCompositeToolDefinition

Appears in:

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

VirtualMCPServer

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

Appears in:

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

VirtualMCPServerList

VirtualMCPServerList contains a list of VirtualMCPServer

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

VirtualMCPServerPhase

Underlying type: string

VirtualMCPServerPhase represents the lifecycle phase of a VirtualMCPServer

Validation:

  • Enum: [Pending Ready Degraded Failed]

Appears in:

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

VirtualMCPServerSpec

VirtualMCPServerSpec defines the desired state of VirtualMCPServer

Appears in:

Field Description Default Validation
groupRef GroupRef GroupRef references an existing MCPGroup that defines backend workloads
The referenced MCPGroup must exist in the same namespace		 Required: {}
incomingAuth IncomingAuthConfig IncomingAuth configures authentication for clients connecting to the Virtual MCP server
Must be explicitly set - use "anonymous" type when no authentication is required		 Required: {}
outgoingAuth OutgoingAuthConfig OutgoingAuth configures authentication from Virtual MCP to backend MCPServers
aggregation AggregationConfig Aggregation defines tool aggregation and conflict resolution strategies
compositeTools CompositeToolSpec array CompositeTools defines inline composite tool definitions
For complex workflows, reference VirtualMCPCompositeToolDefinition resources instead
compositeToolRefs CompositeToolDefinitionRef array CompositeToolRefs references VirtualMCPCompositeToolDefinition resources
for complex, reusable workflows
operational OperationalConfig Operational defines operational settings like timeouts and health checks
serviceType string ServiceType specifies the Kubernetes service type for the Virtual MCP server ClusterIP Enum: [ClusterIP NodePort LoadBalancer]
podTemplateSpec RawExtension PodTemplateSpec defines the pod template to use for the Virtual MCP server
This allows for customizing the pod configuration beyond what is provided by the other fields.
Note that to modify the specific container the Virtual MCP server runs in, you must specify
the 'vmcp' container name in the PodTemplateSpec.
This field accepts a PodTemplateSpec object as JSON/YAML.		 Type: object
telemetry TelemetryConfig Telemetry configures OpenTelemetry-based observability for the Virtual MCP server
including distributed tracing, OTLP metrics export, and Prometheus metrics endpoint

VirtualMCPServerStatus

VirtualMCPServerStatus defines the observed state of VirtualMCPServer

Appears in:

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

Volume

Volume represents a volume to mount in a container

Appears in:

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

WorkflowStep

WorkflowStep defines a step in a composite tool workflow

Appears in:

Field Description Default Validation
id string ID is the unique identifier for this step Required: {}
type string Type is the step type (tool, elicitation, etc.) tool Enum: [tool elicitation]
tool string Tool is the tool to call (format: "workload.tool_name")
Only used when Type is "tool"
arguments object (keys:string, values:string) Arguments is a map of argument templates
Supports Go template syntax with .params and .steps
message string Message is the elicitation message
Only used when Type is "elicitation"
schema RawExtension Schema defines the expected response schema for elicitation Type: object
dependsOn string array DependsOn lists step IDs that must complete before this step
condition string Condition is a template expression that determines if the step should execute
onError ErrorHandling OnError defines error handling behavior
timeout string Timeout is the maximum execution time for this step

WorkloadToolConfig

WorkloadToolConfig defines tool filtering and overrides for a specific workload

Appears in:

Field Description Default Validation
workload string Workload is the name of the backend MCPServer workload Required: {}
toolConfigRef ToolConfigRef ToolConfigRef references a MCPToolConfig resource for tool filtering and renaming
If specified, Filter and Overrides are ignored
filter string array Filter is an inline list of tool names to allow (allow list)
Only used if ToolConfigRef is not specified
overrides object (keys:string, values:ToolOverride) Overrides is an inline map of tool overrides
Only used if ToolConfigRef is not specified