Skip to content

Latest commit

 

History

History
2068 lines (1135 loc) · 89.2 KB

crd-api.md

File metadata and controls

2068 lines (1135 loc) · 89.2 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 pass_through service_account external_auth_config_ref]
Required: {}
serviceAccount ServiceAccountAuth ServiceAccount configures service account authentication
Only used when Type is "service_account"
externalAuthConfigRef ExternalAuthConfigRef ExternalAuthConfigRef references an MCPExternalAuthConfig resource
Only used when Type is "external_auth_config_ref"

CapabilitiesSummary

CapabilitiesSummary summarizes aggregated capabilities

Appears in:

Field Description Default Validation
toolCount integer ToolCount is the total number of tools exposed
resourceCount integer ResourceCount is the total number of resources exposed
promptCount integer PromptCount is the total number of prompts exposed
compositeToolCount integer CompositeToolCount is the number of composite tools defined

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 object (keys:string, values:ParameterSpec) Parameters defines the input parameters for the composite tool
steps WorkflowStep array Steps defines the workflow steps MinItems: 1
Required: {}
timeout string Timeout is the maximum execution time for the composite tool 30m

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

ConfigMapSource

ConfigMapSource defines ConfigMap source configuration

Appears in:

Field Description Default Validation
name string Name is the name of the ConfigMap MinLength: 1
Required: {}
key string Key is the key in the ConfigMap that contains the registry data registry.json MinLength: 1

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

Appears in:

Field Description Default Validation
name string Name is the name of the backend MCPServer Required: {}
authConfigRef string AuthConfigRef is the name of the discovered MCPExternalAuthConfig
Empty if backend has no external auth config
authType string AuthType is the type of authentication configured
status string Status is the current status of the backend Enum: [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"

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

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

IncomingAuthConfig

IncomingAuthConfig configures authentication for clients connecting to the Virtual MCP server

Appears in:

Field Description Default Validation
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
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 string Type is the type of external authentication to configure Enum: [tokenExchange]
Required: {}
tokenExchange TokenExchangeConfig TokenExchange configures RFC-8693 OAuth 2.0 Token Exchange
Only used when Type is "tokenExchange"

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

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

MCPRegistrySource

MCPRegistrySource defines the source configuration for registry data

Appears in:

Field Description Default Validation
type string Type is the type of source (configmap, git, api) configmap Enum: [configmap git api]
format string Format is the data format (toolhive, upstream) toolhive Enum: [toolhive upstream]
configmap ConfigMapSource ConfigMap defines the ConfigMap source configuration
Only used when Type is "configmap"
git GitSource Git defines the Git repository source configuration
Only used when Type is "git"
api APISource API defines the API source configuration
Only used when Type is "api"

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
source MCPRegistrySource Source defines the configuration for the registry data source Required: {}
syncPolicy SyncPolicy SyncPolicy defines the automatic synchronization behavior for the 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
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

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

MemoryCacheConfig

MemoryCacheConfig configures in-memory token caching

Appears in:

Field Description Default Validation
maxEntries integer MaxEntries is the maximum number of cache entries 1000
ttlOffset string TTLOffset is the duration before token expiry to refresh 5m

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
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
- mixed: Discover most, override specific backends		 discovered Enum: [discovered inline mixed]
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, mixed)

ParameterSpec

ParameterSpec defines a parameter for a composite tool

Appears in:

Field Description Default Validation
type string Type is the parameter type (string, integer, boolean, etc.) Required: {}
description string Description describes the parameter
default string Default is the default value for the parameter
required boolean Required indicates if the parameter is required false

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

RedisCacheConfig

RedisCacheConfig configures Redis token caching

Appears in:

Field Description Default Validation
address string Address is the Redis server address Required: {}
db integer DB is the Redis database number 0
keyPrefix string KeyPrefix is the prefix for cache keys vmcp:tokens:
passwordRef SecretKeyRef PasswordRef references a secret containing the Redis password
tls boolean TLS enables TLS for Redis connections false

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

ServiceAccountAuth

ServiceAccountAuth defines service account authentication

Appears in:

Field Description Default Validation
credentialsRef SecretKeyRef CredentialsRef references a secret containing the service account credentials Required: {}
headerName string HeaderName is the HTTP header name for the credentials Authorization
headerFormat string HeaderFormat is the format string for the header value
Use {token} as placeholder for the credential value		 Bearer {token}

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

TokenCacheConfig

TokenCacheConfig configures token caching behavior

Appears in:

Field Description Default Validation
provider string Provider defines the cache provider type memory Enum: [memory redis]
memory MemoryCacheConfig Memory configures in-memory token caching
Only used when Provider is "memory"
redis RedisCacheConfig Redis configures Redis token caching
Only used when Provider is "redis"

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 Required: {}
clientSecretRef SecretKeyRef ClientSecretRef is a reference to a secret containing the OAuth 2.0 client secret Required: {}
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
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 object (keys:string, values:ParameterSpec) Parameters defines the input parameter schema for the workflow
Each key is a parameter name, each value is the parameter specification
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
- best_effort: Try all steps, report partial success		 abort Enum: [abort continue best_effort]

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
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
tokenCache TokenCacheConfig TokenCache configures token caching behavior
operational OperationalConfig Operational defines operational settings like timeouts and health checks
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

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
discoveredBackends DiscoveredBackend array DiscoveredBackends lists discovered backend configurations when source=discovered
capabilities CapabilitiesSummary Capabilities summarizes aggregated capabilities from all backends
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

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_call, elicitation, etc.) tool_call Enum: [tool_call elicitation]
tool string Tool is the tool to call (format: "workload.tool_name")
Only used when Type is "tool_call"
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