toolhive.stacklok.dev_virtualmcpservers.yaml

{{- if .Values.crds.install }}
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  annotations:
    {{- if .Values.crds.keep }}
    helm.sh/resource-policy: keep
    {{- end }}
    controller-gen.kubebuilder.io/version: v0.17.3
  labels:
    toolhive.stacklok.dev/auto-migrate-storage-version: "true"
  name: virtualmcpservers.toolhive.stacklok.dev
spec:
  group: toolhive.stacklok.dev
  names:
    categories:
    - toolhive
    kind: VirtualMCPServer
    listKind: VirtualMCPServerList
    plural: virtualmcpservers
    shortNames:
    - vmcp
    - virtualmcp
    singular: virtualmcpserver
  scope: Namespaced
  versions:
  - additionalPrinterColumns:
    - description: The phase of the VirtualMCPServer
      jsonPath: .status.phase
      name: Phase
      type: string
    - description: Virtual MCP server URL
      jsonPath: .status.url
      name: URL
      type: string
    - description: Discovered backends count
      jsonPath: .status.backendCount
      name: Backends
      type: integer
    - description: Age
      jsonPath: .metadata.creationTimestamp
      name: Age
      type: date
    - jsonPath: .status.conditions[?(@.type=='Ready')].status
      name: Ready
      type: string
    deprecated: true
    deprecationWarning: toolhive.stacklok.dev/v1alpha1 is deprecated; use v1beta1
    name: v1alpha1
    schema:
      openAPIV3Schema:
        description: VirtualMCPServer is the deprecated v1alpha1 version of the VirtualMCPServer
          resource.
        properties:
          apiVersion:
            description: |-
              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
            type: string
          kind:
            description: |-
              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
            type: string
          metadata:
            type: object
          spec:
            description: VirtualMCPServerSpec defines the desired state of VirtualMCPServer
            properties:
              authServerConfig:
                description: |-
                  AuthServerConfig configures an embedded OAuth authorization server.
                  When set, the vMCP server acts as an OIDC issuer, drives users through
                  upstream IDPs, and issues ToolHive JWTs. The embedded AS becomes the
                  IncomingAuth OIDC provider — its issuer must match IncomingAuth.OIDCConfigRef
                  so that tokens it issues are accepted by the vMCP's incoming auth middleware.
                  When nil, IncomingAuth uses an external IDP and behavior is unchanged.
                properties:
                  authorizationEndpointBaseUrl:
                    description: |-
                      AuthorizationEndpointBaseURL overrides the base URL used for the authorization_endpoint
                      in the OAuth discovery document. When set, the discovery document will advertise
                      `{authorizationEndpointBaseUrl}/oauth/authorize` instead of `{issuer}/oauth/authorize`.
                      All other endpoints (token, registration, JWKS) remain derived from the issuer.
                      This is useful when the browser-facing authorization endpoint needs to be on a
                      different host than the issuer used for backend-to-backend calls.
                      Must be a valid HTTPS URL (or HTTP for localhost) without query, fragment, or trailing slash.
                    pattern: ^https?://[^\s?#]+[^/\s?#]$
                    type: string
                  baselineClientScopes:
                    description: |-
                      BaselineClientScopes is a baseline set of OAuth 2.0 scopes guaranteed to be
                      included in every client registration. The embedded auth server unions these
                      scopes into the registered set returned by RFC 7591 Dynamic Client
                      Registration, so a client that narrows the `scope` field at /oauth/register
                      can still request the baseline scopes at /oauth/authorize. All values must
                      be present in the upstream-derived scopesSupported set; the auth server
                      fails to start if any value is missing.

                      Security: every client registered via /oauth/register will gain the
                      ability to request these scopes at /oauth/authorize, regardless of what
                      the client itself requested. Keep the baseline narrow (typically
                      "openid" and "offline_access"). Adding a privileged scope here — e.g.
                      "admin:read" — would grant it to every DCR-registered client, including
                      public clients like Claude Code, Cursor, and VS Code.
                      When cimd.enabled is true, every dynamically resolved CIMD client will
                      also gain the ability to request these scopes, including third-party
                      clients resolved from arbitrary HTTPS URLs.
                    items:
                      minLength: 1
                      pattern: ^[\x21\x23-\x5B\x5D-\x7E]+$
                      type: string
                    maxItems: 10
                    type: array
                    x-kubernetes-list-type: atomic
                  cimd:
                    description: CIMD configures Client ID Metadata Document support.
                      When omitted, CIMD is disabled.
                    properties:
                      cacheFallbackTtl:
                        description: |-
                          CacheFallbackTTL is the fixed TTL applied to every cached CIMD document.
                          Cache-Control header parsing is not yet implemented; all entries use this value.
                          Format: Go duration string (e.g. "5m", "10m", "1h").
                          Defaults to 5 minutes when Enabled is true and this field is omitted.
                        pattern: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
                        type: string
                      cacheMaxSize:
                        description: |-
                          CacheMaxSize is the maximum number of CIMD documents held in the LRU cache.
                          Defaults to 256 when Enabled is true and this field is omitted.
                        minimum: 1
                        type: integer
                      enabled:
                        default: false
                        description: |-
                          Enabled activates CIMD client lookup. When false (the default), the AS only
                          accepts client_id values that were registered via DCR.
                        type: boolean
                    required:
                    - enabled
                    type: object
                  hmacSecretRefs:
                    description: |-
                      HMACSecretRefs references Kubernetes Secrets containing symmetric secrets for signing
                      authorization codes and refresh tokens (opaque tokens).
                      Current secret must be at least 32 bytes and cryptographically random.
                      Supports secret rotation via multiple entries (first is current, rest are for verification).
                      If not specified, an ephemeral secret will be auto-generated (development only -
                      auth codes and refresh tokens will be invalid after restart).
                    items:
                      description: SecretKeyRef is a reference to a key within a Secret
                      properties:
                        key:
                          description: Key is the key within the secret
                          type: string
                        name:
                          description: Name is the name of the secret
                          type: string
                      required:
                      - key
                      - name
                      type: object
                    type: array
                    x-kubernetes-list-type: atomic
                  issuer:
                    description: |-
                      Issuer is the issuer identifier for this authorization server.
                      This will be included in the "iss" claim of issued tokens.
                      Must be a valid HTTPS URL (or HTTP for localhost) without query, fragment, or trailing slash (per RFC 8414).
                    pattern: ^https?://[^\s?#]+[^/\s?#]$
                    type: string
                  primaryUpstreamProvider:
                    description: |-
                      PrimaryUpstreamProvider names the upstream IDP whose access token Cedar
                      should read claims from when authorising a request. Must match the name
                      of one of the entries in UpstreamProviders. When empty, the controller
                      auto-selects the first entry of UpstreamProviders.

                      Only meaningful on VirtualMCPServer, where multiple upstream providers
                      can be configured and Cedar needs to pick which token's claims to
                      evaluate. The VirtualMCPServer controller validates this field against
                      UpstreamProviders at admission and rejects unresolvable values.

                      On MCPServer and MCPRemoteProxy this field is structurally present (the
                      EmbeddedAuthServerConfig struct is shared) but has no runtime effect:
                      those CRDs are restricted to a single upstream so there is no choice to
                      make. Setting it on those CRDs is silently ignored.
                    maxLength: 63
                    minLength: 1
                    pattern: ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$
                    type: string
                  signingKeySecretRefs:
                    description: |-
                      SigningKeySecretRefs references Kubernetes Secrets containing signing keys for JWT operations.
                      Supports key rotation by allowing multiple keys (oldest keys are used for verification only).
                      If not specified, an ephemeral signing key will be auto-generated (development only -
                      JWTs will be invalid after restart).
                    items:
                      description: SecretKeyRef is a reference to a key within a Secret
                      properties:
                        key:
                          description: Key is the key within the secret
                          type: string
                        name:
                          description: Name is the name of the secret
                          type: string
                      required:
                      - key
                      - name
                      type: object
                    maxItems: 5
                    type: array
                    x-kubernetes-list-type: atomic
                  storage:
                    description: |-
                      Storage configures the storage backend for the embedded auth server.
                      If not specified, defaults to in-memory storage.
                    properties:
                      redis:
                        description: |-
                          Redis configures the Redis storage backend.
                          Required when type is "redis".
                        properties:
                          aclUserConfig:
                            description: ACLUserConfig configures Redis ACL user authentication.
                            properties:
                              passwordSecretRef:
                                description: PasswordSecretRef references a Secret
                                  containing the Redis ACL password.
                                properties:
                                  key:
                                    description: Key is the key within the secret
                                    type: string
                                  name:
                                    description: Name is the name of the secret
                                    type: string
                                required:
                                - key
                                - name
                                type: object
                              usernameSecretRef:
                                description: |-
                                  UsernameSecretRef references a Secret containing the Redis ACL username.
                                  When omitted, connections use legacy password-only AUTH. Omit for managed
                                  Redis tiers that do not support ACL users (e.g. GCP Memorystore Basic/Standard
                                  HA, Azure Cache for Redis). Set for services that support ACL users (e.g. AWS
                                  ElastiCache non-cluster with Redis 6+ RBAC).
                                properties:
                                  key:
                                    description: Key is the key within the secret
                                    type: string
                                  name:
                                    description: Name is the name of the secret
                                    type: string
                                required:
                                - key
                                - name
                                type: object
                            required:
                            - passwordSecretRef
                            type: object
                          addr:
                            description: |-
                              Addr is the Redis server address (host:port). Required for standalone and cluster modes.
                              Use for managed Redis services that expose a single endpoint (GCP Memorystore basic tier,
                              AWS ElastiCache without cluster mode, or cluster-mode services when clusterMode is true).
                              Mutually exclusive with sentinelConfig.
                            type: string
                          clusterMode:
                            description: |-
                              ClusterMode enables the Redis Cluster protocol. Set to true when addr points to a
                              Redis Cluster discovery endpoint (e.g., GCP Memorystore Cluster, AWS ElastiCache
                              cluster mode enabled). Requires addr to be set.
                            type: boolean
                          dialTimeout:
                            default: 5s
                            description: |-
                              DialTimeout is the timeout for establishing connections.
                              Format: Go duration string (e.g., "5s", "1m").
                            pattern: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
                            type: string
                          readTimeout:
                            default: 3s
                            description: |-
                              ReadTimeout is the timeout for socket reads.
                              Format: Go duration string (e.g., "3s", "1m").
                            pattern: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
                            type: string
                          sentinelConfig:
                            description: |-
                              SentinelConfig holds Redis Sentinel configuration.
                              Use for self-managed Redis with Sentinel-based HA. Mutually exclusive with addr.
                            properties:
                              db:
                                default: 0
                                description: DB is the Redis database number.
                                format: int32
                                type: integer
                              masterName:
                                description: MasterName is the name of the Redis master
                                  monitored by Sentinel.
                                type: string
                              sentinelAddrs:
                                description: |-
                                  SentinelAddrs is a list of Sentinel host:port addresses.
                                  Mutually exclusive with SentinelService.
                                items:
                                  type: string
                                type: array
                                x-kubernetes-list-type: atomic
                              sentinelService:
                                description: |-
                                  SentinelService enables automatic discovery from a Kubernetes Service.
                                  Mutually exclusive with SentinelAddrs.
                                properties:
                                  name:
                                    description: Name of the Sentinel Service.
                                    type: string
                                  namespace:
                                    description: Namespace of the Sentinel Service
                                      (defaults to same namespace).
                                    type: string
                                  port:
                                    default: 26379
                                    description: Port of the Sentinel service.
                                    format: int32
                                    type: integer
                                required:
                                - name
                                type: object
                            required:
                            - masterName
                            type: object
                          sentinelTls:
                            description: |-
                              SentinelTLS configures TLS for connections to Sentinel instances.
                              Only applies when sentinelConfig is set. Presence of this field enables TLS.
                            properties:
                              caCertSecretRef:
                                description: |-
                                  CACertSecretRef references a Secret containing a PEM-encoded CA certificate
                                  for verifying the server. When not specified, system root CAs are used.
                                properties:
                                  key:
                                    description: Key is the key within the secret
                                    type: string
                                  name:
                                    description: Name is the name of the secret
                                    type: string
                                required:
                                - key
                                - name
                                type: object
                              insecureSkipVerify:
                                description: |-
                                  InsecureSkipVerify skips TLS certificate verification.
                                  Use when connecting to services with self-signed certificates.
                                type: boolean
                            type: object
                          tls:
                            description: |-
                              TLS configures TLS for connections to the Redis/Valkey master or cluster nodes.
                              Presence of this field enables TLS. Omit to use plaintext.
                            properties:
                              caCertSecretRef:
                                description: |-
                                  CACertSecretRef references a Secret containing a PEM-encoded CA certificate
                                  for verifying the server. When not specified, system root CAs are used.
                                properties:
                                  key:
                                    description: Key is the key within the secret
                                    type: string
                                  name:
                                    description: Name is the name of the secret
                                    type: string
                                required:
                                - key
                                - name
                                type: object
                              insecureSkipVerify:
                                description: |-
                                  InsecureSkipVerify skips TLS certificate verification.
                                  Use when connecting to services with self-signed certificates.
                                type: boolean
                            type: object
                          writeTimeout:
                            default: 3s
                            description: |-
                              WriteTimeout is the timeout for socket writes.
                              Format: Go duration string (e.g., "3s", "1m").
                            pattern: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
                            type: string
                        required:
                        - aclUserConfig
                        type: object
                        x-kubernetes-validations:
                        - message: exactly one of addr or sentinelConfig must be set
                          rule: (has(self.addr) && self.addr.size() > 0) != has(self.sentinelConfig)
                        - message: clusterMode requires addr to be set
                          rule: '!(has(self.clusterMode) && self.clusterMode) || (has(self.addr)
                            && self.addr.size() > 0)'
                      type:
                        default: memory
                        description: |-
                          Type specifies the storage backend type.
                          Valid values: "memory" (default), "redis".
                        enum:
                        - memory
                        - redis
                        type: string
                    type: object
                  tokenLifespans:
                    description: |-
                      TokenLifespans configures the duration that various tokens are valid.
                      If not specified, defaults are applied (access: 1h, refresh: 7d, authCode: 10m).
                    properties:
                      accessTokenLifespan:
                        description: |-
                          AccessTokenLifespan is the duration that access tokens are valid.
                          Format: Go duration string (e.g., "1h", "30m", "24h").
                          If empty, defaults to 1 hour.
                        pattern: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
                        type: string
                      authCodeLifespan:
                        description: |-
                          AuthCodeLifespan is the duration that authorization codes are valid.
                          Format: Go duration string (e.g., "10m", "5m").
                          If empty, defaults to 10 minutes.
                        pattern: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
                        type: string
                      refreshTokenLifespan:
                        description: |-
                          RefreshTokenLifespan is the duration that refresh tokens are valid.
                          Format: Go duration string (e.g., "168h", "7d" as "168h").
                          If empty, defaults to 7 days (168h).
                        pattern: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
                        type: string
                    type: object
                  upstreamProviders:
                    description: |-
                      UpstreamProviders configures connections to upstream Identity Providers.
                      The embedded auth server delegates authentication to these providers.
                      MCPServer and MCPRemoteProxy support a single upstream; VirtualMCPServer supports multiple.
                    items:
                      description: |-
                        UpstreamProviderConfig defines configuration for an upstream Identity Provider.

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

                        The rule is structured as a chain of equality checks ending in an explicit
                        `false`, so adding a new UpstreamProviderType value without extending this
                        rule fails admission instead of silently demanding the OAuth2 shape. When
                        adding a new type, extend both this rule and validateUpstreamProvider.
                      properties:
                        name:
                          description: |-
                            Name uniquely identifies this upstream provider.
                            Used for routing decisions and session binding in multi-upstream scenarios.
                            Must be lowercase alphanumeric with hyphens (DNS-label-like).
                          maxLength: 63
                          minLength: 1
                          pattern: ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$
                          type: string
                        oauth2Config:
                          description: |-
                            OAuth2Config contains OAuth 2.0-specific configuration.
                            Required when Type is "oauth2", must be nil when Type is "oidc".
                          properties:
                            additionalAuthorizationParams:
                              additionalProperties:
                                type: string
                              description: |-
                                AdditionalAuthorizationParams are extra query parameters to include in
                                authorization requests sent to the upstream provider.
                                This is useful for providers that require custom parameters, such as
                                Google's access_type=offline for obtaining refresh tokens.
                                Framework-managed parameters (response_type, client_id, redirect_uri,
                                scope, state, code_challenge, code_challenge_method, nonce) are not allowed.
                              maxProperties: 16
                              type: object
                            authorizationEndpoint:
                              description: AuthorizationEndpoint is the URL for the
                                OAuth authorization endpoint.
                              pattern: ^https?://.*$
                              type: string
                            clientId:
                              description: |-
                                ClientID is the OAuth 2.0 client identifier registered with the upstream IDP.
                                Mutually exclusive with DCRConfig: when DCRConfig is set, ClientID is obtained
                                at runtime via RFC 7591 Dynamic Client Registration and must be left empty.
                              type: string
                            clientSecretRef:
                              description: |-
                                ClientSecretRef references a Kubernetes Secret containing the OAuth 2.0 client secret.
                                Optional for public clients using PKCE instead of client secret.
                              properties:
                                key:
                                  description: Key is the key within the secret
                                  type: string
                                name:
                                  description: Name is the name of the secret
                                  type: string
                              required:
                              - key
                              - name
                              type: object
                            dcrConfig:
                              description: |-
                                DCRConfig enables RFC 7591 Dynamic Client Registration against the upstream
                                authorization server. When set, the client credentials are obtained at
                                runtime rather than being pre-provisioned, and ClientID must be left empty.
                                Mutually exclusive with ClientID.
                              properties:
                                discoveryUrl:
                                  description: |-
                                    DiscoveryURL is the RFC 8414 / OIDC Discovery document URL. The resolver
                                    issues a single GET against this URL (no well-known-path fallback) and
                                    reads registration_endpoint, authorization_endpoint, token_endpoint,
                                    token_endpoint_auth_methods_supported, and scopes_supported from the
                                    response.
                                    Mutually exclusive with RegistrationEndpoint.
                                    HTTPS is required because the registration endpoint resolved from this
                                    document carries the initial access token and the issued client_secret
                                    (RFC 7591 §3, RFC 8414 §3). MaxLength is a defensive size cap (etcd
                                    object budget, regex evaluation cost) and matches the conventional URL
                                    length cap.
                                  maxLength: 2048
                                  pattern: ^https://[^\s?#]+[^/\s?#]$
                                  type: string
                                initialAccessTokenRef:
                                  description: |-
                                    InitialAccessTokenRef is an optional reference to a Kubernetes Secret
                                    carrying an RFC 7591 §3 initial access token. When set, the resolver
                                    presents the token value as a Bearer credential on the registration
                                    request. Mirrors the ClientSecretRef pattern.
                                  properties:
                                    key:
                                      description: Key is the key within the secret
                                      type: string
                                    name:
                                      description: Name is the name of the secret
                                      type: string
                                  required:
                                  - key
                                  - name
                                  type: object
                                registrationEndpoint:
                                  description: |-
                                    RegistrationEndpoint is the RFC 7591 registration endpoint URL used
                                    directly, bypassing discovery. When using this field, the caller is
                                    expected to also supply AuthorizationEndpoint, TokenEndpoint, and an
                                    explicit Scopes list on the parent OAuth2UpstreamConfig.
                                    Mutually exclusive with DiscoveryURL.
                                    HTTPS is required because the registration endpoint carries the initial
                                    access token and the issued client_secret (RFC 7591 §3, RFC 8414 §3).
                                    MaxLength is a defensive size cap (etcd object budget, regex evaluation
                                    cost) and matches the conventional URL length cap.
                                  maxLength: 2048
                                  pattern: ^https://[^\s?#]+[^/\s?#]$
                                  type: string
                                softwareId:
                                  description: |-
                                    SoftwareID is the RFC 7591 "software_id" registration metadata value,
                                    identifying the client software independent of any particular
                                    registration instance. Typically a UUID or short identifier.
                                  maxLength: 255
                                  type: string
                                softwareStatement:
                                  description: |-
                                    SoftwareStatement is the RFC 7591 "software_statement" JWT asserting
                                    metadata about the client software, signed by a party the authorization
                                    server trusts.

                                    Stored inline on the CR. The JWT is signed but not encrypted, so its
                                    contents are visible to anyone with get/list/watch on this resource and
                                    appear in etcd backups in plaintext. Treat the value as non-confidential
                                    (signed attestation, not a secret). Operators that rotate software
                                    statements like bearer credentials should keep them at the authorization
                                    server side and rely on the registration endpoint's initial access
                                    token (see InitialAccessTokenRef) instead of placing them on the CR.

                                    Bounded to 16384 characters as a defensive size cap (etcd object
                                    budget, regex evaluation cost). Real-world signed statements with
                                    embedded x5c certificate chains, JWKS keys, or OIDC-Federation
                                    trust-framework metadata routinely exceed 4 KB.
                                  maxLength: 16384
                                  type: string
                              type: object
                              x-kubernetes-validations:
                              - message: exactly one of discoveryUrl or registrationEndpoint
                                  must be set
                                rule: has(self.discoveryUrl) != has(self.registrationEndpoint)
                            identityFromToken:
                              description: |-
                                IdentityFromToken extracts user identity (subject, name, email) directly
                                from the OAuth2 token-endpoint response body using gjson dot-notation paths.
                                When set, the embedded auth server skips the userinfo HTTP call entirely
                                and resolves identity from the token response. See IdentityFromTokenConfig
                                for trust-model and uniqueness considerations.
                              properties:
                                emailPath:
                                  description: |-
                                    EmailPath is the dot-notation path to the email address field in the token response.
                                    If not specified or if the path does not resolve to a string, the email is omitted.
                                    Omit the field entirely rather than setting it to an empty string.
                                  maxLength: 256
                                  minLength: 1
                                  type: string
                                namePath:
                                  description: |-
                                    NamePath is the dot-notation path to the display name field in the token response.
                                    If not specified or if the path does not resolve to a string, the display name is omitted.
                                    Omit the field entirely rather than setting it to an empty string.
                                  maxLength: 256
                                  minLength: 1
                                  type: string
                                subjectPath:
                                  description: |-
                                    SubjectPath is the dot-notation path to the subject (user ID) field in the token response.
                                    Warning: claims read from the token response are trusted only via TLS, not
                                    cryptographically verified; prefer OIDC ID tokens when verifiable claims are required.
                                    Example: "authed_user.id" for Slack (top-level token-response field). For providers
                                    whose token response embeds the access token as a JWT (e.g. Snowflake), use the
                                    "@upstreamjwt" modifier to decode the payload, e.g. "access_token|@upstreamjwt|sub".
                                    The "@upstreamjwt" modifier performs no signature verification either.
                                  maxLength: 256
                                  minLength: 1
                                  type: string
                              required:
                              - subjectPath
                              type: object
                            redirectUri:
                              description: |-
                                RedirectURI is the callback URL where the upstream IDP will redirect after authentication.
                                When not specified, defaults to `{resourceUrl}/oauth/callback` where `resourceUrl` is the
                                URL associated with the resource (e.g., MCPServer or vMCP) using this config.
                              type: string
                            scopes:
                              description: Scopes are the OAuth scopes to request
                                from the upstream IDP.
                              items:
                                type: string
                              type: array
                              x-kubernetes-list-type: atomic
                            tokenEndpoint:
                              description: TokenEndpoint is the URL for the OAuth
                                token endpoint.
                              pattern: ^https?://.*$
                              type: string
                            tokenResponseMapping:
                              description: |-
                                TokenResponseMapping configures custom field extraction from non-standard token responses.
                                Some OAuth providers (e.g., GovSlack) nest token fields under non-standard paths
                                instead of returning them at the top level. When set, ToolHive performs the token
                                exchange HTTP call directly and extracts fields using the configured dot-notation paths.
                                If nil, standard OAuth 2.0 token response parsing is used.
                                For extracting user identity from the token response, see IdentityFromToken.
                              properties:
                                accessTokenPath:
                                  description: |-
                                    AccessTokenPath is the dot-notation path to the access token in the response.
                                    Example: "authed_user.access_token"
                                  minLength: 1
                                  type: string
                                expiresInPath:
                                  description: |-
                                    ExpiresInPath is the dot-notation path to the expires_in value (in seconds).
                                    If not specified, defaults to "expires_in".
                                  type: string
                                refreshTokenPath:
                                  description: |-
                                    RefreshTokenPath is the dot-notation path to the refresh token in the response.
                                    If not specified, defaults to "refresh_token".
                                  type: string
                                scopePath:
                                  description: |-
                                    ScopePath is the dot-notation path to the scope string in the response.
                                    If not specified, defaults to "scope".
                                  type: string
                              required:
                              - accessTokenPath
                              type: object
                            userInfo:
                              description: |-
                                UserInfo contains configuration for fetching user information from the upstream provider.
                                When omitted and IdentityFromToken is also unset, the embedded auth server runs in
                                synthesis mode for this upstream: a non-PII subject derived from the access token, no
                                Name/Email. Use this shape for upstreams with no userinfo surface and no identity in
                                the token response (e.g., MCP authorization servers per the MCP spec). When
                                IdentityFromToken is set instead, identity is resolved from the token response body
                                (e.g., Snowflake's "username" field, Slack's "authed_user.id"); the userinfo HTTP call
                                is skipped entirely.
                              properties:
                                additionalHeaders:
                                  additionalProperties:
                                    type: string
                                  description: |-
                                    AdditionalHeaders contains extra headers to include in the userinfo request.
                                    Useful for providers that require specific headers (e.g., GitHub's Accept header).
                                  type: object
                                endpointUrl:
                                  description: EndpointURL is the URL of the userinfo
                                    endpoint.
                                  pattern: ^https?://.*$
                                  type: string
                                fieldMapping:
                                  description: |-
                                    FieldMapping contains custom field mapping configuration for non-standard providers.
                                    If nil, standard OIDC field names are used ("sub", "name", "email").
                                  properties:
                                    emailFields:
                                      description: |-
                                        EmailFields is an ordered list of field names to try for the email address.
                                        The first non-empty value found will be used.
                                        Default: ["email"]
                                      items:
                                        type: string
                                      type: array
                                      x-kubernetes-list-type: atomic
                                    nameFields:
                                      description: |-
                                        NameFields is an ordered list of field names to try for the display name.
                                        The first non-empty value found will be used.
                                        Default: ["name"]
                                      items:
                                        type: string
                                      type: array
                                      x-kubernetes-list-type: atomic
                                    subjectFields:
                                      description: |-
                                        SubjectFields is an ordered list of field names to try for the user ID.
                                        The first non-empty value found will be used.
                                        Default: ["sub"]
                                      items:
                                        type: string
                                      type: array
                                      x-kubernetes-list-type: atomic
                                  type: object
                                httpMethod:
                                  description: |-
                                    HTTPMethod is the HTTP method to use for the userinfo request.
                                    If not specified, defaults to GET.
                                  enum:
                                  - GET
                                  - POST
                                  type: string
                              required:
                              - endpointUrl
                              type: object
                          required:
                          - authorizationEndpoint
                          - tokenEndpoint
                          type: object
                          x-kubernetes-validations:
                          - message: exactly one of clientId or dcrConfig must be
                              set
                            rule: '(has(self.clientId) && size(self.clientId) > 0)
                              ? !has(self.dcrConfig) : has(self.dcrConfig)'
                          - message: clientSecretRef must not be set when dcrConfig
                              is set; the client_secret is obtained at runtime via
                              Dynamic Client Registration
                            rule: '!(has(self.dcrConfig) && has(self.clientSecretRef))'
                        oidcConfig:
                          description: |-
                            OIDCConfig contains OIDC-specific configuration.
                            Required when Type is "oidc", must be nil when Type is "oauth2".
                          properties:
                            additionalAuthorizationParams:
                              additionalProperties:
                                type: string
                              description: |-
                                AdditionalAuthorizationParams are extra query parameters to include in
                                authorization requests sent to the upstream provider.
                                This is useful for providers that require custom parameters, such as
                                Google's access_type=offline for obtaining refresh tokens.
                                Note: when using access_type=offline, also set explicit scopes to avoid
                                the default offline_access scope being sent alongside it.
                                Framework-managed parameters (response_type, client_id, redirect_uri,
                                scope, state, code_challenge, code_challenge_method, nonce) are not allowed.
                              maxProperties: 16
                              type: object
                            clientId:
                              description: ClientID is the OAuth 2.0 client identifier
                                registered with the upstream IDP.
                              type: string
                            clientSecretRef:
                              description: |-
                                ClientSecretRef references a Kubernetes Secret containing the OAuth 2.0 client secret.
                                Optional for public clients using PKCE instead of client secret.
                              properties:
                                key:
                                  description: Key is the key within the secret
                                  type: string
                                name:
                                  description: Name is the name of the secret
                                  type: string
                              required:
                              - key
                              - name
                              type: object
                            issuerUrl:
                              description: |-
                                IssuerURL is the OIDC issuer URL for automatic endpoint discovery.
                                Must be a valid HTTPS URL.
                              pattern: ^https://.*$
                              type: string
                            redirectUri:
                              description: |-
                                RedirectURI is the callback URL where the upstream IDP will redirect after authentication.
                                When not specified, defaults to `{resourceUrl}/oauth/callback` where `resourceUrl` is the
                                URL associated with the resource (e.g., MCPServer or vMCP) using this config.
                              type: string
                            scopes:
                              description: |-
                                Scopes are the OAuth scopes to request from the upstream IDP.
                                If not specified, defaults to ["openid", "offline_access"].
                                When using additionalAuthorizationParams with provider-specific refresh token
                                mechanisms (e.g., Google's access_type=offline), set explicit scopes to avoid
                                sending both offline_access and the provider-specific parameter.
                              items:
                                type: string
                              type: array
                              x-kubernetes-list-type: atomic
                            userInfoOverride:
                              description: |-
                                UserInfoOverride allows customizing UserInfo fetching behavior for OIDC providers.
                                By default, the UserInfo endpoint is discovered automatically via OIDC discovery.
                                Use this to override the endpoint URL, HTTP method, or field mappings for providers
                                that return non-standard claim names in their UserInfo response.
                              properties:
                                additionalHeaders:
                                  additionalProperties:
                                    type: string
                                  description: |-
                                    AdditionalHeaders contains extra headers to include in the userinfo request.
                                    Useful for providers that require specific headers (e.g., GitHub's Accept header).
                                  type: object
                                endpointUrl:
                                  description: EndpointURL is the URL of the userinfo
                                    endpoint.
                                  pattern: ^https?://.*$
                                  type: string
                                fieldMapping:
                                  description: |-
                                    FieldMapping contains custom field mapping configuration for non-standard providers.
                                    If nil, standard OIDC field names are used ("sub", "name", "email").
                                  properties:
                                    emailFields:
                                      description: |-
                                        EmailFields is an ordered list of field names to try for the email address.
                                        The first non-empty value found will be used.
                                        Default: ["email"]
                                      items:
                                        type: string
                                      type: array
                                      x-kubernetes-list-type: atomic
                                    nameFields:
                                      description: |-
                                        NameFields is an ordered list of field names to try for the display name.
                                        The first non-empty value found will be used.
                                        Default: ["name"]
                                      items:
                                        type: string
                                      type: array
                                      x-kubernetes-list-type: atomic
                                    subjectFields:
                                      description: |-
                                        SubjectFields is an ordered list of field names to try for the user ID.
                                        The first non-empty value found will be used.
                                        Default: ["sub"]
                                      items:
                                        type: string
                                      type: array
                                      x-kubernetes-list-type: atomic
                                  type: object
                                httpMethod:
                                  description: |-
                                    HTTPMethod is the HTTP method to use for the userinfo request.
                                    If not specified, defaults to GET.
                                  enum:
                                  - GET
                                  - POST
                                  type: string
                              required:
                              - endpointUrl
                              type: object
                          required:
                          - clientId
                          - issuerUrl
                          type: object
                        type:
                          description: 'Type specifies the provider type: "oidc" or
                            "oauth2"'
                          enum:
                          - oidc
                          - oauth2
                          type: string
                      required:
                      - name
                      - type
                      type: object
                      x-kubernetes-validations:
                      - message: type must be 'oidc' or 'oauth2'; oidcConfig must
                          be set when type is 'oidc' and oauth2Config must be set
                          when type is 'oauth2' (and the other must not be set)
                        rule: 'self.type == ''oidc'' ? (has(self.oidcConfig) && !has(self.oauth2Config))
                          : self.type == ''oauth2'' ? (has(self.oauth2Config) && !has(self.oidcConfig))
                          : false'
                    minItems: 1
                    type: array
                    x-kubernetes-list-map-keys:
                    - name
                    x-kubernetes-list-type: map
                required:
                - issuer
                - upstreamProviders
                type: object
              config:
                description: |-
                  Config is the Virtual MCP server configuration.
                  The audit config from here is also supported, but not required.
                properties:
                  aggregation:
                    description: |-
                      Aggregation defines tool aggregation and conflict resolution strategies.
                      Supports ToolConfigRef for Kubernetes-native MCPToolConfig resource references.
                    properties:
                      conflictResolution:
                        default: prefix
                        description: |-
                          ConflictResolution defines the strategy for resolving tool name conflicts.
                          - prefix: Automatically prefix tool names with workload identifier
                          - priority: First workload in priority order wins
                          - manual: Explicitly define overrides for all conflicts
                        enum:
                        - prefix
                        - priority
                        - manual
                        type: string
                      conflictResolutionConfig:
                        description: ConflictResolutionConfig provides configuration
                          for the chosen strategy.
                        properties:
                          prefixFormat:
                            default: '{workload}_'
                            description: |-
                              PrefixFormat defines the prefix format for the "prefix" strategy.
                              Supports placeholders: {workload}, {workload}_, {workload}.
                            type: string
                          priorityOrder:
                            description: PriorityOrder defines the workload priority
                              order for the "priority" strategy.
                            items:
                              type: string
                            type: array
                        type: object
                      excludeAllTools:
                        description: |-
                          ExcludeAllTools hides all backend tools from MCP clients when true.
                          Hidden tools are NOT advertised in tools/list responses, but they ARE
                          available in the routing table for composite tools to use.
                          This enables the use case where you want to hide raw backend tools from
                          direct client access while exposing curated composite tool workflows.
                        type: boolean
                      tools:
                        description: Tools defines per-workload tool filtering and
                          overrides.
                        items:
                          description: WorkloadToolConfig defines tool filtering and
                            overrides for a specific workload.
                          properties:
                            excludeAll:
                              description: |-
                                ExcludeAll hides all tools from this workload from MCP clients when true.
                                Hidden tools are NOT advertised in tools/list responses, but they ARE
                                available in the routing table for composite tools to use.
                                This enables the use case where you want to hide raw backend tools from
                                direct client access while exposing curated composite tool workflows.
                              type: boolean
                            filter:
                              description: |-
                                Filter is an allow-list of tool names to advertise to MCP clients.
                                Tools NOT in this list are hidden from clients (not in tools/list response)
                                but remain available in the routing table for composite tools to use.
                                This enables selective exposure of backend tools while allowing composite
                                workflows to orchestrate all backend capabilities.
                                Only used if ToolConfigRef is not specified.
                              items:
                                type: string
                              type: array
                            overrides:
                              additionalProperties:
                                description: ToolOverride defines tool name, description,
                                  and annotation overrides.
                                properties:
                                  annotations:
                                    description: |-
                                      Annotations overrides specific tool annotation fields.
                                      Only specified fields are overridden; others pass through from the backend.
                                    properties:
                                      destructiveHint:
                                        description: DestructiveHint overrides the
                                          destructive hint annotation.
                                        type: boolean
                                      idempotentHint:
                                        description: IdempotentHint overrides the
                                          idempotent hint annotation.
                                        type: boolean
                                      openWorldHint:
                                        description: OpenWorldHint overrides the open-world
                                          hint annotation.
                                        type: boolean
                                      readOnlyHint:
                                        description: ReadOnlyHint overrides the read-only
                                          hint annotation.
                                        type: boolean
                                      title:
                                        description: Title overrides the human-readable
                                          title annotation.
                                        type: string
                                    type: object
                                  description:
                                    description: Description is the new tool description.
                                    type: string
                                  name:
                                    description: Name is the new tool name (for renaming).
                                    type: string
                                type: object
                              description: |-
                                Overrides is an inline map of tool overrides for renaming and description changes.
                                Overrides are applied to tools before conflict resolution and affect both
                                advertising and routing (the overridden name is used everywhere).
                                Only used if ToolConfigRef is not specified.
                              type: object
                            toolConfigRef:
                              description: |-
                                ToolConfigRef references an MCPToolConfig resource for tool filtering and renaming.
                                If specified, Filter and Overrides are ignored.
                                Only used when running in Kubernetes with the operator.
                              properties:
                                name:
                                  description: Name is the name of the MCPToolConfig
                                    resource in the same namespace.
                                  type: string
                              required:
                              - name
                              type: object
                            workload:
                              description: Workload is the name of the backend MCPServer
                                workload.
                              type: string
                          required:
                          - workload
                          type: object
                        type: array
                    type: object
                  audit:
                    description: |-
                      Audit configures audit logging for the Virtual MCP server.
                      When present, audit logs include MCP protocol operations.
                      See audit.Config for available configuration options.
                    properties:
                      component:
                        description: Component is the component name to use in audit
                          events.
                        type: string
                      detectApplicationErrors:
                        default: true
                        description: |-
                          DetectApplicationErrors controls whether the audit middleware inspects
                          JSON-RPC response bodies for application-level errors when the HTTP
                          status code indicates success (2xx). When enabled, a small prefix of
                          the response body is buffered to detect JSON-RPC error fields,
                          independent of the IncludeResponseData setting.
                        type: boolean
                      enabled:
                        default: false
                        description: |-
                          Enabled controls whether audit logging is enabled.
                          When true, enables audit logging with the configured options.
                        type: boolean
                      eventTypes:
                        description: EventTypes specifies which event types to audit.
                          If empty, all events are audited.
                        items:
                          type: string
                        type: array
                      excludeEventTypes:
                        description: |-
                          ExcludeEventTypes specifies which event types to exclude from auditing.
                          This takes precedence over EventTypes.
                        items:
                          type: string
                        type: array
                      includeRequestData:
                        default: false
                        description: IncludeRequestData determines whether to include
                          request data in audit logs.
                        type: boolean
                      includeResponseData:
                        default: false
                        description: IncludeResponseData determines whether to include
                          response data in audit logs.
                        type: boolean
                      logFile:
                        description: LogFile specifies the file path for audit logs.
                          If empty, logs to stdout.
                        type: string
                      maxDataSize:
                        default: 1024
                        description: MaxDataSize limits the size of request/response
                          data included in audit logs (in bytes).
                        type: integer
                    type: object
                  backends:
                    description: |-
                      Backends defines pre-configured backend servers for static mode.
                      When OutgoingAuth.Source is "inline", this field contains the full list of backend
                      servers with their URLs and transport types, eliminating the need for K8s API access.
                      When OutgoingAuth.Source is "discovered", this field is empty and backends are
                      discovered at runtime via Kubernetes API.
                    items:
                      description: |-
                        StaticBackendConfig defines a pre-configured backend server for static mode.
                        This allows vMCP to operate without Kubernetes API access by embedding all backend
                        information directly in the configuration.
                      properties:
                        caBundlePath:
                          description: |-
                            CABundlePath is the file path to a custom CA certificate bundle for TLS verification.
                            Only valid when Type is "entry". The operator mounts CA bundles at
                            /etc/toolhive/ca-bundles/<name>/ca.crt.
                          type: string
                        metadata:
                          additionalProperties:
                            type: string
                          description: |-
                            Metadata is a custom key-value map for storing additional backend information
                            such as labels, tags, or other arbitrary data (e.g., "env": "prod", "region": "us-east-1").
                            This is NOT Kubernetes ObjectMeta - it's a simple string map for user-defined metadata.
                            Reserved keys: "group" is automatically set by vMCP and any user-provided value will be overridden.
                          type: object
                        name:
                          description: |-
                            Name is the backend identifier.
                            Must match the backend name from the MCPGroup for auth config resolution.
                          type: string
                        transport:
                          description: |-
                            Transport is the MCP transport protocol: "sse" or "streamable-http"
                            Only network transports supported by vMCP client are allowed.
                          enum:
                          - sse
                          - streamable-http
                          type: string
                        type:
                          description: |-
                            Type is the backend workload type: "entry" for MCPServerEntry backends, or empty
                            for container/proxy backends. Entry backends connect directly to remote MCP servers.
                          enum:
                          - entry
                          - ""
                          type: string
                        url:
                          description: URL is the backend's MCP server base URL.
                          pattern: ^https?://
                          type: string
                      required:
                      - name
                      - transport
                      - url
                      type: object
                    type: array
                  compositeToolRefs:
                    description: |-
                      CompositeToolRefs references VirtualMCPCompositeToolDefinition resources
                      for complex, reusable workflows. Only applicable when running in Kubernetes.
                      Referenced resources must be in the same namespace as the VirtualMCPServer.
                    items:
                      description: |-
                        CompositeToolRef defines a reference to a VirtualMCPCompositeToolDefinition resource.
                        The referenced resource must be in the same namespace as the VirtualMCPServer.
                      properties:
                        name:
                          description: Name is the name of the VirtualMCPCompositeToolDefinition
                            resource in the same namespace.
                          type: string
                      required:
                      - name
                      type: object
                    type: array
                  compositeTools:
                    description: |-
                      CompositeTools defines inline composite tool workflows.
                      Full workflow definitions are embedded in the configuration.
                      For Kubernetes, complex workflows can also reference VirtualMCPCompositeToolDefinition CRDs.
                    items:
                      description: |-
                        CompositeToolConfig defines a composite tool workflow.
                        This matches the YAML structure from the proposal (lines 173-255).
                      properties:
                        description:
                          description: Description describes what the workflow does.
                          type: string
                        name:
                          description: Name is the workflow name (unique identifier).
                          type: string
                        output:
                          description: |-
                            Output defines the structured output schema for this workflow.
                            If not specified, the workflow returns the last step's output (backward compatible).
                          properties:
                            properties:
                              additionalProperties:
                                description: |-
                                  OutputProperty defines a single output property.
                                  For non-object types, Value is required.
                                  For object types, either Value or Properties must be specified (but not both).
                                properties:
                                  default:
                                    description: |-
                                      Default is the fallback value if template expansion fails.
                                      Type coercion is applied to match the declared Type.
                                    x-kubernetes-preserve-unknown-fields: true
                                  description:
                                    description: Description is a human-readable description
                                      exposed to clients and models
                                    type: string
                                  properties:
                                    description: |-
                                      Properties defines nested properties for object types.
                                      Each nested property has full metadata (type, description, value/properties).
                                    type: object
                                    x-kubernetes-preserve-unknown-fields: true
                                  type:
                                    description: 'Type is the JSON Schema type: "string",
                                      "integer", "number", "boolean", "object", "array"'
                                    enum:
                                    - string
                                    - integer
                                    - number
                                    - boolean
                                    - object
                                    - array
                                    type: string
                                  value:
                                    description: |-
                                      Value is a template string for constructing the runtime value.
                                      For object types, this can be a JSON string that will be deserialized.
                                      Supports template syntax: {{ "{{" }}.steps.step_id.output.field{{ "}}" }}, {{ "{{" }}.params.param_name{{ "}}" }}
                                    type: string
                                required:
                                - type
                                type: object
                              description: |-
                                Properties defines the output properties.
                                Map key is the property name, value is the property definition.
                              type: object
                            required:
                              description: Required lists property names that must
                                be present in the output.
                              items:
                                type: string
                              type: array
                          required:
                          - properties
                          type: object
                        parameters:
                          description: |-
                            Parameters defines input parameter schema in JSON Schema format.
                            Should be a JSON Schema object with "type": "object" and "properties".
                            Example:
                              {
                                "type": "object",
                                "properties": {
                                  "param1": {"type": "string", "default": "value"},
                                  "param2": {"type": "integer"}
                                },
                                "required": ["param2"]
                              }

                            We use json.Map rather than a typed struct because JSON Schema is highly
                            flexible with many optional fields (default, enum, minimum, maximum, pattern,
                            items, additionalProperties, oneOf, anyOf, allOf, etc.). Using json.Map
                            allows full JSON Schema compatibility without needing to define every possible
                            field, and matches how the MCP SDK handles inputSchema.
                          type: object
                          x-kubernetes-preserve-unknown-fields: true
                        steps:
                          description: Steps are the workflow steps to execute.
                          items:
                            description: |-
                              WorkflowStepConfig defines a single workflow step.
                              This matches the proposal's step configuration (lines 180-255).
                            properties:
                              arguments:
                                description: |-
                                  Arguments is a map of argument values with template expansion support.
                                  Supports Go template syntax with .params and .steps for string values.
                                  Non-string values (integers, booleans, arrays, objects) are passed as-is.
                                  Note: the templating is only supported on the first level of the key-value pairs.
                                type: object
                                x-kubernetes-preserve-unknown-fields: true
                              collection:
                                description: |-
                                  Collection is a Go template expression that resolves to a JSON array or a slice.
                                  Only used when Type is "forEach".
                                type: string
                              condition:
                                description: Condition is a template expression that
                                  determines if the step should execute
                                type: string
                              defaultResults:
                                description: |-
                                  DefaultResults provides fallback output values when this step is skipped
                                  (due to condition evaluating to false) or fails (when onError.action is "continue").
                                  Each key corresponds to an output field name referenced by downstream steps.
                                  Required if the step may be skipped AND downstream steps reference this step's output.
                                x-kubernetes-preserve-unknown-fields: true
                              dependsOn:
                                description: DependsOn lists step IDs that must complete
                                  before this step
                                items:
                                  type: string
                                type: array
                              id:
                                description: ID is the unique identifier for this
                                  step.
                                type: string
                              itemVar:
                                description: |-
                                  ItemVar is the variable name used to reference the current item in forEach templates.
                                  Defaults to "item" if not specified.
                                  Only used when Type is "forEach".
                                type: string
                              maxIterations:
                                description: |-
                                  MaxIterations limits the number of items that can be iterated over.
                                  Defaults to 100, hard cap at 1000.
                                  Only used when Type is "forEach".
                                type: integer
                              maxParallel:
                                description: |-
                                  MaxParallel limits the number of concurrent iterations in a forEach step.
                                  Defaults to the DAG executor's maxParallel (10).
                                  Only used when Type is "forEach".
                                type: integer
                              message:
                                description: |-
                                  Message is the elicitation message
                                  Only used when Type is "elicitation"
                                type: string
                              onCancel:
                                description: |-
                                  OnCancel defines the action to take when the user cancels/dismisses the elicitation
                                  Only used when Type is "elicitation"
                                properties:
                                  action:
                                    default: abort
                                    description: |-
                                      Action defines the action to take when the user declines or cancels
                                      - skip_remaining: Skip remaining steps in the workflow
                                      - abort: Abort the entire workflow execution
                                      - continue: Continue to the next step
                                    enum:
                                    - skip_remaining
                                    - abort
                                    - continue
                                    type: string
                                type: object
                              onDecline:
                                description: |-
                                  OnDecline defines the action to take when the user explicitly declines the elicitation
                                  Only used when Type is "elicitation"
                                properties:
                                  action:
                                    default: abort
                                    description: |-
                                      Action defines the action to take when the user declines or cancels
                                      - skip_remaining: Skip remaining steps in the workflow
                                      - abort: Abort the entire workflow execution
                                      - continue: Continue to the next step
                                    enum:
                                    - skip_remaining
                                    - abort
                                    - continue
                                    type: string
                                type: object
                              onError:
                                description: OnError defines error handling behavior
                                properties:
                                  action:
                                    default: abort
                                    description: Action defines the action to take
                                      on error
                                    enum:
                                    - abort
                                    - continue
                                    - retry
                                    type: string
                                  retryCount:
                                    description: |-
                                      RetryCount is the maximum number of retries
                                      Only used when Action is "retry"
                                    type: integer
                                  retryDelay:
                                    description: |-
                                      RetryDelay is the delay between retry attempts
                                      Only used when Action is "retry"
                                    pattern: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
                                    type: string
                                type: object
                              schema:
                                description: Schema defines the expected response
                                  schema for elicitation
                                type: object
                                x-kubernetes-preserve-unknown-fields: true
                              step:
                                description: |-
                                  InnerStep defines the step to execute for each item in the collection.
                                  Only used when Type is "forEach". Only tool-type inner steps are supported.
                                type: object
                                x-kubernetes-preserve-unknown-fields: true
                              timeout:
                                description: Timeout is the maximum execution time
                                  for this step
                                pattern: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
                                type: string
                              tool:
                                description: |-
                                  Tool is the tool to call (format: "workload.tool_name")
                                  Only used when Type is "tool"
                                type: string
                              type:
                                default: tool
                                description: Type is the step type (tool, elicitation,
                                  etc.)
                                enum:
                                - tool
                                - elicitation
                                - forEach
                                type: string
                            required:
                            - id
                            type: object
                          type: array
                        timeout:
                          description: Timeout is the maximum workflow execution time.
                          pattern: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
                          type: string
                      required:
                      - name
                      - steps
                      type: object
                    type: array
                  groupRef:
                    description: |-
                      Group references an existing MCPGroup that defines backend workloads.
                      In standalone CLI mode, this is set from the YAML config file.
                      In Kubernetes, the operator populates this from spec.groupRef during conversion.
                    type: string
                  incomingAuth:
                    description: |-
                      IncomingAuth configures how clients authenticate to the virtual MCP server.
                      When using the Kubernetes operator, this is populated by the converter from
                      VirtualMCPServerSpec.IncomingAuth and any values set here will be superseded.
                    properties:
                      authz:
                        description: Authz contains authorization configuration (optional).
                        properties:
                          entitiesJson:
                            description: |-
                              EntitiesJSON is a JSON string representing Cedar entities. Required for
                              enterprise policies that rely on transitive relationships (e.g.
                              `ClaimGroup → PlatformRole`) — without it the Cedar authorizer is
                              constructed with an empty entity store and `in` checks against absent
                              entities silently evaluate to false. Defaults to "[]" when empty.
                            type: string
                          groupClaimName:
                            description: |-
                              GroupClaimName is the JWT claim key that contains group membership for
                              the principal. When set, takes priority over the well-known defaults
                              ("groups", "roles", "cognito:groups"). Use this for IDPs that place
                              groups under a URI-style claim (e.g. "https://example.com/groups").
                              When empty, only the well-known claim names are checked.
                            type: string
                          groupEntityType:
                            description: |-
                              GroupEntityType is the Cedar entity type name used for principal parent
                              UIDs synthesised from JWT group/role claims. Defaults to "THVGroup" when
                              empty. Must match the entity type used in EntitiesJSON for transitive
                              `in` checks to resolve. Namespaced names (`Foo::Bar`) are not yet supported.
                            type: string
                          policies:
                            description: Policies contains Cedar policy definitions
                              (when Type = "cedar").
                            items:
                              type: string
                            type: array
                          primaryUpstreamProvider:
                            description: |-
                              PrimaryUpstreamProvider names the upstream IDP provider whose access
                              token should be used as the source of JWT claims for Cedar evaluation.
                              When empty, claims from the ToolHive-issued token are used.
                              Must match an upstream provider name configured in the embedded auth server
                              (e.g. "default", "github"). Only relevant when the embedded auth server is active.
                            type: string
                          roleClaimName:
                            description: |-
                              RoleClaimName is the JWT claim key that contains role membership for the
                              principal. When set, the claim is extracted separately from GroupClaimName
                              and both are mapped to the configured group entity type. When empty, no
                              role extraction is performed.
                            type: string
                          type:
                            description: 'Type is the authz type: "cedar", "none"'
                            type: string
                        required:
                        - type
                        type: object
                      oidc:
                        description: OIDC contains OIDC configuration (when Type =
                          "oidc").
                        properties:
                          audience:
                            description: Audience is the required token audience.
                            type: string
                          clientId:
                            description: ClientID is the OAuth client ID.
                            type: string
                          clientSecretEnv:
                            description: |-
                              ClientSecretEnv is the name of the environment variable containing the client secret.
                              This is the secure way to reference secrets - the actual secret value is never stored
                              in configuration files, only the environment variable name.
                              The secret value will be resolved from this environment variable at runtime.
                            type: string
                          insecureAllowHttp:
                            description: |-
                              InsecureAllowHTTP allows HTTP (non-HTTPS) OIDC issuers for development/testing
                              WARNING: This is insecure and should NEVER be used in production
                            type: boolean
                          introspectionUrl:
                            description: |-
                              IntrospectionURL is the token introspection endpoint URL (RFC 7662).
                              When set, enables token introspection for opaque (non-JWT) tokens.
                            type: string
                          issuer:
                            description: Issuer is the OIDC issuer URL.
                            pattern: ^https?://
                            type: string
                          jwksAllowPrivateIp:
                            description: |-
                              JwksAllowPrivateIP allows OIDC discovery and JWKS fetches to private IP addresses.
                              Enable when the embedded auth server runs on a loopback address and
                              the OIDC middleware needs to fetch its JWKS from that address.
                              Use with caution - only enable for trusted internal IDPs or testing.
                            type: boolean
                          jwksUrl:
                            description: |-
                              JWKSURL is the explicit JWKS endpoint URL.
                              When set, skips OIDC discovery and fetches the JWKS directly from this URL.
                              This is useful when the OIDC issuer does not serve a /.well-known/openid-configuration.
                            type: string
                          protectedResourceAllowPrivateIp:
                            description: |-
                              ProtectedResourceAllowPrivateIP allows protected resource endpoint on private IP addresses
                              Use with caution - only enable for trusted internal IDPs or testing
                            type: boolean
                          resource:
                            description: |-
                              Resource is the OAuth 2.0 resource indicator (RFC 8707).
                              Used in WWW-Authenticate header and OAuth discovery metadata (RFC 9728).
                              If not specified, defaults to Audience.
                            type: string
                          scopes:
                            description: Scopes are the required OAuth scopes.
                            items:
                              type: string
                            type: array
                        required:
                        - audience
                        - clientId
                        - issuer
                        type: object
                      type:
                        description: 'Type is the auth type: "oidc", "local", "anonymous"'
                        type: string
                    required:
                    - type
                    type: object
                  metadata:
                    additionalProperties:
                      type: string
                    description: Metadata stores additional configuration metadata.
                    type: object
                  name:
                    description: Name is the virtual MCP server name.
                    type: string
                  operational:
                    description: Operational configures operational settings.
                    properties:
                      failureHandling:
                        description: FailureHandling configures failure handling behavior.
                        properties:
                          circuitBreaker:
                            description: CircuitBreaker configures circuit breaker
                              behavior.
                            properties:
                              enabled:
                                default: false
                                description: Enabled controls whether circuit breaker
                                  is enabled.
                                type: boolean
                              failureThreshold:
                                default: 5
                                description: |-
                                  FailureThreshold is the number of failures before opening the circuit.
                                  Must be >= 1.
                                minimum: 1
                                type: integer
                              timeout:
                                default: 60s
                                description: |-
                                  Timeout is the duration to wait before attempting to close the circuit.
                                  Must be >= 1s to prevent thrashing.
                                pattern: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
                                type: string
                                x-kubernetes-validations:
                                - message: timeout must be >= 1s
                                  rule: self == '' || duration(self) >= duration('1s')
                            type: object
                          healthCheckInterval:
                            default: 30s
                            description: HealthCheckInterval is the interval between
                              health checks.
                            pattern: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
                            type: string
                          healthCheckTimeout:
                            default: 10s
                            description: |-
                              HealthCheckTimeout is the maximum duration for a single health check operation.
                              Should be less than HealthCheckInterval to prevent checks from queuing up.
                            pattern: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
                            type: string
                          partialFailureMode:
                            default: fail
                            description: |-
                              PartialFailureMode defines behavior when some backends are unavailable.
                              - fail: Fail entire request if any backend is unavailable
                              - best_effort: Continue with available backends
                            enum:
                            - fail
                            - best_effort
                            type: string
                          statusReportingInterval:
                            default: 30s
                            description: |-
                              StatusReportingInterval is the interval for reporting status updates to Kubernetes.
                              This controls how often the vMCP runtime reports backend health and phase changes.
                              Lower values provide faster status updates but increase API server load.
                            pattern: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
                            type: string
                          unhealthyThreshold:
                            default: 3
                            description: UnhealthyThreshold is the number of consecutive
                              failures before marking unhealthy.
                            type: integer
                        type: object
                      logLevel:
                        description: |-
                          LogLevel sets the logging level for the Virtual MCP server.
                          The only valid value is "debug" to enable debug logging.
                          When omitted or empty, the server uses info level logging.
                        enum:
                        - debug
                        type: string
                      timeouts:
                        description: Timeouts configures timeout settings.
                        properties:
                          default:
                            default: 30s
                            description: Default is the default timeout for backend
                              requests.
                            pattern: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
                            type: string
                          perWorkload:
                            additionalProperties:
                              pattern: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
                              type: string
                            description: PerWorkload defines per-workload timeout
                              overrides.
                            type: object
                        type: object
                    type: object
                  optimizer:
                    description: |-
                      Optimizer configures the MCP optimizer for context optimization on large toolsets.
                      When enabled, vMCP exposes only find_tool and call_tool operations to clients
                      instead of all backend tools directly. This reduces token usage by allowing
                      LLMs to discover relevant tools on demand rather than receiving all tool definitions.
                    properties:
                      embeddingService:
                        description: |-
                          EmbeddingService is the full base URL of the embedding service endpoint
                          (e.g., http://my-embedding.default.svc.cluster.local:8080) for semantic
                          tool discovery.

                          In a Kubernetes environment, it is more convenient to use the
                          VirtualMCPServerSpec.EmbeddingServerRef field instead of setting this
                          directly. EmbeddingServerRef references an EmbeddingServer CRD by name,
                          and the operator automatically resolves the referenced resource's
                          Status.URL to populate this field. This provides managed lifecycle
                          (the operator watches the EmbeddingServer for readiness and URL changes)
                          and avoids hardcoding service URLs in the config. If both
                          EmbeddingServerRef and this field are set, EmbeddingServerRef takes
                          precedence and this value is overridden with a warning.
                        type: string
                      embeddingServiceTimeout:
                        default: 30s
                        description: |-
                          EmbeddingServiceTimeout is the HTTP request timeout for calls to the embedding service.
                          Defaults to 30s if not specified.
                        pattern: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
                        type: string
                      hybridSearchSemanticRatio:
                        description: |-
                          HybridSearchSemanticRatio controls the balance between semantic (meaning-based)
                          and keyword search results. 0.0 = all keyword, 1.0 = all semantic.
                          Defaults to "0.5" if not specified or empty.
                          Serialized as a string because CRDs do not support float types portably.
                        pattern: ^([0-9]*[.])?[0-9]+$
                        type: string
                      maxToolsToReturn:
                        description: |-
                          MaxToolsToReturn is the maximum number of tool results returned by a search query.
                          Defaults to 8 if not specified or zero.
                        maximum: 50
                        minimum: 1
                        type: integer
                      semanticDistanceThreshold:
                        description: |-
                          SemanticDistanceThreshold is the maximum distance for semantic search results.
                          Results exceeding this threshold are filtered out from semantic search.
                          This threshold does not apply to keyword search.
                          Range: 0 = identical, 2 = completely unrelated.
                          Defaults to "1.0" if not specified or empty.
                          Serialized as a string because CRDs do not support float types portably.
                        pattern: ^([0-9]*[.])?[0-9]+$
                        type: string
                    type: object
                  outgoingAuth:
                    description: |-
                      OutgoingAuth configures how the virtual MCP server authenticates to backends.
                      When using the Kubernetes operator, this is populated by the converter from
                      VirtualMCPServerSpec.OutgoingAuth and any values set here will be superseded.
                    properties:
                      backends:
                        additionalProperties:
                          description: |-
                            BackendAuthStrategy defines how to authenticate to a specific backend.

                            This struct provides type-safe configuration for different authentication strategies
                            using HeaderInjection or TokenExchange fields based on the Type field.
                          properties:
                            awsSts:
                              description: |-
                                AwsSts contains configuration for AWS STS auth strategy.
                                Used when Type = "aws_sts".
                              properties:
                                fallbackRoleArn:
                                  description: FallbackRoleArn is the IAM role ARN
                                    to assume when no role mappings match.
                                  type: string
                                region:
                                  description: Region is the AWS region for the STS
                                    endpoint and service.
                                  type: string
                                roleClaim:
                                  description: RoleClaim is the JWT claim to use for
                                    role mapping evaluation.
                                  type: string
                                roleMappings:
                                  description: RoleMappings defines claim-based role
                                    selection rules.
                                  items:
                                    description: |-
                                      RoleMapping defines a rule for mapping JWT claims to IAM roles.
                                      Mappings are evaluated in priority order (lower number = higher priority).
                                    properties:
                                      claim:
                                        description: Claim is a simple claim value
                                          to match against the RoleClaim field.
                                        type: string
                                      matcher:
                                        description: Matcher is a CEL expression for
                                          complex matching against JWT claims.
                                        type: string
                                      priority:
                                        description: |-
                                          Priority determines evaluation order (lower values = higher priority).
                                          Mirrors awssts.RoleMapping.Priority, which is *int because the role mapper
                                          uses math.MaxInt for nil-priority semantics in effectivePriority.
                                        type: integer
                                      roleArn:
                                        description: RoleArn is the IAM role ARN to
                                          assume when this mapping matches.
                                        type: string
                                    required:
                                    - roleArn
                                    type: object
                                  type: array
                                  x-kubernetes-list-type: atomic
                                service:
                                  description: Service is the AWS service name for
                                    SigV4 signing.
                                  type: string
                                sessionDuration:
                                  description: SessionDuration is the duration in
                                    seconds for the STS session.
                                  format: int32
                                  type: integer
                                sessionNameClaim:
                                  description: SessionNameClaim is the JWT claim to
                                    use for the role session name.
                                  type: string
                                subjectProviderName:
                                  description: |-
                                    SubjectProviderName selects which upstream provider's token to use as the
                                    web identity token for AssumeRoleWithWebIdentity. When set, the token is
                                    looked up from Identity.UpstreamTokens instead of the request's
                                    Authorization header.
                                  type: string
                              required:
                              - region
                              type: object
                            headerInjection:
                              description: |-
                                HeaderInjection contains configuration for header injection auth strategy.
                                Used when Type = "header_injection".
                              properties:
                                headerName:
                                  description: HeaderName is the name of the header
                                    to inject (e.g., "Authorization").
                                  type: string
                                headerValue:
                                  description: |-
                                    HeaderValue is the static header value to inject.
                                    Either HeaderValue or HeaderValueEnv should be set, not both.
                                  type: string
                                headerValueEnv:
                                  description: |-
                                    HeaderValueEnv is the environment variable name containing the header value.
                                    The value will be resolved at runtime from this environment variable.
                                    Either HeaderValue or HeaderValueEnv should be set, not both.
                                  type: string
                              required:
                              - headerName
                              type: object
                            tokenExchange:
                              description: |-
                                TokenExchange contains configuration for token exchange auth strategy.
                                Used when Type = "token_exchange".
                              properties:
                                audience:
                                  description: Audience is the target audience for
                                    the exchanged token.
                                  type: string
                                clientId:
                                  description: ClientID is the OAuth client ID for
                                    the token exchange request.
                                  type: string
                                clientSecret:
                                  description: ClientSecret is the OAuth client secret
                                    (use ClientSecretEnv for security).
                                  type: string
                                clientSecretEnv:
                                  description: |-
                                    ClientSecretEnv is the environment variable name containing the client secret.
                                    The value will be resolved at runtime from this environment variable.
                                  type: string
                                scopes:
                                  description: Scopes are the requested scopes for
                                    the exchanged token.
                                  items:
                                    type: string
                                  type: array
                                subjectProviderName:
                                  description: |-
                                    SubjectProviderName selects which upstream provider's token to use as the
                                    subject token. When set, the token is looked up from Identity.UpstreamTokens
                                    instead of using Identity.Token.
                                    When left empty and an embedded authorization server is configured, the system
                                    automatically populates this field with the first configured upstream provider name.
                                    Set it explicitly to override that default or to select a specific provider when
                                    multiple upstreams are configured.
                                  type: string
                                subjectTokenType:
                                  description: |-
                                    SubjectTokenType is the token type of the incoming subject token.
                                    Defaults to "urn:ietf:params:oauth:token-type:access_token" if not specified.
                                  type: string
                                tokenUrl:
                                  description: TokenURL is the OAuth token endpoint
                                    URL for token exchange.
                                  type: string
                              required:
                              - tokenUrl
                              type: object
                            type:
                              description: 'Type is the auth strategy: "unauthenticated",
                                "header_injection", "token_exchange", "upstream_inject",
                                "aws_sts", "obo"'
                              type: string
                            upstreamInject:
                              description: |-
                                UpstreamInject contains configuration for upstream inject auth strategy.
                                Used when Type = "upstream_inject".
                              properties:
                                providerName:
                                  description: |-
                                    ProviderName is the name of the upstream provider configured in the
                                    embedded authorization server. Must match an entry in AuthServer.Upstreams.
                                  type: string
                              required:
                              - providerName
                              type: object
                          required:
                          - type
                          type: object
                        description: Backends contains per-backend auth configuration.
                        type: object
                      default:
                        description: Default is the default auth strategy for backends
                          without explicit config.
                        properties:
                          awsSts:
                            description: |-
                              AwsSts contains configuration for AWS STS auth strategy.
                              Used when Type = "aws_sts".
                            properties:
                              fallbackRoleArn:
                                description: FallbackRoleArn is the IAM role ARN to
                                  assume when no role mappings match.
                                type: string
                              region:
                                description: Region is the AWS region for the STS
                                  endpoint and service.
                                type: string
                              roleClaim:
                                description: RoleClaim is the JWT claim to use for
                                  role mapping evaluation.
                                type: string
                              roleMappings:
                                description: RoleMappings defines claim-based role
                                  selection rules.
                                items:
                                  description: |-
                                    RoleMapping defines a rule for mapping JWT claims to IAM roles.
                                    Mappings are evaluated in priority order (lower number = higher priority).
                                  properties:
                                    claim:
                                      description: Claim is a simple claim value to
                                        match against the RoleClaim field.
                                      type: string
                                    matcher:
                                      description: Matcher is a CEL expression for
                                        complex matching against JWT claims.
                                      type: string
                                    priority:
                                      description: |-
                                        Priority determines evaluation order (lower values = higher priority).
                                        Mirrors awssts.RoleMapping.Priority, which is *int because the role mapper
                                        uses math.MaxInt for nil-priority semantics in effectivePriority.
                                      type: integer
                                    roleArn:
                                      description: RoleArn is the IAM role ARN to
                                        assume when this mapping matches.
                                      type: string
                                  required:
                                  - roleArn
                                  type: object
                                type: array
                                x-kubernetes-list-type: atomic
                              service:
                                description: Service is the AWS service name for SigV4
                                  signing.
                                type: string
                              sessionDuration:
                                description: SessionDuration is the duration in seconds
                                  for the STS session.
                                format: int32
                                type: integer
                              sessionNameClaim:
                                description: SessionNameClaim is the JWT claim to
                                  use for the role session name.
                                type: string
                              subjectProviderName:
                                description: |-
                                  SubjectProviderName selects which upstream provider's token to use as the
                                  web identity token for AssumeRoleWithWebIdentity. When set, the token is
                                  looked up from Identity.UpstreamTokens instead of the request's
                                  Authorization header.
                                type: string
                            required:
                            - region
                            type: object
                          headerInjection:
                            description: |-
                              HeaderInjection contains configuration for header injection auth strategy.
                              Used when Type = "header_injection".
                            properties:
                              headerName:
                                description: HeaderName is the name of the header
                                  to inject (e.g., "Authorization").
                                type: string
                              headerValue:
                                description: |-
                                  HeaderValue is the static header value to inject.
                                  Either HeaderValue or HeaderValueEnv should be set, not both.
                                type: string
                              headerValueEnv:
                                description: |-
                                  HeaderValueEnv is the environment variable name containing the header value.
                                  The value will be resolved at runtime from this environment variable.
                                  Either HeaderValue or HeaderValueEnv should be set, not both.
                                type: string
                            required:
                            - headerName
                            type: object
                          tokenExchange:
                            description: |-
                              TokenExchange contains configuration for token exchange auth strategy.
                              Used when Type = "token_exchange".
                            properties:
                              audience:
                                description: Audience is the target audience for the
                                  exchanged token.
                                type: string
                              clientId:
                                description: ClientID is the OAuth client ID for the
                                  token exchange request.
                                type: string
                              clientSecret:
                                description: ClientSecret is the OAuth client secret
                                  (use ClientSecretEnv for security).
                                type: string
                              clientSecretEnv:
                                description: |-
                                  ClientSecretEnv is the environment variable name containing the client secret.
                                  The value will be resolved at runtime from this environment variable.
                                type: string
                              scopes:
                                description: Scopes are the requested scopes for the
                                  exchanged token.
                                items:
                                  type: string
                                type: array
                              subjectProviderName:
                                description: |-
                                  SubjectProviderName selects which upstream provider's token to use as the
                                  subject token. When set, the token is looked up from Identity.UpstreamTokens
                                  instead of using Identity.Token.
                                  When left empty and an embedded authorization server is configured, the system
                                  automatically populates this field with the first configured upstream provider name.
                                  Set it explicitly to override that default or to select a specific provider when
                                  multiple upstreams are configured.
                                type: string
                              subjectTokenType:
                                description: |-
                                  SubjectTokenType is the token type of the incoming subject token.
                                  Defaults to "urn:ietf:params:oauth:token-type:access_token" if not specified.
                                type: string
                              tokenUrl:
                                description: TokenURL is the OAuth token endpoint
                                  URL for token exchange.
                                type: string
                            required:
                            - tokenUrl
                            type: object
                          type:
                            description: 'Type is the auth strategy: "unauthenticated",
                              "header_injection", "token_exchange", "upstream_inject",
                              "aws_sts", "obo"'
                            type: string
                          upstreamInject:
                            description: |-
                              UpstreamInject contains configuration for upstream inject auth strategy.
                              Used when Type = "upstream_inject".
                            properties:
                              providerName:
                                description: |-
                                  ProviderName is the name of the upstream provider configured in the
                                  embedded authorization server. Must match an entry in AuthServer.Upstreams.
                                type: string
                            required:
                            - providerName
                            type: object
                        required:
                        - type
                        type: object
                      source:
                        description: |-
                          Source defines how to discover backend auth: "inline", "discovered"
                          - inline: Explicit configuration in OutgoingAuth
                          - discovered: Auto-discover from backend MCPServer.externalAuthConfigRef (Kubernetes only)
                        type: string
                    required:
                    - source
                    type: object
                  rateLimiting:
                    description: |-
                      RateLimiting defines rate limiting configuration for the Virtual MCP server.
                      Requires Redis session storage to be configured for distributed rate limiting.
                    properties:
                      perUser:
                        description: |-
                          PerUser is a token bucket applied independently to each authenticated user
                          at the server level. Requires authentication to be enabled.
                          Each unique userID creates Redis keys that expire after 2x refillPeriod.
                          Memory formula: unique_users_per_TTL_window * (1 + num_tools_with_per_user_limits) keys.
                        properties:
                          maxTokens:
                            description: |-
                              MaxTokens is the maximum number of tokens (bucket capacity).
                              This is also the burst size: the maximum number of requests that can be served
                              instantaneously before the bucket is depleted.
                            format: int32
                            minimum: 1
                            type: integer
                          refillPeriod:
                            description: |-
                              RefillPeriod is the duration to fully refill the bucket from zero to maxTokens.
                              The effective refill rate is maxTokens / refillPeriod tokens per second.
                              Format: Go duration string (e.g., "1m0s", "30s", "1h0m0s").
                            type: string
                        required:
                        - maxTokens
                        - refillPeriod
                        type: object
                      shared:
                        description: Shared is a token bucket shared across all users
                          for the entire server.
                        properties:
                          maxTokens:
                            description: |-
                              MaxTokens is the maximum number of tokens (bucket capacity).
                              This is also the burst size: the maximum number of requests that can be served
                              instantaneously before the bucket is depleted.
                            format: int32
                            minimum: 1
                            type: integer
                          refillPeriod:
                            description: |-
                              RefillPeriod is the duration to fully refill the bucket from zero to maxTokens.
                              The effective refill rate is maxTokens / refillPeriod tokens per second.
                              Format: Go duration string (e.g., "1m0s", "30s", "1h0m0s").
                            type: string
                        required:
                        - maxTokens
                        - refillPeriod
                        type: object
                      tools:
                        description: |-
                          Tools defines per-tool rate limit overrides.
                          Each entry applies additional rate limits to calls targeting a specific tool name.
                          A request must pass both the server-level limit and the per-tool limit.
                        items:
                          description: |-
                            ToolRateLimitConfig defines rate limits for a specific tool.
                            At least one of shared or perUser must be configured.
                          properties:
                            name:
                              description: Name is the MCP tool name this limit applies
                                to.
                              minLength: 1
                              type: string
                            perUser:
                              description: PerUser token bucket configuration for
                                this tool.
                              properties:
                                maxTokens:
                                  description: |-
                                    MaxTokens is the maximum number of tokens (bucket capacity).
                                    This is also the burst size: the maximum number of requests that can be served
                                    instantaneously before the bucket is depleted.
                                  format: int32
                                  minimum: 1
                                  type: integer
                                refillPeriod:
                                  description: |-
                                    RefillPeriod is the duration to fully refill the bucket from zero to maxTokens.
                                    The effective refill rate is maxTokens / refillPeriod tokens per second.
                                    Format: Go duration string (e.g., "1m0s", "30s", "1h0m0s").
                                  type: string
                              required:
                              - maxTokens
                              - refillPeriod
                              type: object
                            shared:
                              description: Shared token bucket for this specific tool.
                              properties:
                                maxTokens:
                                  description: |-
                                    MaxTokens is the maximum number of tokens (bucket capacity).
                                    This is also the burst size: the maximum number of requests that can be served
                                    instantaneously before the bucket is depleted.
                                  format: int32
                                  minimum: 1
                                  type: integer
                                refillPeriod:
                                  description: |-
                                    RefillPeriod is the duration to fully refill the bucket from zero to maxTokens.
                                    The effective refill rate is maxTokens / refillPeriod tokens per second.
                                    Format: Go duration string (e.g., "1m0s", "30s", "1h0m0s").
                                  type: string
                              required:
                              - maxTokens
                              - refillPeriod
                              type: object
                          required:
                          - name
                          type: object
                          x-kubernetes-validations:
                          - message: at least one of shared or perUser must be configured
                            rule: has(self.shared) || has(self.perUser)
                        type: array
                        x-kubernetes-list-map-keys:
                        - name
                        x-kubernetes-list-type: map
                    type: object
                    x-kubernetes-validations:
                    - message: at least one of shared, perUser, or tools must be configured
                      rule: has(self.shared) || has(self.perUser) || (has(self.tools)
                        && size(self.tools) > 0)
                  sessionStorage:
                    description: |-
                      SessionStorage configures session storage for stateful horizontal scaling.
                      When provider is "redis", the operator injects Redis connection parameters
                      (address, db, keyPrefix) here. The Redis password is provided separately via
                      the THV_SESSION_REDIS_PASSWORD environment variable.
                    properties:
                      address:
                        description: Address is the Redis server address (required
                          when provider is redis).
                        type: string
                      db:
                        default: 0
                        description: DB is the Redis database number.
                        format: int32
                        minimum: 0
                        type: integer
                      keyPrefix:
                        description: KeyPrefix is an optional prefix for all Redis
                          keys used by ToolHive.
                        type: string
                      provider:
                        description: Provider is the session storage backend type.
                        enum:
                        - memory
                        - redis
                        type: string
                    required:
                    - provider
                    type: object
                  telemetry:
                    description: |-
                      Telemetry configures OpenTelemetry-based observability for the Virtual MCP server
                      including distributed tracing, OTLP metrics export, and Prometheus metrics endpoint.
                      Deprecated (Kubernetes operator only): When deploying via the operator, use
                      VirtualMCPServer.spec.telemetryConfigRef to reference a shared MCPTelemetryConfig
                      resource instead. This field remains valid for standalone (non-operator) deployments.
                    properties:
                      caCertPath:
                        description: |-
                          CACertPath is the file path to a CA certificate bundle for the OTLP endpoint.
                          When set, the OTLP exporters use this CA to verify the collector's TLS certificate
                          instead of relying solely on the system CA pool.
                        type: string
                      customAttributes:
                        additionalProperties:
                          type: string
                        description: |-
                          CustomAttributes contains custom resource attributes to be added to all telemetry signals.
                          These are parsed from CLI flags (--otel-custom-attributes) or environment variables
                          (OTEL_RESOURCE_ATTRIBUTES) as key=value pairs.
                        type: object
                      enablePrometheusMetricsPath:
                        default: false
                        description: |-
                          EnablePrometheusMetricsPath controls whether to expose Prometheus-style /metrics endpoint.
                          The metrics are served on the main transport port at /metrics.
                          This is separate from OTLP metrics which are sent to the Endpoint.
                        type: boolean
                      endpoint:
                        description: Endpoint is the OTLP endpoint URL
                        type: string
                      environmentVariables:
                        description: |-
                          EnvironmentVariables is a list of environment variable names that should be
                          included in telemetry spans as attributes. Only variables in this list will
                          be read from the host machine and included in spans for observability.
                          Example: ["NODE_ENV", "DEPLOYMENT_ENV", "SERVICE_VERSION"]
                        items:
                          type: string
                        type: array
                      headers:
                        additionalProperties:
                          type: string
                        description: Headers contains authentication headers for the
                          OTLP endpoint.
                        type: object
                      insecure:
                        default: false
                        description: Insecure indicates whether to use HTTP instead
                          of HTTPS for the OTLP endpoint.
                        type: boolean
                      metricsEnabled:
                        default: false
                        description: |-
                          MetricsEnabled controls whether OTLP metrics are enabled.
                          When false, OTLP metrics are not sent even if an endpoint is configured.
                          This is independent of EnablePrometheusMetricsPath.
                        type: boolean
                      samplingRate:
                        default: "0.05"
                        description: |-
                          SamplingRate is the trace sampling rate (0.0-1.0) as a string.
                          Only used when TracingEnabled is true.
                          Example: "0.05" for 5% sampling.
                        type: string
                      serviceName:
                        description: |-
                          ServiceName is the service name for telemetry.
                          When omitted, defaults to the server name (e.g., VirtualMCPServer name).
                        type: string
                      serviceVersion:
                        description: |-
                          ServiceVersion is the service version for telemetry.
                          When omitted, defaults to the ToolHive version.
                        type: string
                      tracingEnabled:
                        default: false
                        description: |-
                          TracingEnabled controls whether distributed tracing is enabled.
                          When false, no tracer provider is created even if an endpoint is configured.
                        type: boolean
                      useLegacyAttributes:
                        default: true
                        description: |-
                          UseLegacyAttributes controls whether legacy (pre-MCP OTEL semconv) attribute names
                          are emitted alongside the new standard attribute names. When true, spans include both
                          old and new attribute names for backward compatibility with existing dashboards.
                          Currently defaults to true; this will change to false in a future release.
                        type: boolean
                    type: object
                type: object
                x-kubernetes-preserve-unknown-fields: true
              embeddingServerRef:
                description: |-
                  EmbeddingServerRef references an existing EmbeddingServer resource by name.
                  When the optimizer is enabled, this field is required to point to a ready EmbeddingServer
                  that provides embedding capabilities.
                  The referenced EmbeddingServer must exist in the same namespace and be ready.
                properties:
                  name:
                    description: Name is the name of the EmbeddingServer resource
                    type: string
                required:
                - name
                type: object
              groupRef:
                description: |-
                  GroupRef references the MCPGroup that defines backend workloads.
                  The referenced MCPGroup must exist in the same namespace.
                properties:
                  name:
                    description: Name is the name of the MCPGroup resource in the
                      same namespace
                    minLength: 1
                    type: string
                required:
                - name
                type: object
              imagePullSecrets:
                description: |-
                  ImagePullSecrets allows specifying image pull secrets for the vMCP workload.
                  These are applied to both the vMCP Deployment's PodSpec.ImagePullSecrets
                  and to the operator-managed ServiceAccount the vMCP server runs as, so private
                  images are pullable through either path.

                  Merge semantics with PodTemplateSpec:
                  The deployed PodSpec.ImagePullSecrets is the Kubernetes-native strategic-merge
                  union of this field and spec.podTemplateSpec.spec.imagePullSecrets, merged by
                  the patchStrategy:"merge" / patchMergeKey:"name" tags on corev1.PodSpec.
                    - This field is rendered first as the controller-generated default.
                    - spec.podTemplateSpec.spec.imagePullSecrets is then strategic-merge-patched
                      on top, keyed by Name. Distinct names from the two sources are unioned in
                      the resulting list; entries with the same Name are deduplicated and the
                      PodTemplateSpec entry wins on overlap (user override).
                    - Order in the resulting list is not guaranteed and should not be relied on:
                      strategic merge by name is order-insensitive.
                    - The operator-managed ServiceAccount's imagePullSecrets list is populated
                      ONLY from this field. spec.podTemplateSpec.spec.imagePullSecrets does not
                      reach the ServiceAccount because PodTemplateSpec has no notion of a
                      ServiceAccount. To make a secret usable via the ServiceAccount path
                      (e.g. for sidecars or init containers that pull images independently),
                      list it here rather than under spec.podTemplateSpec.

                  Note on cross-CRD consistency:
                  MCPRegistry currently uses an atomic-replace strategy for its imagePullSecrets
                  (the user-provided value replaces the controller-generated list rather than
                  being merged on top). VirtualMCPServer follows the Kubernetes-native
                  strategic-merge-by-name behavior described above. Aligning the two is tracked
                  as a separate follow-up; until then, manifests that set imagePullSecrets on
                  both CRDs will see different override behavior between them.
                items:
                  description: |-
                    LocalObjectReference contains enough information to let you locate the
                    referenced object inside the same namespace.
                  properties:
                    name:
                      default: ""
                      description: |-
                        Name of the referent.
                        This field is effectively required, but due to backwards compatibility is
                        allowed to be empty. Instances of this type with an empty value here are
                        almost certainly wrong.
                        More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
                      type: string
                  type: object
                  x-kubernetes-map-type: atomic
                type: array
                x-kubernetes-list-type: atomic
              incomingAuth:
                description: |-
                  IncomingAuth configures authentication for clients connecting to the Virtual MCP server.
                  Must be explicitly set - use "anonymous" type when no authentication is required.
                  This field takes precedence over config.IncomingAuth and should be preferred because it
                  supports Kubernetes-native secret references (SecretKeyRef, ConfigMapRef) for secure
                  dynamic discovery of credentials, rather than requiring secrets to be embedded in config.
                properties:
                  authzConfig:
                    description: |-
                      AuthzConfig defines authorization policy configuration
                      Reuses MCPServer authz patterns
                    properties:
                      configMap:
                        description: |-
                          ConfigMap references a ConfigMap containing authorization configuration
                          Only used when Type is "configMap"
                        properties:
                          key:
                            default: authz.json
                            description: Key is the key in the ConfigMap that contains
                              the authorization configuration
                            type: string
                          name:
                            description: Name is the name of the ConfigMap
                            type: string
                        required:
                        - name
                        type: object
                      groupClaimName:
                        description: |-
                          GroupClaimName is the JWT claim key that contains group membership for the
                          principal. When set, takes priority over the well-known defaults
                          ("groups", "roles", "cognito:groups"). Use this for IDPs that place
                          groups under a URI-style claim (e.g. "https://example.com/groups"). When
                          Type is "configMap", a group_claim_name entry in the referenced ConfigMap
                          is overridden by this field if both are set.
                        maxLength: 253
                        type: string
                      groupEntityType:
                        description: |-
                          GroupEntityType is the Cedar entity type name used for principal parent
                          UIDs synthesised from JWT group/role claims. Defaults to "THVGroup" when
                          empty. Must match the entity type used in the static entity store for
                          transitive `in` checks (e.g. `ClaimGroup → PlatformRole`) to resolve.
                          Namespaced names (`Foo::Bar`) are not yet supported. When Type is
                          "configMap", a group_entity_type entry in the referenced ConfigMap is
                          overridden by this field if both are set.
                        maxLength: 63
                        pattern: ^[A-Za-z_][A-Za-z0-9_]*$
                        type: string
                      inline:
                        description: |-
                          Inline contains direct authorization configuration
                          Only used when Type is "inline"
                        properties:
                          entitiesJson:
                            default: '[]'
                            description: |-
                              EntitiesJSON is a JSON string representing Cedar entities. Required when
                              transitive policies (e.g. `ClaimGroup → PlatformRole`) need a static
                              entity store; defaults to "[]".
                            type: string
                          policies:
                            description: Policies is a list of Cedar policy strings
                            items:
                              type: string
                            minItems: 1
                            type: array
                            x-kubernetes-list-type: atomic
                          primaryUpstreamProvider:
                            description: |-
                              PrimaryUpstreamProvider names the upstream IDP whose access token's
                              claims Cedar should evaluate.

                              Deprecated: on VirtualMCPServer this field has moved to
                              spec.authServerConfig.primaryUpstreamProvider. The old location is
                              still read for one release for backward compatibility; the
                              VirtualMCPServer controller emits an AuthzPrimaryUpstreamProviderDeprecated
                              Warning event whenever it is consumed, and removal is planned for the
                              release after the deprecation cycle.

                              On MCPServer and MCPRemoteProxy this field has always been a structural
                              no-op (those CRDs do not run an embedded auth server). Setting it
                              continues to surface the AuthzPrimaryUpstreamProviderIgnored advisory
                              condition; the deprecation does not change that behaviour.
                            maxLength: 63
                            minLength: 1
                            pattern: ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$
                            type: string
                        required:
                        - policies
                        type: object
                      roleClaimName:
                        description: |-
                          RoleClaimName is the JWT claim key that contains role membership for the
                          principal. When set, the claim is extracted separately from GroupClaimName
                          and both are mapped to the configured GroupEntityType. When Type is
                          "configMap", a role_claim_name entry in the referenced ConfigMap is
                          overridden by this field if both are set.
                        maxLength: 253
                        type: string
                      type:
                        default: configMap
                        description: Type is the type of authorization configuration
                        enum:
                        - configMap
                        - inline
                        type: string
                    required:
                    - type
                    type: object
                    x-kubernetes-validations:
                    - message: configMap must be set when type is 'configMap', and
                        must not be set otherwise
                      rule: 'self.type == ''configMap'' ? has(self.configMap) : !has(self.configMap)'
                    - message: inline must be set when type is 'inline', and must
                        not be set otherwise
                      rule: 'self.type == ''inline'' ? has(self.inline) : !has(self.inline)'
                  oidcConfigRef:
                    description: |-
                      OIDCConfigRef references a shared MCPOIDCConfig resource for OIDC authentication.
                      The referenced MCPOIDCConfig must exist in the same namespace as this VirtualMCPServer.
                      Per-server overrides (audience, scopes) are specified here; shared provider config
                      lives in the MCPOIDCConfig resource.
                    properties:
                      audience:
                        description: |-
                          Audience is the expected audience for token validation.
                          This MUST be unique per server to prevent token replay attacks.
                        minLength: 1
                        type: string
                      name:
                        description: Name is the name of the MCPOIDCConfig resource
                        minLength: 1
                        type: string
                      resourceUrl:
                        description: |-
                          ResourceURL is the public URL for OAuth protected resource metadata (RFC 9728).
                          When the server is exposed via Ingress or gateway, set this to the external
                          URL that MCP clients connect to. If not specified, defaults to the internal
                          Kubernetes service URL.
                        type: string
                      scopes:
                        description: |-
                          Scopes is the list of OAuth scopes to advertise in the well-known endpoint (RFC 9728).
                          If empty, defaults to ["openid"].
                        items:
                          type: string
                        type: array
                        x-kubernetes-list-type: atomic
                    required:
                    - audience
                    - name
                    type: object
                  type:
                    description: |-
                      Type defines the authentication type: anonymous or oidc
                      When no authentication is required, explicitly set this to "anonymous"
                    enum:
                    - anonymous
                    - oidc
                    type: string
                required:
                - type
                type: object
                x-kubernetes-validations:
                - message: spec.incomingAuth.oidcConfigRef is required when type is
                    oidc
                  rule: 'self.type == ''oidc'' ? has(self.oidcConfigRef) : true'
              outgoingAuth:
                description: |-
                  OutgoingAuth configures authentication from Virtual MCP to backend MCPServers.
                  This field takes precedence over config.OutgoingAuth and should be preferred because it
                  supports Kubernetes-native secret references (SecretKeyRef, ConfigMapRef) for secure
                  dynamic discovery of credentials, rather than requiring secrets to be embedded in config.
                properties:
                  backends:
                    additionalProperties:
                      description: BackendAuthConfig defines authentication configuration
                        for a backend MCPServer
                      properties:
                        externalAuthConfigRef:
                          description: |-
                            ExternalAuthConfigRef references an MCPExternalAuthConfig resource
                            Only used when Type is "externalAuthConfigRef"
                          properties:
                            name:
                              description: Name is the name of the MCPExternalAuthConfig
                                resource
                              type: string
                          required:
                          - name
                          type: object
                        type:
                          description: Type defines the authentication type
                          enum:
                          - discovered
                          - externalAuthConfigRef
                          type: string
                      required:
                      - type
                      type: object
                    description: |-
                      Backends defines per-backend authentication overrides
                      Works in all modes (discovered, inline)
                    type: object
                  default:
                    description: Default defines default behavior for backends without
                      explicit auth config
                    properties:
                      externalAuthConfigRef:
                        description: |-
                          ExternalAuthConfigRef references an MCPExternalAuthConfig resource
                          Only used when Type is "externalAuthConfigRef"
                        properties:
                          name:
                            description: Name is the name of the MCPExternalAuthConfig
                              resource
                            type: string
                        required:
                        - name
                        type: object
                      type:
                        description: Type defines the authentication type
                        enum:
                        - discovered
                        - externalAuthConfigRef
                        type: string
                    required:
                    - type
                    type: object
                  source:
                    default: discovered
                    description: |-
                      Source defines how backend authentication configurations are determined
                      - discovered: Automatically discover from backend's MCPServer.spec.externalAuthConfigRef
                      - inline: Explicit per-backend configuration in VirtualMCPServer
                    enum:
                    - discovered
                    - inline
                    type: string
                type: object
              podTemplateSpec:
                description: |-
                  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
                x-kubernetes-preserve-unknown-fields: true
              replicas:
                description: |-
                  Replicas is the desired number of vMCP pod replicas.
                  VirtualMCPServer creates a single Deployment for the vMCP aggregator process,
                  so there is only one replicas field (unlike MCPServer which has separate
                  Replicas and BackendReplicas for its two Deployments).
                  When nil, the operator does not set Deployment.Spec.Replicas, leaving replica
                  management to an HPA or other external controller.
                format: int32
                minimum: 0
                type: integer
              serviceAccount:
                description: |-
                  ServiceAccount is the name of an already existing service account to use by the Virtual MCP server.
                  If not specified, a ServiceAccount will be created automatically and used by the Virtual MCP server.
                type: string
              serviceType:
                default: ClusterIP
                description: ServiceType specifies the Kubernetes service type for
                  the Virtual MCP server
                enum:
                - ClusterIP
                - NodePort
                - LoadBalancer
                type: string
              sessionAffinity:
                default: ClientIP
                description: |-
                  SessionAffinity controls whether the Service routes repeated client connections to the same pod.
                  MCP protocols (SSE, streamable-http) are stateful, so ClientIP is the default.
                  Set to "None" for stateless servers or when using an external load balancer with its own affinity.
                enum:
                - ClientIP
                - None
                type: string
              sessionStorage:
                description: |-
                  SessionStorage configures session storage for stateful horizontal scaling.
                  When nil, no session storage is configured.
                properties:
                  address:
                    description: Address is the Redis server address (required when
                      provider is redis)
                    minLength: 1
                    type: string
                  db:
                    default: 0
                    description: DB is the Redis database number
                    format: int32
                    minimum: 0
                    type: integer
                  keyPrefix:
                    description: KeyPrefix is an optional prefix for all Redis keys
                      used by ToolHive
                    type: string
                  passwordRef:
                    description: PasswordRef is a reference to a Secret key containing
                      the Redis password
                    properties:
                      key:
                        description: Key is the key within the secret
                        type: string
                      name:
                        description: Name is the name of the secret
                        type: string
                    required:
                    - key
                    - name
                    type: object
                  provider:
                    description: Provider is the session storage backend type
                    enum:
                    - memory
                    - redis
                    type: string
                required:
                - provider
                type: object
                x-kubernetes-validations:
                - message: address is required
                  rule: 'self.provider == ''redis'' ? has(self.address) : true'
              telemetryConfigRef:
                description: |-
                  TelemetryConfigRef references an MCPTelemetryConfig resource for shared telemetry configuration.
                  The referenced MCPTelemetryConfig must exist in the same namespace as this VirtualMCPServer.
                  Cross-namespace references are not supported for security and isolation reasons.
                properties:
                  name:
                    description: Name is the name of the MCPTelemetryConfig resource
                    minLength: 1
                    type: string
                  serviceName:
                    description: |-
                      ServiceName overrides the telemetry service name for this specific server.
                      This MUST be unique per server for proper observability (e.g., distinguishing
                      traces and metrics from different servers sharing the same collector).
                      If empty, defaults to the server name with "thv-" prefix at runtime.
                    type: string
                required:
                - name
                type: object
            required:
            - groupRef
            - incomingAuth
            type: object
            x-kubernetes-validations:
            - message: config.rateLimiting requires sessionStorage with provider 'redis'
              rule: '!has(self.config) || !has(self.config.rateLimiting) || (has(self.sessionStorage)
                && self.sessionStorage.provider == ''redis'')'
            - message: config.rateLimiting.perUser requires incomingAuth.type oidc
              rule: '!(has(self.config) && has(self.config.rateLimiting) && has(self.config.rateLimiting.perUser))
                || (has(self.incomingAuth) && self.incomingAuth.type == ''oidc'')'
            - message: per-tool perUser rate limiting requires incomingAuth.type oidc
              rule: '!has(self.config) || !has(self.config.rateLimiting) || !has(self.config.rateLimiting.tools)
                || self.config.rateLimiting.tools.all(t, !has(t.perUser)) || (has(self.incomingAuth)
                && self.incomingAuth.type == ''oidc'')'
          status:
            description: VirtualMCPServerStatus defines the observed state of VirtualMCPServer
            properties:
              backendCount:
                description: |-
                  BackendCount is the number of routable backends (ready + unauthenticated).
                  Excludes unavailable, degraded, and unknown backends.
                format: int32
                type: integer
              conditions:
                description: Conditions represent the latest available observations
                  of the VirtualMCPServer's state
                items:
                  description: Condition contains details for one aspect of the current
                    state of this API Resource.
                  properties:
                    lastTransitionTime:
                      description: |-
                        lastTransitionTime is the last time the condition transitioned from one status to another.
                        This should be when the underlying condition changed.  If that is not known, then using the time when the API field changed is acceptable.
                      format: date-time
                      type: string
                    message:
                      description: |-
                        message is a human readable message indicating details about the transition.
                        This may be an empty string.
                      maxLength: 32768
                      type: string
                    observedGeneration:
                      description: |-
                        observedGeneration represents the .metadata.generation that the condition was set based upon.
                        For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date
                        with respect to the current state of the instance.
                      format: int64
                      minimum: 0
                      type: integer
                    reason:
                      description: |-
                        reason contains a programmatic identifier indicating the reason for the condition's last transition.
                        Producers of specific condition types may define expected values and meanings for this field,
                        and whether the values are considered a guaranteed API.
                        The value should be a CamelCase string.
                        This field may not be empty.
                      maxLength: 1024
                      minLength: 1
                      pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$
                      type: string
                    status:
                      description: status of the condition, one of True, False, Unknown.
                      enum:
                      - "True"
                      - "False"
                      - Unknown
                      type: string
                    type:
                      description: type of condition in CamelCase or in foo.example.com/CamelCase.
                      maxLength: 316
                      pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$
                      type: string
                  required:
                  - lastTransitionTime
                  - message
                  - reason
                  - status
                  - type
                  type: object
                type: array
                x-kubernetes-list-map-keys:
                - type
                x-kubernetes-list-type: map
              discoveredBackends:
                description: DiscoveredBackends lists discovered backend configurations
                  from the MCPGroup
                items:
                  description: |-
                    DiscoveredBackend represents a backend server discovered by vMCP runtime.
                    This type is shared with the Kubernetes operator CRD (VirtualMCPServer.Status.DiscoveredBackends).
                  properties:
                    authConfigRef:
                      description: AuthConfigRef is the name of the discovered MCPExternalAuthConfig
                        (if any)
                      type: string
                    authType:
                      description: AuthType is the type of authentication configured
                      type: string
                    circuitBreakerState:
                      description: |-
                        CircuitBreakerState is the current circuit breaker state (closed, open, half-open).
                        Empty when circuit breaker is disabled or not configured.
                      enum:
                      - closed
                      - open
                      - half-open
                      type: string
                    circuitLastChanged:
                      description: |-
                        CircuitLastChanged is the timestamp when the circuit breaker state last changed.
                        Empty when circuit breaker is disabled or has never changed state.
                      format: date-time
                      type: string
                    consecutiveFailures:
                      description: |-
                        ConsecutiveFailures is the current count of consecutive health check failures.
                        Resets to 0 when the backend becomes healthy again.
                      type: integer
                    lastHealthCheck:
                      description: LastHealthCheck is the timestamp of the last health
                        check
                      format: date-time
                      type: string
                    message:
                      description: Message provides additional information about the
                        backend status
                      type: string
                    name:
                      description: Name is the name of the backend MCPServer
                      type: string
                    status:
                      description: |-
                        Status is the current status of the backend (ready, degraded, unavailable, unauthenticated, unknown).
                        Use BackendHealthStatus.ToCRDStatus() to populate this field.
                      type: string
                    url:
                      description: URL is the URL of the backend MCPServer
                      type: string
                  required:
                  - name
                  type: object
                type: array
                x-kubernetes-list-map-keys:
                - name
                x-kubernetes-list-type: map
              message:
                description: Message provides additional information about the current
                  phase
                type: string
              observedGeneration:
                description: ObservedGeneration is the most recent generation observed
                  for this VirtualMCPServer
                format: int64
                type: integer
              oidcConfigHash:
                description: |-
                  OIDCConfigHash is the hash of the referenced MCPOIDCConfig spec for change detection.
                  Only populated when IncomingAuth.OIDCConfigRef is set.
                type: string
              phase:
                default: Pending
                description: Phase is the current phase of the VirtualMCPServer
                enum:
                - Pending
                - Ready
                - Degraded
                - Failed
                type: string
              telemetryConfigHash:
                description: |-
                  TelemetryConfigHash is the hash of the referenced MCPTelemetryConfig spec for change detection.
                  Only populated when TelemetryConfigRef is set.
                type: string
              url:
                description: URL is the URL where the Virtual MCP server can be accessed
                type: string
            type: object
        type: object
    served: true
    storage: false
    subresources:
      status: {}
  - additionalPrinterColumns:
    - description: The phase of the VirtualMCPServer
      jsonPath: .status.phase
      name: Phase
      type: string
    - description: Virtual MCP server URL
      jsonPath: .status.url
      name: URL
      type: string
    - description: Discovered backends count
      jsonPath: .status.backendCount
      name: Backends
      type: integer
    - description: Age
      jsonPath: .metadata.creationTimestamp
      name: Age
      type: date
    - jsonPath: .status.conditions[?(@.type=='Ready')].status
      name: Ready
      type: string
    name: v1beta1
    schema:
      openAPIV3Schema:
        description: |-
          VirtualMCPServer is the Schema for the virtualmcpservers API
          VirtualMCPServer aggregates multiple backend MCPServers into a unified endpoint
        properties:
          apiVersion:
            description: |-
              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
            type: string
          kind:
            description: |-
              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
            type: string
          metadata:
            type: object
          spec:
            description: VirtualMCPServerSpec defines the desired state of VirtualMCPServer
            properties:
              authServerConfig:
                description: |-
                  AuthServerConfig configures an embedded OAuth authorization server.
                  When set, the vMCP server acts as an OIDC issuer, drives users through
                  upstream IDPs, and issues ToolHive JWTs. The embedded AS becomes the
                  IncomingAuth OIDC provider — its issuer must match IncomingAuth.OIDCConfigRef
                  so that tokens it issues are accepted by the vMCP's incoming auth middleware.
                  When nil, IncomingAuth uses an external IDP and behavior is unchanged.
                properties:
                  authorizationEndpointBaseUrl:
                    description: |-
                      AuthorizationEndpointBaseURL overrides the base URL used for the authorization_endpoint
                      in the OAuth discovery document. When set, the discovery document will advertise
                      `{authorizationEndpointBaseUrl}/oauth/authorize` instead of `{issuer}/oauth/authorize`.
                      All other endpoints (token, registration, JWKS) remain derived from the issuer.
                      This is useful when the browser-facing authorization endpoint needs to be on a
                      different host than the issuer used for backend-to-backend calls.
                      Must be a valid HTTPS URL (or HTTP for localhost) without query, fragment, or trailing slash.
                    pattern: ^https?://[^\s?#]+[^/\s?#]$
                    type: string
                  baselineClientScopes:
                    description: |-
                      BaselineClientScopes is a baseline set of OAuth 2.0 scopes guaranteed to be
                      included in every client registration. The embedded auth server unions these
                      scopes into the registered set returned by RFC 7591 Dynamic Client
                      Registration, so a client that narrows the `scope` field at /oauth/register
                      can still request the baseline scopes at /oauth/authorize. All values must
                      be present in the upstream-derived scopesSupported set; the auth server
                      fails to start if any value is missing.

                      Security: every client registered via /oauth/register will gain the
                      ability to request these scopes at /oauth/authorize, regardless of what
                      the client itself requested. Keep the baseline narrow (typically
                      "openid" and "offline_access"). Adding a privileged scope here — e.g.
                      "admin:read" — would grant it to every DCR-registered client, including
                      public clients like Claude Code, Cursor, and VS Code.
                      When cimd.enabled is true, every dynamically resolved CIMD client will
                      also gain the ability to request these scopes, including third-party
                      clients resolved from arbitrary HTTPS URLs.
                    items:
                      minLength: 1
                      pattern: ^[\x21\x23-\x5B\x5D-\x7E]+$
                      type: string
                    maxItems: 10
                    type: array
                    x-kubernetes-list-type: atomic
                  cimd:
                    description: CIMD configures Client ID Metadata Document support.
                      When omitted, CIMD is disabled.
                    properties:
                      cacheFallbackTtl:
                        description: |-
                          CacheFallbackTTL is the fixed TTL applied to every cached CIMD document.
                          Cache-Control header parsing is not yet implemented; all entries use this value.
                          Format: Go duration string (e.g. "5m", "10m", "1h").
                          Defaults to 5 minutes when Enabled is true and this field is omitted.
                        pattern: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
                        type: string
                      cacheMaxSize:
                        description: |-
                          CacheMaxSize is the maximum number of CIMD documents held in the LRU cache.
                          Defaults to 256 when Enabled is true and this field is omitted.
                        minimum: 1
                        type: integer
                      enabled:
                        default: false
                        description: |-
                          Enabled activates CIMD client lookup. When false (the default), the AS only
                          accepts client_id values that were registered via DCR.
                        type: boolean
                    required:
                    - enabled
                    type: object
                  hmacSecretRefs:
                    description: |-
                      HMACSecretRefs references Kubernetes Secrets containing symmetric secrets for signing
                      authorization codes and refresh tokens (opaque tokens).
                      Current secret must be at least 32 bytes and cryptographically random.
                      Supports secret rotation via multiple entries (first is current, rest are for verification).
                      If not specified, an ephemeral secret will be auto-generated (development only -
                      auth codes and refresh tokens will be invalid after restart).
                    items:
                      description: SecretKeyRef is a reference to a key within a Secret
                      properties:
                        key:
                          description: Key is the key within the secret
                          type: string
                        name:
                          description: Name is the name of the secret
                          type: string
                      required:
                      - key
                      - name
                      type: object
                    type: array
                    x-kubernetes-list-type: atomic
                  issuer:
                    description: |-
                      Issuer is the issuer identifier for this authorization server.
                      This will be included in the "iss" claim of issued tokens.
                      Must be a valid HTTPS URL (or HTTP for localhost) without query, fragment, or trailing slash (per RFC 8414).
                    pattern: ^https?://[^\s?#]+[^/\s?#]$
                    type: string
                  primaryUpstreamProvider:
                    description: |-
                      PrimaryUpstreamProvider names the upstream IDP whose access token Cedar
                      should read claims from when authorising a request. Must match the name
                      of one of the entries in UpstreamProviders. When empty, the controller
                      auto-selects the first entry of UpstreamProviders.

                      Only meaningful on VirtualMCPServer, where multiple upstream providers
                      can be configured and Cedar needs to pick which token's claims to
                      evaluate. The VirtualMCPServer controller validates this field against
                      UpstreamProviders at admission and rejects unresolvable values.

                      On MCPServer and MCPRemoteProxy this field is structurally present (the
                      EmbeddedAuthServerConfig struct is shared) but has no runtime effect:
                      those CRDs are restricted to a single upstream so there is no choice to
                      make. Setting it on those CRDs is silently ignored.
                    maxLength: 63
                    minLength: 1
                    pattern: ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$
                    type: string
                  signingKeySecretRefs:
                    description: |-
                      SigningKeySecretRefs references Kubernetes Secrets containing signing keys for JWT operations.
                      Supports key rotation by allowing multiple keys (oldest keys are used for verification only).
                      If not specified, an ephemeral signing key will be auto-generated (development only -
                      JWTs will be invalid after restart).
                    items:
                      description: SecretKeyRef is a reference to a key within a Secret
                      properties:
                        key:
                          description: Key is the key within the secret
                          type: string
                        name:
                          description: Name is the name of the secret
                          type: string
                      required:
                      - key
                      - name
                      type: object
                    maxItems: 5
                    type: array
                    x-kubernetes-list-type: atomic
                  storage:
                    description: |-
                      Storage configures the storage backend for the embedded auth server.
                      If not specified, defaults to in-memory storage.
                    properties:
                      redis:
                        description: |-
                          Redis configures the Redis storage backend.
                          Required when type is "redis".
                        properties:
                          aclUserConfig:
                            description: ACLUserConfig configures Redis ACL user authentication.
                            properties:
                              passwordSecretRef:
                                description: PasswordSecretRef references a Secret
                                  containing the Redis ACL password.
                                properties:
                                  key:
                                    description: Key is the key within the secret
                                    type: string
                                  name:
                                    description: Name is the name of the secret
                                    type: string
                                required:
                                - key
                                - name
                                type: object
                              usernameSecretRef:
                                description: |-
                                  UsernameSecretRef references a Secret containing the Redis ACL username.
                                  When omitted, connections use legacy password-only AUTH. Omit for managed
                                  Redis tiers that do not support ACL users (e.g. GCP Memorystore Basic/Standard
                                  HA, Azure Cache for Redis). Set for services that support ACL users (e.g. AWS
                                  ElastiCache non-cluster with Redis 6+ RBAC).
                                properties:
                                  key:
                                    description: Key is the key within the secret
                                    type: string
                                  name:
                                    description: Name is the name of the secret
                                    type: string
                                required:
                                - key
                                - name
                                type: object
                            required:
                            - passwordSecretRef
                            type: object
                          addr:
                            description: |-
                              Addr is the Redis server address (host:port). Required for standalone and cluster modes.
                              Use for managed Redis services that expose a single endpoint (GCP Memorystore basic tier,
                              AWS ElastiCache without cluster mode, or cluster-mode services when clusterMode is true).
                              Mutually exclusive with sentinelConfig.
                            type: string
                          clusterMode:
                            description: |-
                              ClusterMode enables the Redis Cluster protocol. Set to true when addr points to a
                              Redis Cluster discovery endpoint (e.g., GCP Memorystore Cluster, AWS ElastiCache
                              cluster mode enabled). Requires addr to be set.
                            type: boolean
                          dialTimeout:
                            default: 5s
                            description: |-
                              DialTimeout is the timeout for establishing connections.
                              Format: Go duration string (e.g., "5s", "1m").
                            pattern: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
                            type: string
                          readTimeout:
                            default: 3s
                            description: |-
                              ReadTimeout is the timeout for socket reads.
                              Format: Go duration string (e.g., "3s", "1m").
                            pattern: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
                            type: string
                          sentinelConfig:
                            description: |-
                              SentinelConfig holds Redis Sentinel configuration.
                              Use for self-managed Redis with Sentinel-based HA. Mutually exclusive with addr.
                            properties:
                              db:
                                default: 0
                                description: DB is the Redis database number.
                                format: int32
                                type: integer
                              masterName:
                                description: MasterName is the name of the Redis master
                                  monitored by Sentinel.
                                type: string
                              sentinelAddrs:
                                description: |-
                                  SentinelAddrs is a list of Sentinel host:port addresses.
                                  Mutually exclusive with SentinelService.
                                items:
                                  type: string
                                type: array
                                x-kubernetes-list-type: atomic
                              sentinelService:
                                description: |-
                                  SentinelService enables automatic discovery from a Kubernetes Service.
                                  Mutually exclusive with SentinelAddrs.
                                properties:
                                  name:
                                    description: Name of the Sentinel Service.
                                    type: string
                                  namespace:
                                    description: Namespace of the Sentinel Service
                                      (defaults to same namespace).
                                    type: string
                                  port:
                                    default: 26379
                                    description: Port of the Sentinel service.
                                    format: int32
                                    type: integer
                                required:
                                - name
                                type: object
                            required:
                            - masterName
                            type: object
                          sentinelTls:
                            description: |-
                              SentinelTLS configures TLS for connections to Sentinel instances.
                              Only applies when sentinelConfig is set. Presence of this field enables TLS.
                            properties:
                              caCertSecretRef:
                                description: |-
                                  CACertSecretRef references a Secret containing a PEM-encoded CA certificate
                                  for verifying the server. When not specified, system root CAs are used.
                                properties:
                                  key:
                                    description: Key is the key within the secret
                                    type: string
                                  name:
                                    description: Name is the name of the secret
                                    type: string
                                required:
                                - key
                                - name
                                type: object
                              insecureSkipVerify:
                                description: |-
                                  InsecureSkipVerify skips TLS certificate verification.
                                  Use when connecting to services with self-signed certificates.
                                type: boolean
                            type: object
                          tls:
                            description: |-
                              TLS configures TLS for connections to the Redis/Valkey master or cluster nodes.
                              Presence of this field enables TLS. Omit to use plaintext.
                            properties:
                              caCertSecretRef:
                                description: |-
                                  CACertSecretRef references a Secret containing a PEM-encoded CA certificate
                                  for verifying the server. When not specified, system root CAs are used.
                                properties:
                                  key:
                                    description: Key is the key within the secret
                                    type: string
                                  name:
                                    description: Name is the name of the secret
                                    type: string
                                required:
                                - key
                                - name
                                type: object
                              insecureSkipVerify:
                                description: |-
                                  InsecureSkipVerify skips TLS certificate verification.
                                  Use when connecting to services with self-signed certificates.
                                type: boolean
                            type: object
                          writeTimeout:
                            default: 3s
                            description: |-
                              WriteTimeout is the timeout for socket writes.
                              Format: Go duration string (e.g., "3s", "1m").
                            pattern: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
                            type: string
                        required:
                        - aclUserConfig
                        type: object
                        x-kubernetes-validations:
                        - message: exactly one of addr or sentinelConfig must be set
                          rule: (has(self.addr) && self.addr.size() > 0) != has(self.sentinelConfig)
                        - message: clusterMode requires addr to be set
                          rule: '!(has(self.clusterMode) && self.clusterMode) || (has(self.addr)
                            && self.addr.size() > 0)'
                      type:
                        default: memory
                        description: |-
                          Type specifies the storage backend type.
                          Valid values: "memory" (default), "redis".
                        enum:
                        - memory
                        - redis
                        type: string
                    type: object
                  tokenLifespans:
                    description: |-
                      TokenLifespans configures the duration that various tokens are valid.
                      If not specified, defaults are applied (access: 1h, refresh: 7d, authCode: 10m).
                    properties:
                      accessTokenLifespan:
                        description: |-
                          AccessTokenLifespan is the duration that access tokens are valid.
                          Format: Go duration string (e.g., "1h", "30m", "24h").
                          If empty, defaults to 1 hour.
                        pattern: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
                        type: string
                      authCodeLifespan:
                        description: |-
                          AuthCodeLifespan is the duration that authorization codes are valid.
                          Format: Go duration string (e.g., "10m", "5m").
                          If empty, defaults to 10 minutes.
                        pattern: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
                        type: string
                      refreshTokenLifespan:
                        description: |-
                          RefreshTokenLifespan is the duration that refresh tokens are valid.
                          Format: Go duration string (e.g., "168h", "7d" as "168h").
                          If empty, defaults to 7 days (168h).
                        pattern: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
                        type: string
                    type: object
                  upstreamProviders:
                    description: |-
                      UpstreamProviders configures connections to upstream Identity Providers.
                      The embedded auth server delegates authentication to these providers.
                      MCPServer and MCPRemoteProxy support a single upstream; VirtualMCPServer supports multiple.
                    items:
                      description: |-
                        UpstreamProviderConfig defines configuration for an upstream Identity Provider.

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

                        The rule is structured as a chain of equality checks ending in an explicit
                        `false`, so adding a new UpstreamProviderType value without extending this
                        rule fails admission instead of silently demanding the OAuth2 shape. When
                        adding a new type, extend both this rule and validateUpstreamProvider.
                      properties:
                        name:
                          description: |-
                            Name uniquely identifies this upstream provider.
                            Used for routing decisions and session binding in multi-upstream scenarios.
                            Must be lowercase alphanumeric with hyphens (DNS-label-like).
                          maxLength: 63
                          minLength: 1
                          pattern: ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$
                          type: string
                        oauth2Config:
                          description: |-
                            OAuth2Config contains OAuth 2.0-specific configuration.
                            Required when Type is "oauth2", must be nil when Type is "oidc".
                          properties:
                            additionalAuthorizationParams:
                              additionalProperties:
                                type: string
                              description: |-
                                AdditionalAuthorizationParams are extra query parameters to include in
                                authorization requests sent to the upstream provider.
                                This is useful for providers that require custom parameters, such as
                                Google's access_type=offline for obtaining refresh tokens.
                                Framework-managed parameters (response_type, client_id, redirect_uri,
                                scope, state, code_challenge, code_challenge_method, nonce) are not allowed.
                              maxProperties: 16
                              type: object
                            authorizationEndpoint:
                              description: AuthorizationEndpoint is the URL for the
                                OAuth authorization endpoint.
                              pattern: ^https?://.*$
                              type: string
                            clientId:
                              description: |-
                                ClientID is the OAuth 2.0 client identifier registered with the upstream IDP.
                                Mutually exclusive with DCRConfig: when DCRConfig is set, ClientID is obtained
                                at runtime via RFC 7591 Dynamic Client Registration and must be left empty.
                              type: string
                            clientSecretRef:
                              description: |-
                                ClientSecretRef references a Kubernetes Secret containing the OAuth 2.0 client secret.
                                Optional for public clients using PKCE instead of client secret.
                              properties:
                                key:
                                  description: Key is the key within the secret
                                  type: string
                                name:
                                  description: Name is the name of the secret
                                  type: string
                              required:
                              - key
                              - name
                              type: object
                            dcrConfig:
                              description: |-
                                DCRConfig enables RFC 7591 Dynamic Client Registration against the upstream
                                authorization server. When set, the client credentials are obtained at
                                runtime rather than being pre-provisioned, and ClientID must be left empty.
                                Mutually exclusive with ClientID.
                              properties:
                                discoveryUrl:
                                  description: |-
                                    DiscoveryURL is the RFC 8414 / OIDC Discovery document URL. The resolver
                                    issues a single GET against this URL (no well-known-path fallback) and
                                    reads registration_endpoint, authorization_endpoint, token_endpoint,
                                    token_endpoint_auth_methods_supported, and scopes_supported from the
                                    response.
                                    Mutually exclusive with RegistrationEndpoint.
                                    HTTPS is required because the registration endpoint resolved from this
                                    document carries the initial access token and the issued client_secret
                                    (RFC 7591 §3, RFC 8414 §3). MaxLength is a defensive size cap (etcd
                                    object budget, regex evaluation cost) and matches the conventional URL
                                    length cap.
                                  maxLength: 2048
                                  pattern: ^https://[^\s?#]+[^/\s?#]$
                                  type: string
                                initialAccessTokenRef:
                                  description: |-
                                    InitialAccessTokenRef is an optional reference to a Kubernetes Secret
                                    carrying an RFC 7591 §3 initial access token. When set, the resolver
                                    presents the token value as a Bearer credential on the registration
                                    request. Mirrors the ClientSecretRef pattern.
                                  properties:
                                    key:
                                      description: Key is the key within the secret
                                      type: string
                                    name:
                                      description: Name is the name of the secret
                                      type: string
                                  required:
                                  - key
                                  - name
                                  type: object
                                registrationEndpoint:
                                  description: |-
                                    RegistrationEndpoint is the RFC 7591 registration endpoint URL used
                                    directly, bypassing discovery. When using this field, the caller is
                                    expected to also supply AuthorizationEndpoint, TokenEndpoint, and an
                                    explicit Scopes list on the parent OAuth2UpstreamConfig.
                                    Mutually exclusive with DiscoveryURL.
                                    HTTPS is required because the registration endpoint carries the initial
                                    access token and the issued client_secret (RFC 7591 §3, RFC 8414 §3).
                                    MaxLength is a defensive size cap (etcd object budget, regex evaluation
                                    cost) and matches the conventional URL length cap.
                                  maxLength: 2048
                                  pattern: ^https://[^\s?#]+[^/\s?#]$
                                  type: string
                                softwareId:
                                  description: |-
                                    SoftwareID is the RFC 7591 "software_id" registration metadata value,
                                    identifying the client software independent of any particular
                                    registration instance. Typically a UUID or short identifier.
                                  maxLength: 255
                                  type: string
                                softwareStatement:
                                  description: |-
                                    SoftwareStatement is the RFC 7591 "software_statement" JWT asserting
                                    metadata about the client software, signed by a party the authorization
                                    server trusts.

                                    Stored inline on the CR. The JWT is signed but not encrypted, so its
                                    contents are visible to anyone with get/list/watch on this resource and
                                    appear in etcd backups in plaintext. Treat the value as non-confidential
                                    (signed attestation, not a secret). Operators that rotate software
                                    statements like bearer credentials should keep them at the authorization
                                    server side and rely on the registration endpoint's initial access
                                    token (see InitialAccessTokenRef) instead of placing them on the CR.

                                    Bounded to 16384 characters as a defensive size cap (etcd object
                                    budget, regex evaluation cost). Real-world signed statements with
                                    embedded x5c certificate chains, JWKS keys, or OIDC-Federation
                                    trust-framework metadata routinely exceed 4 KB.
                                  maxLength: 16384
                                  type: string
                              type: object
                              x-kubernetes-validations:
                              - message: exactly one of discoveryUrl or registrationEndpoint
                                  must be set
                                rule: has(self.discoveryUrl) != has(self.registrationEndpoint)
                            identityFromToken:
                              description: |-
                                IdentityFromToken extracts user identity (subject, name, email) directly
                                from the OAuth2 token-endpoint response body using gjson dot-notation paths.
                                When set, the embedded auth server skips the userinfo HTTP call entirely
                                and resolves identity from the token response. See IdentityFromTokenConfig
                                for trust-model and uniqueness considerations.
                              properties:
                                emailPath:
                                  description: |-
                                    EmailPath is the dot-notation path to the email address field in the token response.
                                    If not specified or if the path does not resolve to a string, the email is omitted.
                                    Omit the field entirely rather than setting it to an empty string.
                                  maxLength: 256
                                  minLength: 1
                                  type: string
                                namePath:
                                  description: |-
                                    NamePath is the dot-notation path to the display name field in the token response.
                                    If not specified or if the path does not resolve to a string, the display name is omitted.
                                    Omit the field entirely rather than setting it to an empty string.
                                  maxLength: 256
                                  minLength: 1
                                  type: string
                                subjectPath:
                                  description: |-
                                    SubjectPath is the dot-notation path to the subject (user ID) field in the token response.
                                    Warning: claims read from the token response are trusted only via TLS, not
                                    cryptographically verified; prefer OIDC ID tokens when verifiable claims are required.
                                    Example: "authed_user.id" for Slack (top-level token-response field). For providers
                                    whose token response embeds the access token as a JWT (e.g. Snowflake), use the
                                    "@upstreamjwt" modifier to decode the payload, e.g. "access_token|@upstreamjwt|sub".
                                    The "@upstreamjwt" modifier performs no signature verification either.
                                  maxLength: 256
                                  minLength: 1
                                  type: string
                              required:
                              - subjectPath
                              type: object
                            redirectUri:
                              description: |-
                                RedirectURI is the callback URL where the upstream IDP will redirect after authentication.
                                When not specified, defaults to `{resourceUrl}/oauth/callback` where `resourceUrl` is the
                                URL associated with the resource (e.g., MCPServer or vMCP) using this config.
                              type: string
                            scopes:
                              description: Scopes are the OAuth scopes to request
                                from the upstream IDP.
                              items:
                                type: string
                              type: array
                              x-kubernetes-list-type: atomic
                            tokenEndpoint:
                              description: TokenEndpoint is the URL for the OAuth
                                token endpoint.
                              pattern: ^https?://.*$
                              type: string
                            tokenResponseMapping:
                              description: |-
                                TokenResponseMapping configures custom field extraction from non-standard token responses.
                                Some OAuth providers (e.g., GovSlack) nest token fields under non-standard paths
                                instead of returning them at the top level. When set, ToolHive performs the token
                                exchange HTTP call directly and extracts fields using the configured dot-notation paths.
                                If nil, standard OAuth 2.0 token response parsing is used.
                                For extracting user identity from the token response, see IdentityFromToken.
                              properties:
                                accessTokenPath:
                                  description: |-
                                    AccessTokenPath is the dot-notation path to the access token in the response.
                                    Example: "authed_user.access_token"
                                  minLength: 1
                                  type: string
                                expiresInPath:
                                  description: |-
                                    ExpiresInPath is the dot-notation path to the expires_in value (in seconds).
                                    If not specified, defaults to "expires_in".
                                  type: string
                                refreshTokenPath:
                                  description: |-
                                    RefreshTokenPath is the dot-notation path to the refresh token in the response.
                                    If not specified, defaults to "refresh_token".
                                  type: string
                                scopePath:
                                  description: |-
                                    ScopePath is the dot-notation path to the scope string in the response.
                                    If not specified, defaults to "scope".
                                  type: string
                              required:
                              - accessTokenPath
                              type: object
                            userInfo:
                              description: |-
                                UserInfo contains configuration for fetching user information from the upstream provider.
                                When omitted and IdentityFromToken is also unset, the embedded auth server runs in
                                synthesis mode for this upstream: a non-PII subject derived from the access token, no
                                Name/Email. Use this shape for upstreams with no userinfo surface and no identity in
                                the token response (e.g., MCP authorization servers per the MCP spec). When
                                IdentityFromToken is set instead, identity is resolved from the token response body
                                (e.g., Snowflake's "username" field, Slack's "authed_user.id"); the userinfo HTTP call
                                is skipped entirely.
                              properties:
                                additionalHeaders:
                                  additionalProperties:
                                    type: string
                                  description: |-
                                    AdditionalHeaders contains extra headers to include in the userinfo request.
                                    Useful for providers that require specific headers (e.g., GitHub's Accept header).
                                  type: object
                                endpointUrl:
                                  description: EndpointURL is the URL of the userinfo
                                    endpoint.
                                  pattern: ^https?://.*$
                                  type: string
                                fieldMapping:
                                  description: |-
                                    FieldMapping contains custom field mapping configuration for non-standard providers.
                                    If nil, standard OIDC field names are used ("sub", "name", "email").
                                  properties:
                                    emailFields:
                                      description: |-
                                        EmailFields is an ordered list of field names to try for the email address.
                                        The first non-empty value found will be used.
                                        Default: ["email"]
                                      items:
                                        type: string
                                      type: array
                                      x-kubernetes-list-type: atomic
                                    nameFields:
                                      description: |-
                                        NameFields is an ordered list of field names to try for the display name.
                                        The first non-empty value found will be used.
                                        Default: ["name"]
                                      items:
                                        type: string
                                      type: array
                                      x-kubernetes-list-type: atomic
                                    subjectFields:
                                      description: |-
                                        SubjectFields is an ordered list of field names to try for the user ID.
                                        The first non-empty value found will be used.
                                        Default: ["sub"]
                                      items:
                                        type: string
                                      type: array
                                      x-kubernetes-list-type: atomic
                                  type: object
                                httpMethod:
                                  description: |-
                                    HTTPMethod is the HTTP method to use for the userinfo request.
                                    If not specified, defaults to GET.
                                  enum:
                                  - GET
                                  - POST
                                  type: string
                              required:
                              - endpointUrl
                              type: object
                          required:
                          - authorizationEndpoint
                          - tokenEndpoint
                          type: object
                          x-kubernetes-validations:
                          - message: exactly one of clientId or dcrConfig must be
                              set
                            rule: '(has(self.clientId) && size(self.clientId) > 0)
                              ? !has(self.dcrConfig) : has(self.dcrConfig)'
                          - message: clientSecretRef must not be set when dcrConfig
                              is set; the client_secret is obtained at runtime via
                              Dynamic Client Registration
                            rule: '!(has(self.dcrConfig) && has(self.clientSecretRef))'
                        oidcConfig:
                          description: |-
                            OIDCConfig contains OIDC-specific configuration.
                            Required when Type is "oidc", must be nil when Type is "oauth2".
                          properties:
                            additionalAuthorizationParams:
                              additionalProperties:
                                type: string
                              description: |-
                                AdditionalAuthorizationParams are extra query parameters to include in
                                authorization requests sent to the upstream provider.
                                This is useful for providers that require custom parameters, such as
                                Google's access_type=offline for obtaining refresh tokens.
                                Note: when using access_type=offline, also set explicit scopes to avoid
                                the default offline_access scope being sent alongside it.
                                Framework-managed parameters (response_type, client_id, redirect_uri,
                                scope, state, code_challenge, code_challenge_method, nonce) are not allowed.
                              maxProperties: 16
                              type: object
                            clientId:
                              description: ClientID is the OAuth 2.0 client identifier
                                registered with the upstream IDP.
                              type: string
                            clientSecretRef:
                              description: |-
                                ClientSecretRef references a Kubernetes Secret containing the OAuth 2.0 client secret.
                                Optional for public clients using PKCE instead of client secret.
                              properties:
                                key:
                                  description: Key is the key within the secret
                                  type: string
                                name:
                                  description: Name is the name of the secret
                                  type: string
                              required:
                              - key
                              - name
                              type: object
                            issuerUrl:
                              description: |-
                                IssuerURL is the OIDC issuer URL for automatic endpoint discovery.
                                Must be a valid HTTPS URL.
                              pattern: ^https://.*$
                              type: string
                            redirectUri:
                              description: |-
                                RedirectURI is the callback URL where the upstream IDP will redirect after authentication.
                                When not specified, defaults to `{resourceUrl}/oauth/callback` where `resourceUrl` is the
                                URL associated with the resource (e.g., MCPServer or vMCP) using this config.
                              type: string
                            scopes:
                              description: |-
                                Scopes are the OAuth scopes to request from the upstream IDP.
                                If not specified, defaults to ["openid", "offline_access"].
                                When using additionalAuthorizationParams with provider-specific refresh token
                                mechanisms (e.g., Google's access_type=offline), set explicit scopes to avoid
                                sending both offline_access and the provider-specific parameter.
                              items:
                                type: string
                              type: array
                              x-kubernetes-list-type: atomic
                            userInfoOverride:
                              description: |-
                                UserInfoOverride allows customizing UserInfo fetching behavior for OIDC providers.
                                By default, the UserInfo endpoint is discovered automatically via OIDC discovery.
                                Use this to override the endpoint URL, HTTP method, or field mappings for providers
                                that return non-standard claim names in their UserInfo response.
                              properties:
                                additionalHeaders:
                                  additionalProperties:
                                    type: string
                                  description: |-
                                    AdditionalHeaders contains extra headers to include in the userinfo request.
                                    Useful for providers that require specific headers (e.g., GitHub's Accept header).
                                  type: object
                                endpointUrl:
                                  description: EndpointURL is the URL of the userinfo
                                    endpoint.
                                  pattern: ^https?://.*$
                                  type: string
                                fieldMapping:
                                  description: |-
                                    FieldMapping contains custom field mapping configuration for non-standard providers.
                                    If nil, standard OIDC field names are used ("sub", "name", "email").
                                  properties:
                                    emailFields:
                                      description: |-
                                        EmailFields is an ordered list of field names to try for the email address.
                                        The first non-empty value found will be used.
                                        Default: ["email"]
                                      items:
                                        type: string
                                      type: array
                                      x-kubernetes-list-type: atomic
                                    nameFields:
                                      description: |-
                                        NameFields is an ordered list of field names to try for the display name.
                                        The first non-empty value found will be used.
                                        Default: ["name"]
                                      items:
                                        type: string
                                      type: array
                                      x-kubernetes-list-type: atomic
                                    subjectFields:
                                      description: |-
                                        SubjectFields is an ordered list of field names to try for the user ID.
                                        The first non-empty value found will be used.
                                        Default: ["sub"]
                                      items:
                                        type: string
                                      type: array
                                      x-kubernetes-list-type: atomic
                                  type: object
                                httpMethod:
                                  description: |-
                                    HTTPMethod is the HTTP method to use for the userinfo request.
                                    If not specified, defaults to GET.
                                  enum:
                                  - GET
                                  - POST
                                  type: string
                              required:
                              - endpointUrl
                              type: object
                          required:
                          - clientId
                          - issuerUrl
                          type: object
                        type:
                          description: 'Type specifies the provider type: "oidc" or
                            "oauth2"'
                          enum:
                          - oidc
                          - oauth2
                          type: string
                      required:
                      - name
                      - type
                      type: object
                      x-kubernetes-validations:
                      - message: type must be 'oidc' or 'oauth2'; oidcConfig must
                          be set when type is 'oidc' and oauth2Config must be set
                          when type is 'oauth2' (and the other must not be set)
                        rule: 'self.type == ''oidc'' ? (has(self.oidcConfig) && !has(self.oauth2Config))
                          : self.type == ''oauth2'' ? (has(self.oauth2Config) && !has(self.oidcConfig))
                          : false'
                    minItems: 1
                    type: array
                    x-kubernetes-list-map-keys:
                    - name
                    x-kubernetes-list-type: map
                required:
                - issuer
                - upstreamProviders
                type: object
              config:
                description: |-
                  Config is the Virtual MCP server configuration.
                  The audit config from here is also supported, but not required.
                properties:
                  aggregation:
                    description: |-
                      Aggregation defines tool aggregation and conflict resolution strategies.
                      Supports ToolConfigRef for Kubernetes-native MCPToolConfig resource references.
                    properties:
                      conflictResolution:
                        default: prefix
                        description: |-
                          ConflictResolution defines the strategy for resolving tool name conflicts.
                          - prefix: Automatically prefix tool names with workload identifier
                          - priority: First workload in priority order wins
                          - manual: Explicitly define overrides for all conflicts
                        enum:
                        - prefix
                        - priority
                        - manual
                        type: string
                      conflictResolutionConfig:
                        description: ConflictResolutionConfig provides configuration
                          for the chosen strategy.
                        properties:
                          prefixFormat:
                            default: '{workload}_'
                            description: |-
                              PrefixFormat defines the prefix format for the "prefix" strategy.
                              Supports placeholders: {workload}, {workload}_, {workload}.
                            type: string
                          priorityOrder:
                            description: PriorityOrder defines the workload priority
                              order for the "priority" strategy.
                            items:
                              type: string
                            type: array
                        type: object
                      excludeAllTools:
                        description: |-
                          ExcludeAllTools hides all backend tools from MCP clients when true.
                          Hidden tools are NOT advertised in tools/list responses, but they ARE
                          available in the routing table for composite tools to use.
                          This enables the use case where you want to hide raw backend tools from
                          direct client access while exposing curated composite tool workflows.
                        type: boolean
                      tools:
                        description: Tools defines per-workload tool filtering and
                          overrides.
                        items:
                          description: WorkloadToolConfig defines tool filtering and
                            overrides for a specific workload.
                          properties:
                            excludeAll:
                              description: |-
                                ExcludeAll hides all tools from this workload from MCP clients when true.
                                Hidden tools are NOT advertised in tools/list responses, but they ARE
                                available in the routing table for composite tools to use.
                                This enables the use case where you want to hide raw backend tools from
                                direct client access while exposing curated composite tool workflows.
                              type: boolean
                            filter:
                              description: |-
                                Filter is an allow-list of tool names to advertise to MCP clients.
                                Tools NOT in this list are hidden from clients (not in tools/list response)
                                but remain available in the routing table for composite tools to use.
                                This enables selective exposure of backend tools while allowing composite
                                workflows to orchestrate all backend capabilities.
                                Only used if ToolConfigRef is not specified.
                              items:
                                type: string
                              type: array
                            overrides:
                              additionalProperties:
                                description: ToolOverride defines tool name, description,
                                  and annotation overrides.
                                properties:
                                  annotations:
                                    description: |-
                                      Annotations overrides specific tool annotation fields.
                                      Only specified fields are overridden; others pass through from the backend.
                                    properties:
                                      destructiveHint:
                                        description: DestructiveHint overrides the
                                          destructive hint annotation.
                                        type: boolean
                                      idempotentHint:
                                        description: IdempotentHint overrides the
                                          idempotent hint annotation.
                                        type: boolean
                                      openWorldHint:
                                        description: OpenWorldHint overrides the open-world
                                          hint annotation.
                                        type: boolean
                                      readOnlyHint:
                                        description: ReadOnlyHint overrides the read-only
                                          hint annotation.
                                        type: boolean
                                      title:
                                        description: Title overrides the human-readable
                                          title annotation.
                                        type: string
                                    type: object
                                  description:
                                    description: Description is the new tool description.
                                    type: string
                                  name:
                                    description: Name is the new tool name (for renaming).
                                    type: string
                                type: object
                              description: |-
                                Overrides is an inline map of tool overrides for renaming and description changes.
                                Overrides are applied to tools before conflict resolution and affect both
                                advertising and routing (the overridden name is used everywhere).
                                Only used if ToolConfigRef is not specified.
                              type: object
                            toolConfigRef:
                              description: |-
                                ToolConfigRef references an MCPToolConfig resource for tool filtering and renaming.
                                If specified, Filter and Overrides are ignored.
                                Only used when running in Kubernetes with the operator.
                              properties:
                                name:
                                  description: Name is the name of the MCPToolConfig
                                    resource in the same namespace.
                                  type: string
                              required:
                              - name
                              type: object
                            workload:
                              description: Workload is the name of the backend MCPServer
                                workload.
                              type: string
                          required:
                          - workload
                          type: object
                        type: array
                    type: object
                  audit:
                    description: |-
                      Audit configures audit logging for the Virtual MCP server.
                      When present, audit logs include MCP protocol operations.
                      See audit.Config for available configuration options.
                    properties:
                      component:
                        description: Component is the component name to use in audit
                          events.
                        type: string
                      detectApplicationErrors:
                        default: true
                        description: |-
                          DetectApplicationErrors controls whether the audit middleware inspects
                          JSON-RPC response bodies for application-level errors when the HTTP
                          status code indicates success (2xx). When enabled, a small prefix of
                          the response body is buffered to detect JSON-RPC error fields,
                          independent of the IncludeResponseData setting.
                        type: boolean
                      enabled:
                        default: false
                        description: |-
                          Enabled controls whether audit logging is enabled.
                          When true, enables audit logging with the configured options.
                        type: boolean
                      eventTypes:
                        description: EventTypes specifies which event types to audit.
                          If empty, all events are audited.
                        items:
                          type: string
                        type: array
                      excludeEventTypes:
                        description: |-
                          ExcludeEventTypes specifies which event types to exclude from auditing.
                          This takes precedence over EventTypes.
                        items:
                          type: string
                        type: array
                      includeRequestData:
                        default: false
                        description: IncludeRequestData determines whether to include
                          request data in audit logs.
                        type: boolean
                      includeResponseData:
                        default: false
                        description: IncludeResponseData determines whether to include
                          response data in audit logs.
                        type: boolean
                      logFile:
                        description: LogFile specifies the file path for audit logs.
                          If empty, logs to stdout.
                        type: string
                      maxDataSize:
                        default: 1024
                        description: MaxDataSize limits the size of request/response
                          data included in audit logs (in bytes).
                        type: integer
                    type: object
                  backends:
                    description: |-
                      Backends defines pre-configured backend servers for static mode.
                      When OutgoingAuth.Source is "inline", this field contains the full list of backend
                      servers with their URLs and transport types, eliminating the need for K8s API access.
                      When OutgoingAuth.Source is "discovered", this field is empty and backends are
                      discovered at runtime via Kubernetes API.
                    items:
                      description: |-
                        StaticBackendConfig defines a pre-configured backend server for static mode.
                        This allows vMCP to operate without Kubernetes API access by embedding all backend
                        information directly in the configuration.
                      properties:
                        caBundlePath:
                          description: |-
                            CABundlePath is the file path to a custom CA certificate bundle for TLS verification.
                            Only valid when Type is "entry". The operator mounts CA bundles at
                            /etc/toolhive/ca-bundles/<name>/ca.crt.
                          type: string
                        metadata:
                          additionalProperties:
                            type: string
                          description: |-
                            Metadata is a custom key-value map for storing additional backend information
                            such as labels, tags, or other arbitrary data (e.g., "env": "prod", "region": "us-east-1").
                            This is NOT Kubernetes ObjectMeta - it's a simple string map for user-defined metadata.
                            Reserved keys: "group" is automatically set by vMCP and any user-provided value will be overridden.
                          type: object
                        name:
                          description: |-
                            Name is the backend identifier.
                            Must match the backend name from the MCPGroup for auth config resolution.
                          type: string
                        transport:
                          description: |-
                            Transport is the MCP transport protocol: "sse" or "streamable-http"
                            Only network transports supported by vMCP client are allowed.
                          enum:
                          - sse
                          - streamable-http
                          type: string
                        type:
                          description: |-
                            Type is the backend workload type: "entry" for MCPServerEntry backends, or empty
                            for container/proxy backends. Entry backends connect directly to remote MCP servers.
                          enum:
                          - entry
                          - ""
                          type: string
                        url:
                          description: URL is the backend's MCP server base URL.
                          pattern: ^https?://
                          type: string
                      required:
                      - name
                      - transport
                      - url
                      type: object
                    type: array
                  compositeToolRefs:
                    description: |-
                      CompositeToolRefs references VirtualMCPCompositeToolDefinition resources
                      for complex, reusable workflows. Only applicable when running in Kubernetes.
                      Referenced resources must be in the same namespace as the VirtualMCPServer.
                    items:
                      description: |-
                        CompositeToolRef defines a reference to a VirtualMCPCompositeToolDefinition resource.
                        The referenced resource must be in the same namespace as the VirtualMCPServer.
                      properties:
                        name:
                          description: Name is the name of the VirtualMCPCompositeToolDefinition
                            resource in the same namespace.
                          type: string
                      required:
                      - name
                      type: object
                    type: array
                  compositeTools:
                    description: |-
                      CompositeTools defines inline composite tool workflows.
                      Full workflow definitions are embedded in the configuration.
                      For Kubernetes, complex workflows can also reference VirtualMCPCompositeToolDefinition CRDs.
                    items:
                      description: |-
                        CompositeToolConfig defines a composite tool workflow.
                        This matches the YAML structure from the proposal (lines 173-255).
                      properties:
                        description:
                          description: Description describes what the workflow does.
                          type: string
                        name:
                          description: Name is the workflow name (unique identifier).
                          type: string
                        output:
                          description: |-
                            Output defines the structured output schema for this workflow.
                            If not specified, the workflow returns the last step's output (backward compatible).
                          properties:
                            properties:
                              additionalProperties:
                                description: |-
                                  OutputProperty defines a single output property.
                                  For non-object types, Value is required.
                                  For object types, either Value or Properties must be specified (but not both).
                                properties:
                                  default:
                                    description: |-
                                      Default is the fallback value if template expansion fails.
                                      Type coercion is applied to match the declared Type.
                                    x-kubernetes-preserve-unknown-fields: true
                                  description:
                                    description: Description is a human-readable description
                                      exposed to clients and models
                                    type: string
                                  properties:
                                    description: |-
                                      Properties defines nested properties for object types.
                                      Each nested property has full metadata (type, description, value/properties).
                                    type: object
                                    x-kubernetes-preserve-unknown-fields: true
                                  type:
                                    description: 'Type is the JSON Schema type: "string",
                                      "integer", "number", "boolean", "object", "array"'
                                    enum:
                                    - string
                                    - integer
                                    - number
                                    - boolean
                                    - object
                                    - array
                                    type: string
                                  value:
                                    description: |-
                                      Value is a template string for constructing the runtime value.
                                      For object types, this can be a JSON string that will be deserialized.
                                      Supports template syntax: {{ "{{" }}.steps.step_id.output.field{{ "}}" }}, {{ "{{" }}.params.param_name{{ "}}" }}
                                    type: string
                                required:
                                - type
                                type: object
                              description: |-
                                Properties defines the output properties.
                                Map key is the property name, value is the property definition.
                              type: object
                            required:
                              description: Required lists property names that must
                                be present in the output.
                              items:
                                type: string
                              type: array
                          required:
                          - properties
                          type: object
                        parameters:
                          description: |-
                            Parameters defines input parameter schema in JSON Schema format.
                            Should be a JSON Schema object with "type": "object" and "properties".
                            Example:
                              {
                                "type": "object",
                                "properties": {
                                  "param1": {"type": "string", "default": "value"},
                                  "param2": {"type": "integer"}
                                },
                                "required": ["param2"]
                              }

                            We use json.Map rather than a typed struct because JSON Schema is highly
                            flexible with many optional fields (default, enum, minimum, maximum, pattern,
                            items, additionalProperties, oneOf, anyOf, allOf, etc.). Using json.Map
                            allows full JSON Schema compatibility without needing to define every possible
                            field, and matches how the MCP SDK handles inputSchema.
                          type: object
                          x-kubernetes-preserve-unknown-fields: true
                        steps:
                          description: Steps are the workflow steps to execute.
                          items:
                            description: |-
                              WorkflowStepConfig defines a single workflow step.
                              This matches the proposal's step configuration (lines 180-255).
                            properties:
                              arguments:
                                description: |-
                                  Arguments is a map of argument values with template expansion support.
                                  Supports Go template syntax with .params and .steps for string values.
                                  Non-string values (integers, booleans, arrays, objects) are passed as-is.
                                  Note: the templating is only supported on the first level of the key-value pairs.
                                type: object
                                x-kubernetes-preserve-unknown-fields: true
                              collection:
                                description: |-
                                  Collection is a Go template expression that resolves to a JSON array or a slice.
                                  Only used when Type is "forEach".
                                type: string
                              condition:
                                description: Condition is a template expression that
                                  determines if the step should execute
                                type: string
                              defaultResults:
                                description: |-
                                  DefaultResults provides fallback output values when this step is skipped
                                  (due to condition evaluating to false) or fails (when onError.action is "continue").
                                  Each key corresponds to an output field name referenced by downstream steps.
                                  Required if the step may be skipped AND downstream steps reference this step's output.
                                x-kubernetes-preserve-unknown-fields: true
                              dependsOn:
                                description: DependsOn lists step IDs that must complete
                                  before this step
                                items:
                                  type: string
                                type: array
                              id:
                                description: ID is the unique identifier for this
                                  step.
                                type: string
                              itemVar:
                                description: |-
                                  ItemVar is the variable name used to reference the current item in forEach templates.
                                  Defaults to "item" if not specified.
                                  Only used when Type is "forEach".
                                type: string
                              maxIterations:
                                description: |-
                                  MaxIterations limits the number of items that can be iterated over.
                                  Defaults to 100, hard cap at 1000.
                                  Only used when Type is "forEach".
                                type: integer
                              maxParallel:
                                description: |-
                                  MaxParallel limits the number of concurrent iterations in a forEach step.
                                  Defaults to the DAG executor's maxParallel (10).
                                  Only used when Type is "forEach".
                                type: integer
                              message:
                                description: |-
                                  Message is the elicitation message
                                  Only used when Type is "elicitation"
                                type: string
                              onCancel:
                                description: |-
                                  OnCancel defines the action to take when the user cancels/dismisses the elicitation
                                  Only used when Type is "elicitation"
                                properties:
                                  action:
                                    default: abort
                                    description: |-
                                      Action defines the action to take when the user declines or cancels
                                      - skip_remaining: Skip remaining steps in the workflow
                                      - abort: Abort the entire workflow execution
                                      - continue: Continue to the next step
                                    enum:
                                    - skip_remaining
                                    - abort
                                    - continue
                                    type: string
                                type: object
                              onDecline:
                                description: |-
                                  OnDecline defines the action to take when the user explicitly declines the elicitation
                                  Only used when Type is "elicitation"
                                properties:
                                  action:
                                    default: abort
                                    description: |-
                                      Action defines the action to take when the user declines or cancels
                                      - skip_remaining: Skip remaining steps in the workflow
                                      - abort: Abort the entire workflow execution
                                      - continue: Continue to the next step
                                    enum:
                                    - skip_remaining
                                    - abort
                                    - continue
                                    type: string
                                type: object
                              onError:
                                description: OnError defines error handling behavior
                                properties:
                                  action:
                                    default: abort
                                    description: Action defines the action to take
                                      on error
                                    enum:
                                    - abort
                                    - continue
                                    - retry
                                    type: string
                                  retryCount:
                                    description: |-
                                      RetryCount is the maximum number of retries
                                      Only used when Action is "retry"
                                    type: integer
                                  retryDelay:
                                    description: |-
                                      RetryDelay is the delay between retry attempts
                                      Only used when Action is "retry"
                                    pattern: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
                                    type: string
                                type: object
                              schema:
                                description: Schema defines the expected response
                                  schema for elicitation
                                type: object
                                x-kubernetes-preserve-unknown-fields: true
                              step:
                                description: |-
                                  InnerStep defines the step to execute for each item in the collection.
                                  Only used when Type is "forEach". Only tool-type inner steps are supported.
                                type: object
                                x-kubernetes-preserve-unknown-fields: true
                              timeout:
                                description: Timeout is the maximum execution time
                                  for this step
                                pattern: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
                                type: string
                              tool:
                                description: |-
                                  Tool is the tool to call (format: "workload.tool_name")
                                  Only used when Type is "tool"
                                type: string
                              type:
                                default: tool
                                description: Type is the step type (tool, elicitation,
                                  etc.)
                                enum:
                                - tool
                                - elicitation
                                - forEach
                                type: string
                            required:
                            - id
                            type: object
                          type: array
                        timeout:
                          description: Timeout is the maximum workflow execution time.
                          pattern: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
                          type: string
                      required:
                      - name
                      - steps
                      type: object
                    type: array
                  groupRef:
                    description: |-
                      Group references an existing MCPGroup that defines backend workloads.
                      In standalone CLI mode, this is set from the YAML config file.
                      In Kubernetes, the operator populates this from spec.groupRef during conversion.
                    type: string
                  incomingAuth:
                    description: |-
                      IncomingAuth configures how clients authenticate to the virtual MCP server.
                      When using the Kubernetes operator, this is populated by the converter from
                      VirtualMCPServerSpec.IncomingAuth and any values set here will be superseded.
                    properties:
                      authz:
                        description: Authz contains authorization configuration (optional).
                        properties:
                          entitiesJson:
                            description: |-
                              EntitiesJSON is a JSON string representing Cedar entities. Required for
                              enterprise policies that rely on transitive relationships (e.g.
                              `ClaimGroup → PlatformRole`) — without it the Cedar authorizer is
                              constructed with an empty entity store and `in` checks against absent
                              entities silently evaluate to false. Defaults to "[]" when empty.
                            type: string
                          groupClaimName:
                            description: |-
                              GroupClaimName is the JWT claim key that contains group membership for
                              the principal. When set, takes priority over the well-known defaults
                              ("groups", "roles", "cognito:groups"). Use this for IDPs that place
                              groups under a URI-style claim (e.g. "https://example.com/groups").
                              When empty, only the well-known claim names are checked.
                            type: string
                          groupEntityType:
                            description: |-
                              GroupEntityType is the Cedar entity type name used for principal parent
                              UIDs synthesised from JWT group/role claims. Defaults to "THVGroup" when
                              empty. Must match the entity type used in EntitiesJSON for transitive
                              `in` checks to resolve. Namespaced names (`Foo::Bar`) are not yet supported.
                            type: string
                          policies:
                            description: Policies contains Cedar policy definitions
                              (when Type = "cedar").
                            items:
                              type: string
                            type: array
                          primaryUpstreamProvider:
                            description: |-
                              PrimaryUpstreamProvider names the upstream IDP provider whose access
                              token should be used as the source of JWT claims for Cedar evaluation.
                              When empty, claims from the ToolHive-issued token are used.
                              Must match an upstream provider name configured in the embedded auth server
                              (e.g. "default", "github"). Only relevant when the embedded auth server is active.
                            type: string
                          roleClaimName:
                            description: |-
                              RoleClaimName is the JWT claim key that contains role membership for the
                              principal. When set, the claim is extracted separately from GroupClaimName
                              and both are mapped to the configured group entity type. When empty, no
                              role extraction is performed.
                            type: string
                          type:
                            description: 'Type is the authz type: "cedar", "none"'
                            type: string
                        required:
                        - type
                        type: object
                      oidc:
                        description: OIDC contains OIDC configuration (when Type =
                          "oidc").
                        properties:
                          audience:
                            description: Audience is the required token audience.
                            type: string
                          clientId:
                            description: ClientID is the OAuth client ID.
                            type: string
                          clientSecretEnv:
                            description: |-
                              ClientSecretEnv is the name of the environment variable containing the client secret.
                              This is the secure way to reference secrets - the actual secret value is never stored
                              in configuration files, only the environment variable name.
                              The secret value will be resolved from this environment variable at runtime.
                            type: string
                          insecureAllowHttp:
                            description: |-
                              InsecureAllowHTTP allows HTTP (non-HTTPS) OIDC issuers for development/testing
                              WARNING: This is insecure and should NEVER be used in production
                            type: boolean
                          introspectionUrl:
                            description: |-
                              IntrospectionURL is the token introspection endpoint URL (RFC 7662).
                              When set, enables token introspection for opaque (non-JWT) tokens.
                            type: string
                          issuer:
                            description: Issuer is the OIDC issuer URL.
                            pattern: ^https?://
                            type: string
                          jwksAllowPrivateIp:
                            description: |-
                              JwksAllowPrivateIP allows OIDC discovery and JWKS fetches to private IP addresses.
                              Enable when the embedded auth server runs on a loopback address and
                              the OIDC middleware needs to fetch its JWKS from that address.
                              Use with caution - only enable for trusted internal IDPs or testing.
                            type: boolean
                          jwksUrl:
                            description: |-
                              JWKSURL is the explicit JWKS endpoint URL.
                              When set, skips OIDC discovery and fetches the JWKS directly from this URL.
                              This is useful when the OIDC issuer does not serve a /.well-known/openid-configuration.
                            type: string
                          protectedResourceAllowPrivateIp:
                            description: |-
                              ProtectedResourceAllowPrivateIP allows protected resource endpoint on private IP addresses
                              Use with caution - only enable for trusted internal IDPs or testing
                            type: boolean
                          resource:
                            description: |-
                              Resource is the OAuth 2.0 resource indicator (RFC 8707).
                              Used in WWW-Authenticate header and OAuth discovery metadata (RFC 9728).
                              If not specified, defaults to Audience.
                            type: string
                          scopes:
                            description: Scopes are the required OAuth scopes.
                            items:
                              type: string
                            type: array
                        required:
                        - audience
                        - clientId
                        - issuer
                        type: object
                      type:
                        description: 'Type is the auth type: "oidc", "local", "anonymous"'
                        type: string
                    required:
                    - type
                    type: object
                  metadata:
                    additionalProperties:
                      type: string
                    description: Metadata stores additional configuration metadata.
                    type: object
                  name:
                    description: Name is the virtual MCP server name.
                    type: string
                  operational:
                    description: Operational configures operational settings.
                    properties:
                      failureHandling:
                        description: FailureHandling configures failure handling behavior.
                        properties:
                          circuitBreaker:
                            description: CircuitBreaker configures circuit breaker
                              behavior.
                            properties:
                              enabled:
                                default: false
                                description: Enabled controls whether circuit breaker
                                  is enabled.
                                type: boolean
                              failureThreshold:
                                default: 5
                                description: |-
                                  FailureThreshold is the number of failures before opening the circuit.
                                  Must be >= 1.
                                minimum: 1
                                type: integer
                              timeout:
                                default: 60s
                                description: |-
                                  Timeout is the duration to wait before attempting to close the circuit.
                                  Must be >= 1s to prevent thrashing.
                                pattern: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
                                type: string
                                x-kubernetes-validations:
                                - message: timeout must be >= 1s
                                  rule: self == '' || duration(self) >= duration('1s')
                            type: object
                          healthCheckInterval:
                            default: 30s
                            description: HealthCheckInterval is the interval between
                              health checks.
                            pattern: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
                            type: string
                          healthCheckTimeout:
                            default: 10s
                            description: |-
                              HealthCheckTimeout is the maximum duration for a single health check operation.
                              Should be less than HealthCheckInterval to prevent checks from queuing up.
                            pattern: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
                            type: string
                          partialFailureMode:
                            default: fail
                            description: |-
                              PartialFailureMode defines behavior when some backends are unavailable.
                              - fail: Fail entire request if any backend is unavailable
                              - best_effort: Continue with available backends
                            enum:
                            - fail
                            - best_effort
                            type: string
                          statusReportingInterval:
                            default: 30s
                            description: |-
                              StatusReportingInterval is the interval for reporting status updates to Kubernetes.
                              This controls how often the vMCP runtime reports backend health and phase changes.
                              Lower values provide faster status updates but increase API server load.
                            pattern: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
                            type: string
                          unhealthyThreshold:
                            default: 3
                            description: UnhealthyThreshold is the number of consecutive
                              failures before marking unhealthy.
                            type: integer
                        type: object
                      logLevel:
                        description: |-
                          LogLevel sets the logging level for the Virtual MCP server.
                          The only valid value is "debug" to enable debug logging.
                          When omitted or empty, the server uses info level logging.
                        enum:
                        - debug
                        type: string
                      timeouts:
                        description: Timeouts configures timeout settings.
                        properties:
                          default:
                            default: 30s
                            description: Default is the default timeout for backend
                              requests.
                            pattern: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
                            type: string
                          perWorkload:
                            additionalProperties:
                              pattern: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
                              type: string
                            description: PerWorkload defines per-workload timeout
                              overrides.
                            type: object
                        type: object
                    type: object
                  optimizer:
                    description: |-
                      Optimizer configures the MCP optimizer for context optimization on large toolsets.
                      When enabled, vMCP exposes only find_tool and call_tool operations to clients
                      instead of all backend tools directly. This reduces token usage by allowing
                      LLMs to discover relevant tools on demand rather than receiving all tool definitions.
                    properties:
                      embeddingService:
                        description: |-
                          EmbeddingService is the full base URL of the embedding service endpoint
                          (e.g., http://my-embedding.default.svc.cluster.local:8080) for semantic
                          tool discovery.

                          In a Kubernetes environment, it is more convenient to use the
                          VirtualMCPServerSpec.EmbeddingServerRef field instead of setting this
                          directly. EmbeddingServerRef references an EmbeddingServer CRD by name,
                          and the operator automatically resolves the referenced resource's
                          Status.URL to populate this field. This provides managed lifecycle
                          (the operator watches the EmbeddingServer for readiness and URL changes)
                          and avoids hardcoding service URLs in the config. If both
                          EmbeddingServerRef and this field are set, EmbeddingServerRef takes
                          precedence and this value is overridden with a warning.
                        type: string
                      embeddingServiceTimeout:
                        default: 30s
                        description: |-
                          EmbeddingServiceTimeout is the HTTP request timeout for calls to the embedding service.
                          Defaults to 30s if not specified.
                        pattern: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
                        type: string
                      hybridSearchSemanticRatio:
                        description: |-
                          HybridSearchSemanticRatio controls the balance between semantic (meaning-based)
                          and keyword search results. 0.0 = all keyword, 1.0 = all semantic.
                          Defaults to "0.5" if not specified or empty.
                          Serialized as a string because CRDs do not support float types portably.
                        pattern: ^([0-9]*[.])?[0-9]+$
                        type: string
                      maxToolsToReturn:
                        description: |-
                          MaxToolsToReturn is the maximum number of tool results returned by a search query.
                          Defaults to 8 if not specified or zero.
                        maximum: 50
                        minimum: 1
                        type: integer
                      semanticDistanceThreshold:
                        description: |-
                          SemanticDistanceThreshold is the maximum distance for semantic search results.
                          Results exceeding this threshold are filtered out from semantic search.
                          This threshold does not apply to keyword search.
                          Range: 0 = identical, 2 = completely unrelated.
                          Defaults to "1.0" if not specified or empty.
                          Serialized as a string because CRDs do not support float types portably.
                        pattern: ^([0-9]*[.])?[0-9]+$
                        type: string
                    type: object
                  outgoingAuth:
                    description: |-
                      OutgoingAuth configures how the virtual MCP server authenticates to backends.
                      When using the Kubernetes operator, this is populated by the converter from
                      VirtualMCPServerSpec.OutgoingAuth and any values set here will be superseded.
                    properties:
                      backends:
                        additionalProperties:
                          description: |-
                            BackendAuthStrategy defines how to authenticate to a specific backend.

                            This struct provides type-safe configuration for different authentication strategies
                            using HeaderInjection or TokenExchange fields based on the Type field.
                          properties:
                            awsSts:
                              description: |-
                                AwsSts contains configuration for AWS STS auth strategy.
                                Used when Type = "aws_sts".
                              properties:
                                fallbackRoleArn:
                                  description: FallbackRoleArn is the IAM role ARN
                                    to assume when no role mappings match.
                                  type: string
                                region:
                                  description: Region is the AWS region for the STS
                                    endpoint and service.
                                  type: string
                                roleClaim:
                                  description: RoleClaim is the JWT claim to use for
                                    role mapping evaluation.
                                  type: string
                                roleMappings:
                                  description: RoleMappings defines claim-based role
                                    selection rules.
                                  items:
                                    description: |-
                                      RoleMapping defines a rule for mapping JWT claims to IAM roles.
                                      Mappings are evaluated in priority order (lower number = higher priority).
                                    properties:
                                      claim:
                                        description: Claim is a simple claim value
                                          to match against the RoleClaim field.
                                        type: string
                                      matcher:
                                        description: Matcher is a CEL expression for
                                          complex matching against JWT claims.
                                        type: string
                                      priority:
                                        description: |-
                                          Priority determines evaluation order (lower values = higher priority).
                                          Mirrors awssts.RoleMapping.Priority, which is *int because the role mapper
                                          uses math.MaxInt for nil-priority semantics in effectivePriority.
                                        type: integer
                                      roleArn:
                                        description: RoleArn is the IAM role ARN to
                                          assume when this mapping matches.
                                        type: string
                                    required:
                                    - roleArn
                                    type: object
                                  type: array
                                  x-kubernetes-list-type: atomic
                                service:
                                  description: Service is the AWS service name for
                                    SigV4 signing.
                                  type: string
                                sessionDuration:
                                  description: SessionDuration is the duration in
                                    seconds for the STS session.
                                  format: int32
                                  type: integer
                                sessionNameClaim:
                                  description: SessionNameClaim is the JWT claim to
                                    use for the role session name.
                                  type: string
                                subjectProviderName:
                                  description: |-
                                    SubjectProviderName selects which upstream provider's token to use as the
                                    web identity token for AssumeRoleWithWebIdentity. When set, the token is
                                    looked up from Identity.UpstreamTokens instead of the request's
                                    Authorization header.
                                  type: string
                              required:
                              - region
                              type: object
                            headerInjection:
                              description: |-
                                HeaderInjection contains configuration for header injection auth strategy.
                                Used when Type = "header_injection".
                              properties:
                                headerName:
                                  description: HeaderName is the name of the header
                                    to inject (e.g., "Authorization").
                                  type: string
                                headerValue:
                                  description: |-
                                    HeaderValue is the static header value to inject.
                                    Either HeaderValue or HeaderValueEnv should be set, not both.
                                  type: string
                                headerValueEnv:
                                  description: |-
                                    HeaderValueEnv is the environment variable name containing the header value.
                                    The value will be resolved at runtime from this environment variable.
                                    Either HeaderValue or HeaderValueEnv should be set, not both.
                                  type: string
                              required:
                              - headerName
                              type: object
                            tokenExchange:
                              description: |-
                                TokenExchange contains configuration for token exchange auth strategy.
                                Used when Type = "token_exchange".
                              properties:
                                audience:
                                  description: Audience is the target audience for
                                    the exchanged token.
                                  type: string
                                clientId:
                                  description: ClientID is the OAuth client ID for
                                    the token exchange request.
                                  type: string
                                clientSecret:
                                  description: ClientSecret is the OAuth client secret
                                    (use ClientSecretEnv for security).
                                  type: string
                                clientSecretEnv:
                                  description: |-
                                    ClientSecretEnv is the environment variable name containing the client secret.
                                    The value will be resolved at runtime from this environment variable.
                                  type: string
                                scopes:
                                  description: Scopes are the requested scopes for
                                    the exchanged token.
                                  items:
                                    type: string
                                  type: array
                                subjectProviderName:
                                  description: |-
                                    SubjectProviderName selects which upstream provider's token to use as the
                                    subject token. When set, the token is looked up from Identity.UpstreamTokens
                                    instead of using Identity.Token.
                                    When left empty and an embedded authorization server is configured, the system
                                    automatically populates this field with the first configured upstream provider name.
                                    Set it explicitly to override that default or to select a specific provider when
                                    multiple upstreams are configured.
                                  type: string
                                subjectTokenType:
                                  description: |-
                                    SubjectTokenType is the token type of the incoming subject token.
                                    Defaults to "urn:ietf:params:oauth:token-type:access_token" if not specified.
                                  type: string
                                tokenUrl:
                                  description: TokenURL is the OAuth token endpoint
                                    URL for token exchange.
                                  type: string
                              required:
                              - tokenUrl
                              type: object
                            type:
                              description: 'Type is the auth strategy: "unauthenticated",
                                "header_injection", "token_exchange", "upstream_inject",
                                "aws_sts", "obo"'
                              type: string
                            upstreamInject:
                              description: |-
                                UpstreamInject contains configuration for upstream inject auth strategy.
                                Used when Type = "upstream_inject".
                              properties:
                                providerName:
                                  description: |-
                                    ProviderName is the name of the upstream provider configured in the
                                    embedded authorization server. Must match an entry in AuthServer.Upstreams.
                                  type: string
                              required:
                              - providerName
                              type: object
                          required:
                          - type
                          type: object
                        description: Backends contains per-backend auth configuration.
                        type: object
                      default:
                        description: Default is the default auth strategy for backends
                          without explicit config.
                        properties:
                          awsSts:
                            description: |-
                              AwsSts contains configuration for AWS STS auth strategy.
                              Used when Type = "aws_sts".
                            properties:
                              fallbackRoleArn:
                                description: FallbackRoleArn is the IAM role ARN to
                                  assume when no role mappings match.
                                type: string
                              region:
                                description: Region is the AWS region for the STS
                                  endpoint and service.
                                type: string
                              roleClaim:
                                description: RoleClaim is the JWT claim to use for
                                  role mapping evaluation.
                                type: string
                              roleMappings:
                                description: RoleMappings defines claim-based role
                                  selection rules.
                                items:
                                  description: |-
                                    RoleMapping defines a rule for mapping JWT claims to IAM roles.
                                    Mappings are evaluated in priority order (lower number = higher priority).
                                  properties:
                                    claim:
                                      description: Claim is a simple claim value to
                                        match against the RoleClaim field.
                                      type: string
                                    matcher:
                                      description: Matcher is a CEL expression for
                                        complex matching against JWT claims.
                                      type: string
                                    priority:
                                      description: |-
                                        Priority determines evaluation order (lower values = higher priority).
                                        Mirrors awssts.RoleMapping.Priority, which is *int because the role mapper
                                        uses math.MaxInt for nil-priority semantics in effectivePriority.
                                      type: integer
                                    roleArn:
                                      description: RoleArn is the IAM role ARN to
                                        assume when this mapping matches.
                                      type: string
                                  required:
                                  - roleArn
                                  type: object
                                type: array
                                x-kubernetes-list-type: atomic
                              service:
                                description: Service is the AWS service name for SigV4
                                  signing.
                                type: string
                              sessionDuration:
                                description: SessionDuration is the duration in seconds
                                  for the STS session.
                                format: int32
                                type: integer
                              sessionNameClaim:
                                description: SessionNameClaim is the JWT claim to
                                  use for the role session name.
                                type: string
                              subjectProviderName:
                                description: |-
                                  SubjectProviderName selects which upstream provider's token to use as the
                                  web identity token for AssumeRoleWithWebIdentity. When set, the token is
                                  looked up from Identity.UpstreamTokens instead of the request's
                                  Authorization header.
                                type: string
                            required:
                            - region
                            type: object
                          headerInjection:
                            description: |-
                              HeaderInjection contains configuration for header injection auth strategy.
                              Used when Type = "header_injection".
                            properties:
                              headerName:
                                description: HeaderName is the name of the header
                                  to inject (e.g., "Authorization").
                                type: string
                              headerValue:
                                description: |-
                                  HeaderValue is the static header value to inject.
                                  Either HeaderValue or HeaderValueEnv should be set, not both.
                                type: string
                              headerValueEnv:
                                description: |-
                                  HeaderValueEnv is the environment variable name containing the header value.
                                  The value will be resolved at runtime from this environment variable.
                                  Either HeaderValue or HeaderValueEnv should be set, not both.
                                type: string
                            required:
                            - headerName
                            type: object
                          tokenExchange:
                            description: |-
                              TokenExchange contains configuration for token exchange auth strategy.
                              Used when Type = "token_exchange".
                            properties:
                              audience:
                                description: Audience is the target audience for the
                                  exchanged token.
                                type: string
                              clientId:
                                description: ClientID is the OAuth client ID for the
                                  token exchange request.
                                type: string
                              clientSecret:
                                description: ClientSecret is the OAuth client secret
                                  (use ClientSecretEnv for security).
                                type: string
                              clientSecretEnv:
                                description: |-
                                  ClientSecretEnv is the environment variable name containing the client secret.
                                  The value will be resolved at runtime from this environment variable.
                                type: string
                              scopes:
                                description: Scopes are the requested scopes for the
                                  exchanged token.
                                items:
                                  type: string
                                type: array
                              subjectProviderName:
                                description: |-
                                  SubjectProviderName selects which upstream provider's token to use as the
                                  subject token. When set, the token is looked up from Identity.UpstreamTokens
                                  instead of using Identity.Token.
                                  When left empty and an embedded authorization server is configured, the system
                                  automatically populates this field with the first configured upstream provider name.
                                  Set it explicitly to override that default or to select a specific provider when
                                  multiple upstreams are configured.
                                type: string
                              subjectTokenType:
                                description: |-
                                  SubjectTokenType is the token type of the incoming subject token.
                                  Defaults to "urn:ietf:params:oauth:token-type:access_token" if not specified.
                                type: string
                              tokenUrl:
                                description: TokenURL is the OAuth token endpoint
                                  URL for token exchange.
                                type: string
                            required:
                            - tokenUrl
                            type: object
                          type:
                            description: 'Type is the auth strategy: "unauthenticated",
                              "header_injection", "token_exchange", "upstream_inject",
                              "aws_sts", "obo"'
                            type: string
                          upstreamInject:
                            description: |-
                              UpstreamInject contains configuration for upstream inject auth strategy.
                              Used when Type = "upstream_inject".
                            properties:
                              providerName:
                                description: |-
                                  ProviderName is the name of the upstream provider configured in the
                                  embedded authorization server. Must match an entry in AuthServer.Upstreams.
                                type: string
                            required:
                            - providerName
                            type: object
                        required:
                        - type
                        type: object
                      source:
                        description: |-
                          Source defines how to discover backend auth: "inline", "discovered"
                          - inline: Explicit configuration in OutgoingAuth
                          - discovered: Auto-discover from backend MCPServer.externalAuthConfigRef (Kubernetes only)
                        type: string
                    required:
                    - source
                    type: object
                  rateLimiting:
                    description: |-
                      RateLimiting defines rate limiting configuration for the Virtual MCP server.
                      Requires Redis session storage to be configured for distributed rate limiting.
                    properties:
                      perUser:
                        description: |-
                          PerUser is a token bucket applied independently to each authenticated user
                          at the server level. Requires authentication to be enabled.
                          Each unique userID creates Redis keys that expire after 2x refillPeriod.
                          Memory formula: unique_users_per_TTL_window * (1 + num_tools_with_per_user_limits) keys.
                        properties:
                          maxTokens:
                            description: |-
                              MaxTokens is the maximum number of tokens (bucket capacity).
                              This is also the burst size: the maximum number of requests that can be served
                              instantaneously before the bucket is depleted.
                            format: int32
                            minimum: 1
                            type: integer
                          refillPeriod:
                            description: |-
                              RefillPeriod is the duration to fully refill the bucket from zero to maxTokens.
                              The effective refill rate is maxTokens / refillPeriod tokens per second.
                              Format: Go duration string (e.g., "1m0s", "30s", "1h0m0s").
                            type: string
                        required:
                        - maxTokens
                        - refillPeriod
                        type: object
                      shared:
                        description: Shared is a token bucket shared across all users
                          for the entire server.
                        properties:
                          maxTokens:
                            description: |-
                              MaxTokens is the maximum number of tokens (bucket capacity).
                              This is also the burst size: the maximum number of requests that can be served
                              instantaneously before the bucket is depleted.
                            format: int32
                            minimum: 1
                            type: integer
                          refillPeriod:
                            description: |-
                              RefillPeriod is the duration to fully refill the bucket from zero to maxTokens.
                              The effective refill rate is maxTokens / refillPeriod tokens per second.
                              Format: Go duration string (e.g., "1m0s", "30s", "1h0m0s").
                            type: string
                        required:
                        - maxTokens
                        - refillPeriod
                        type: object
                      tools:
                        description: |-
                          Tools defines per-tool rate limit overrides.
                          Each entry applies additional rate limits to calls targeting a specific tool name.
                          A request must pass both the server-level limit and the per-tool limit.
                        items:
                          description: |-
                            ToolRateLimitConfig defines rate limits for a specific tool.
                            At least one of shared or perUser must be configured.
                          properties:
                            name:
                              description: Name is the MCP tool name this limit applies
                                to.
                              minLength: 1
                              type: string
                            perUser:
                              description: PerUser token bucket configuration for
                                this tool.
                              properties:
                                maxTokens:
                                  description: |-
                                    MaxTokens is the maximum number of tokens (bucket capacity).
                                    This is also the burst size: the maximum number of requests that can be served
                                    instantaneously before the bucket is depleted.
                                  format: int32
                                  minimum: 1
                                  type: integer
                                refillPeriod:
                                  description: |-
                                    RefillPeriod is the duration to fully refill the bucket from zero to maxTokens.
                                    The effective refill rate is maxTokens / refillPeriod tokens per second.
                                    Format: Go duration string (e.g., "1m0s", "30s", "1h0m0s").
                                  type: string
                              required:
                              - maxTokens
                              - refillPeriod
                              type: object
                            shared:
                              description: Shared token bucket for this specific tool.
                              properties:
                                maxTokens:
                                  description: |-
                                    MaxTokens is the maximum number of tokens (bucket capacity).
                                    This is also the burst size: the maximum number of requests that can be served
                                    instantaneously before the bucket is depleted.
                                  format: int32
                                  minimum: 1
                                  type: integer
                                refillPeriod:
                                  description: |-
                                    RefillPeriod is the duration to fully refill the bucket from zero to maxTokens.
                                    The effective refill rate is maxTokens / refillPeriod tokens per second.
                                    Format: Go duration string (e.g., "1m0s", "30s", "1h0m0s").
                                  type: string
                              required:
                              - maxTokens
                              - refillPeriod
                              type: object
                          required:
                          - name
                          type: object
                          x-kubernetes-validations:
                          - message: at least one of shared or perUser must be configured
                            rule: has(self.shared) || has(self.perUser)
                        type: array
                        x-kubernetes-list-map-keys:
                        - name
                        x-kubernetes-list-type: map
                    type: object
                    x-kubernetes-validations:
                    - message: at least one of shared, perUser, or tools must be configured
                      rule: has(self.shared) || has(self.perUser) || (has(self.tools)
                        && size(self.tools) > 0)
                  sessionStorage:
                    description: |-
                      SessionStorage configures session storage for stateful horizontal scaling.
                      When provider is "redis", the operator injects Redis connection parameters
                      (address, db, keyPrefix) here. The Redis password is provided separately via
                      the THV_SESSION_REDIS_PASSWORD environment variable.
                    properties:
                      address:
                        description: Address is the Redis server address (required
                          when provider is redis).
                        type: string
                      db:
                        default: 0
                        description: DB is the Redis database number.
                        format: int32
                        minimum: 0
                        type: integer
                      keyPrefix:
                        description: KeyPrefix is an optional prefix for all Redis
                          keys used by ToolHive.
                        type: string
                      provider:
                        description: Provider is the session storage backend type.
                        enum:
                        - memory
                        - redis
                        type: string
                    required:
                    - provider
                    type: object
                  telemetry:
                    description: |-
                      Telemetry configures OpenTelemetry-based observability for the Virtual MCP server
                      including distributed tracing, OTLP metrics export, and Prometheus metrics endpoint.
                      Deprecated (Kubernetes operator only): When deploying via the operator, use
                      VirtualMCPServer.spec.telemetryConfigRef to reference a shared MCPTelemetryConfig
                      resource instead. This field remains valid for standalone (non-operator) deployments.
                    properties:
                      caCertPath:
                        description: |-
                          CACertPath is the file path to a CA certificate bundle for the OTLP endpoint.
                          When set, the OTLP exporters use this CA to verify the collector's TLS certificate
                          instead of relying solely on the system CA pool.
                        type: string
                      customAttributes:
                        additionalProperties:
                          type: string
                        description: |-
                          CustomAttributes contains custom resource attributes to be added to all telemetry signals.
                          These are parsed from CLI flags (--otel-custom-attributes) or environment variables
                          (OTEL_RESOURCE_ATTRIBUTES) as key=value pairs.
                        type: object
                      enablePrometheusMetricsPath:
                        default: false
                        description: |-
                          EnablePrometheusMetricsPath controls whether to expose Prometheus-style /metrics endpoint.
                          The metrics are served on the main transport port at /metrics.
                          This is separate from OTLP metrics which are sent to the Endpoint.
                        type: boolean
                      endpoint:
                        description: Endpoint is the OTLP endpoint URL
                        type: string
                      environmentVariables:
                        description: |-
                          EnvironmentVariables is a list of environment variable names that should be
                          included in telemetry spans as attributes. Only variables in this list will
                          be read from the host machine and included in spans for observability.
                          Example: ["NODE_ENV", "DEPLOYMENT_ENV", "SERVICE_VERSION"]
                        items:
                          type: string
                        type: array
                      headers:
                        additionalProperties:
                          type: string
                        description: Headers contains authentication headers for the
                          OTLP endpoint.
                        type: object
                      insecure:
                        default: false
                        description: Insecure indicates whether to use HTTP instead
                          of HTTPS for the OTLP endpoint.
                        type: boolean
                      metricsEnabled:
                        default: false
                        description: |-
                          MetricsEnabled controls whether OTLP metrics are enabled.
                          When false, OTLP metrics are not sent even if an endpoint is configured.
                          This is independent of EnablePrometheusMetricsPath.
                        type: boolean
                      samplingRate:
                        default: "0.05"
                        description: |-
                          SamplingRate is the trace sampling rate (0.0-1.0) as a string.
                          Only used when TracingEnabled is true.
                          Example: "0.05" for 5% sampling.
                        type: string
                      serviceName:
                        description: |-
                          ServiceName is the service name for telemetry.
                          When omitted, defaults to the server name (e.g., VirtualMCPServer name).
                        type: string
                      serviceVersion:
                        description: |-
                          ServiceVersion is the service version for telemetry.
                          When omitted, defaults to the ToolHive version.
                        type: string
                      tracingEnabled:
                        default: false
                        description: |-
                          TracingEnabled controls whether distributed tracing is enabled.
                          When false, no tracer provider is created even if an endpoint is configured.
                        type: boolean
                      useLegacyAttributes:
                        default: true
                        description: |-
                          UseLegacyAttributes controls whether legacy (pre-MCP OTEL semconv) attribute names
                          are emitted alongside the new standard attribute names. When true, spans include both
                          old and new attribute names for backward compatibility with existing dashboards.
                          Currently defaults to true; this will change to false in a future release.
                        type: boolean
                    type: object
                type: object
                x-kubernetes-preserve-unknown-fields: true
              embeddingServerRef:
                description: |-
                  EmbeddingServerRef references an existing EmbeddingServer resource by name.
                  When the optimizer is enabled, this field is required to point to a ready EmbeddingServer
                  that provides embedding capabilities.
                  The referenced EmbeddingServer must exist in the same namespace and be ready.
                properties:
                  name:
                    description: Name is the name of the EmbeddingServer resource
                    type: string
                required:
                - name
                type: object
              groupRef:
                description: |-
                  GroupRef references the MCPGroup that defines backend workloads.
                  The referenced MCPGroup must exist in the same namespace.
                properties:
                  name:
                    description: Name is the name of the MCPGroup resource in the
                      same namespace
                    minLength: 1
                    type: string
                required:
                - name
                type: object
              imagePullSecrets:
                description: |-
                  ImagePullSecrets allows specifying image pull secrets for the vMCP workload.
                  These are applied to both the vMCP Deployment's PodSpec.ImagePullSecrets
                  and to the operator-managed ServiceAccount the vMCP server runs as, so private
                  images are pullable through either path.

                  Merge semantics with PodTemplateSpec:
                  The deployed PodSpec.ImagePullSecrets is the Kubernetes-native strategic-merge
                  union of this field and spec.podTemplateSpec.spec.imagePullSecrets, merged by
                  the patchStrategy:"merge" / patchMergeKey:"name" tags on corev1.PodSpec.
                    - This field is rendered first as the controller-generated default.
                    - spec.podTemplateSpec.spec.imagePullSecrets is then strategic-merge-patched
                      on top, keyed by Name. Distinct names from the two sources are unioned in
                      the resulting list; entries with the same Name are deduplicated and the
                      PodTemplateSpec entry wins on overlap (user override).
                    - Order in the resulting list is not guaranteed and should not be relied on:
                      strategic merge by name is order-insensitive.
                    - The operator-managed ServiceAccount's imagePullSecrets list is populated
                      ONLY from this field. spec.podTemplateSpec.spec.imagePullSecrets does not
                      reach the ServiceAccount because PodTemplateSpec has no notion of a
                      ServiceAccount. To make a secret usable via the ServiceAccount path
                      (e.g. for sidecars or init containers that pull images independently),
                      list it here rather than under spec.podTemplateSpec.

                  Note on cross-CRD consistency:
                  MCPRegistry currently uses an atomic-replace strategy for its imagePullSecrets
                  (the user-provided value replaces the controller-generated list rather than
                  being merged on top). VirtualMCPServer follows the Kubernetes-native
                  strategic-merge-by-name behavior described above. Aligning the two is tracked
                  as a separate follow-up; until then, manifests that set imagePullSecrets on
                  both CRDs will see different override behavior between them.
                items:
                  description: |-
                    LocalObjectReference contains enough information to let you locate the
                    referenced object inside the same namespace.
                  properties:
                    name:
                      default: ""
                      description: |-
                        Name of the referent.
                        This field is effectively required, but due to backwards compatibility is
                        allowed to be empty. Instances of this type with an empty value here are
                        almost certainly wrong.
                        More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
                      type: string
                  type: object
                  x-kubernetes-map-type: atomic
                type: array
                x-kubernetes-list-type: atomic
              incomingAuth:
                description: |-
                  IncomingAuth configures authentication for clients connecting to the Virtual MCP server.
                  Must be explicitly set - use "anonymous" type when no authentication is required.
                  This field takes precedence over config.IncomingAuth and should be preferred because it
                  supports Kubernetes-native secret references (SecretKeyRef, ConfigMapRef) for secure
                  dynamic discovery of credentials, rather than requiring secrets to be embedded in config.
                properties:
                  authzConfig:
                    description: |-
                      AuthzConfig defines authorization policy configuration
                      Reuses MCPServer authz patterns
                    properties:
                      configMap:
                        description: |-
                          ConfigMap references a ConfigMap containing authorization configuration
                          Only used when Type is "configMap"
                        properties:
                          key:
                            default: authz.json
                            description: Key is the key in the ConfigMap that contains
                              the authorization configuration
                            type: string
                          name:
                            description: Name is the name of the ConfigMap
                            type: string
                        required:
                        - name
                        type: object
                      groupClaimName:
                        description: |-
                          GroupClaimName is the JWT claim key that contains group membership for the
                          principal. When set, takes priority over the well-known defaults
                          ("groups", "roles", "cognito:groups"). Use this for IDPs that place
                          groups under a URI-style claim (e.g. "https://example.com/groups"). When
                          Type is "configMap", a group_claim_name entry in the referenced ConfigMap
                          is overridden by this field if both are set.
                        maxLength: 253
                        type: string
                      groupEntityType:
                        description: |-
                          GroupEntityType is the Cedar entity type name used for principal parent
                          UIDs synthesised from JWT group/role claims. Defaults to "THVGroup" when
                          empty. Must match the entity type used in the static entity store for
                          transitive `in` checks (e.g. `ClaimGroup → PlatformRole`) to resolve.
                          Namespaced names (`Foo::Bar`) are not yet supported. When Type is
                          "configMap", a group_entity_type entry in the referenced ConfigMap is
                          overridden by this field if both are set.
                        maxLength: 63
                        pattern: ^[A-Za-z_][A-Za-z0-9_]*$
                        type: string
                      inline:
                        description: |-
                          Inline contains direct authorization configuration
                          Only used when Type is "inline"
                        properties:
                          entitiesJson:
                            default: '[]'
                            description: |-
                              EntitiesJSON is a JSON string representing Cedar entities. Required when
                              transitive policies (e.g. `ClaimGroup → PlatformRole`) need a static
                              entity store; defaults to "[]".
                            type: string
                          policies:
                            description: Policies is a list of Cedar policy strings
                            items:
                              type: string
                            minItems: 1
                            type: array
                            x-kubernetes-list-type: atomic
                          primaryUpstreamProvider:
                            description: |-
                              PrimaryUpstreamProvider names the upstream IDP whose access token's
                              claims Cedar should evaluate.

                              Deprecated: on VirtualMCPServer this field has moved to
                              spec.authServerConfig.primaryUpstreamProvider. The old location is
                              still read for one release for backward compatibility; the
                              VirtualMCPServer controller emits an AuthzPrimaryUpstreamProviderDeprecated
                              Warning event whenever it is consumed, and removal is planned for the
                              release after the deprecation cycle.

                              On MCPServer and MCPRemoteProxy this field has always been a structural
                              no-op (those CRDs do not run an embedded auth server). Setting it
                              continues to surface the AuthzPrimaryUpstreamProviderIgnored advisory
                              condition; the deprecation does not change that behaviour.
                            maxLength: 63
                            minLength: 1
                            pattern: ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$
                            type: string
                        required:
                        - policies
                        type: object
                      roleClaimName:
                        description: |-
                          RoleClaimName is the JWT claim key that contains role membership for the
                          principal. When set, the claim is extracted separately from GroupClaimName
                          and both are mapped to the configured GroupEntityType. When Type is
                          "configMap", a role_claim_name entry in the referenced ConfigMap is
                          overridden by this field if both are set.
                        maxLength: 253
                        type: string
                      type:
                        default: configMap
                        description: Type is the type of authorization configuration
                        enum:
                        - configMap
                        - inline
                        type: string
                    required:
                    - type
                    type: object
                    x-kubernetes-validations:
                    - message: configMap must be set when type is 'configMap', and
                        must not be set otherwise
                      rule: 'self.type == ''configMap'' ? has(self.configMap) : !has(self.configMap)'
                    - message: inline must be set when type is 'inline', and must
                        not be set otherwise
                      rule: 'self.type == ''inline'' ? has(self.inline) : !has(self.inline)'
                  oidcConfigRef:
                    description: |-
                      OIDCConfigRef references a shared MCPOIDCConfig resource for OIDC authentication.
                      The referenced MCPOIDCConfig must exist in the same namespace as this VirtualMCPServer.
                      Per-server overrides (audience, scopes) are specified here; shared provider config
                      lives in the MCPOIDCConfig resource.
                    properties:
                      audience:
                        description: |-
                          Audience is the expected audience for token validation.
                          This MUST be unique per server to prevent token replay attacks.
                        minLength: 1
                        type: string
                      name:
                        description: Name is the name of the MCPOIDCConfig resource
                        minLength: 1
                        type: string
                      resourceUrl:
                        description: |-
                          ResourceURL is the public URL for OAuth protected resource metadata (RFC 9728).
                          When the server is exposed via Ingress or gateway, set this to the external
                          URL that MCP clients connect to. If not specified, defaults to the internal
                          Kubernetes service URL.
                        type: string
                      scopes:
                        description: |-
                          Scopes is the list of OAuth scopes to advertise in the well-known endpoint (RFC 9728).
                          If empty, defaults to ["openid"].
                        items:
                          type: string
                        type: array
                        x-kubernetes-list-type: atomic
                    required:
                    - audience
                    - name
                    type: object
                  type:
                    description: |-
                      Type defines the authentication type: anonymous or oidc
                      When no authentication is required, explicitly set this to "anonymous"
                    enum:
                    - anonymous
                    - oidc
                    type: string
                required:
                - type
                type: object
                x-kubernetes-validations:
                - message: spec.incomingAuth.oidcConfigRef is required when type is
                    oidc
                  rule: 'self.type == ''oidc'' ? has(self.oidcConfigRef) : true'
              outgoingAuth:
                description: |-
                  OutgoingAuth configures authentication from Virtual MCP to backend MCPServers.
                  This field takes precedence over config.OutgoingAuth and should be preferred because it
                  supports Kubernetes-native secret references (SecretKeyRef, ConfigMapRef) for secure
                  dynamic discovery of credentials, rather than requiring secrets to be embedded in config.
                properties:
                  backends:
                    additionalProperties:
                      description: BackendAuthConfig defines authentication configuration
                        for a backend MCPServer
                      properties:
                        externalAuthConfigRef:
                          description: |-
                            ExternalAuthConfigRef references an MCPExternalAuthConfig resource
                            Only used when Type is "externalAuthConfigRef"
                          properties:
                            name:
                              description: Name is the name of the MCPExternalAuthConfig
                                resource
                              type: string
                          required:
                          - name
                          type: object
                        type:
                          description: Type defines the authentication type
                          enum:
                          - discovered
                          - externalAuthConfigRef
                          type: string
                      required:
                      - type
                      type: object
                    description: |-
                      Backends defines per-backend authentication overrides
                      Works in all modes (discovered, inline)
                    type: object
                  default:
                    description: Default defines default behavior for backends without
                      explicit auth config
                    properties:
                      externalAuthConfigRef:
                        description: |-
                          ExternalAuthConfigRef references an MCPExternalAuthConfig resource
                          Only used when Type is "externalAuthConfigRef"
                        properties:
                          name:
                            description: Name is the name of the MCPExternalAuthConfig
                              resource
                            type: string
                        required:
                        - name
                        type: object
                      type:
                        description: Type defines the authentication type
                        enum:
                        - discovered
                        - externalAuthConfigRef
                        type: string
                    required:
                    - type
                    type: object
                  source:
                    default: discovered
                    description: |-
                      Source defines how backend authentication configurations are determined
                      - discovered: Automatically discover from backend's MCPServer.spec.externalAuthConfigRef
                      - inline: Explicit per-backend configuration in VirtualMCPServer
                    enum:
                    - discovered
                    - inline
                    type: string
                type: object
              podTemplateSpec:
                description: |-
                  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
                x-kubernetes-preserve-unknown-fields: true
              replicas:
                description: |-
                  Replicas is the desired number of vMCP pod replicas.
                  VirtualMCPServer creates a single Deployment for the vMCP aggregator process,
                  so there is only one replicas field (unlike MCPServer which has separate
                  Replicas and BackendReplicas for its two Deployments).
                  When nil, the operator does not set Deployment.Spec.Replicas, leaving replica
                  management to an HPA or other external controller.
                format: int32
                minimum: 0
                type: integer
              serviceAccount:
                description: |-
                  ServiceAccount is the name of an already existing service account to use by the Virtual MCP server.
                  If not specified, a ServiceAccount will be created automatically and used by the Virtual MCP server.
                type: string
              serviceType:
                default: ClusterIP
                description: ServiceType specifies the Kubernetes service type for
                  the Virtual MCP server
                enum:
                - ClusterIP
                - NodePort
                - LoadBalancer
                type: string
              sessionAffinity:
                default: ClientIP
                description: |-
                  SessionAffinity controls whether the Service routes repeated client connections to the same pod.
                  MCP protocols (SSE, streamable-http) are stateful, so ClientIP is the default.
                  Set to "None" for stateless servers or when using an external load balancer with its own affinity.
                enum:
                - ClientIP
                - None
                type: string
              sessionStorage:
                description: |-
                  SessionStorage configures session storage for stateful horizontal scaling.
                  When nil, no session storage is configured.
                properties:
                  address:
                    description: Address is the Redis server address (required when
                      provider is redis)
                    minLength: 1
                    type: string
                  db:
                    default: 0
                    description: DB is the Redis database number
                    format: int32
                    minimum: 0
                    type: integer
                  keyPrefix:
                    description: KeyPrefix is an optional prefix for all Redis keys
                      used by ToolHive
                    type: string
                  passwordRef:
                    description: PasswordRef is a reference to a Secret key containing
                      the Redis password
                    properties:
                      key:
                        description: Key is the key within the secret
                        type: string
                      name:
                        description: Name is the name of the secret
                        type: string
                    required:
                    - key
                    - name
                    type: object
                  provider:
                    description: Provider is the session storage backend type
                    enum:
                    - memory
                    - redis
                    type: string
                required:
                - provider
                type: object
                x-kubernetes-validations:
                - message: address is required
                  rule: 'self.provider == ''redis'' ? has(self.address) : true'
              telemetryConfigRef:
                description: |-
                  TelemetryConfigRef references an MCPTelemetryConfig resource for shared telemetry configuration.
                  The referenced MCPTelemetryConfig must exist in the same namespace as this VirtualMCPServer.
                  Cross-namespace references are not supported for security and isolation reasons.
                properties:
                  name:
                    description: Name is the name of the MCPTelemetryConfig resource
                    minLength: 1
                    type: string
                  serviceName:
                    description: |-
                      ServiceName overrides the telemetry service name for this specific server.
                      This MUST be unique per server for proper observability (e.g., distinguishing
                      traces and metrics from different servers sharing the same collector).
                      If empty, defaults to the server name with "thv-" prefix at runtime.
                    type: string
                required:
                - name
                type: object
            required:
            - groupRef
            - incomingAuth
            type: object
            x-kubernetes-validations:
            - message: config.rateLimiting requires sessionStorage with provider 'redis'
              rule: '!has(self.config) || !has(self.config.rateLimiting) || (has(self.sessionStorage)
                && self.sessionStorage.provider == ''redis'')'
            - message: config.rateLimiting.perUser requires incomingAuth.type oidc
              rule: '!(has(self.config) && has(self.config.rateLimiting) && has(self.config.rateLimiting.perUser))
                || (has(self.incomingAuth) && self.incomingAuth.type == ''oidc'')'
            - message: per-tool perUser rate limiting requires incomingAuth.type oidc
              rule: '!has(self.config) || !has(self.config.rateLimiting) || !has(self.config.rateLimiting.tools)
                || self.config.rateLimiting.tools.all(t, !has(t.perUser)) || (has(self.incomingAuth)
                && self.incomingAuth.type == ''oidc'')'
          status:
            description: VirtualMCPServerStatus defines the observed state of VirtualMCPServer
            properties:
              backendCount:
                description: |-
                  BackendCount is the number of routable backends (ready + unauthenticated).
                  Excludes unavailable, degraded, and unknown backends.
                format: int32
                type: integer
              conditions:
                description: Conditions represent the latest available observations
                  of the VirtualMCPServer's state
                items:
                  description: Condition contains details for one aspect of the current
                    state of this API Resource.
                  properties:
                    lastTransitionTime:
                      description: |-
                        lastTransitionTime is the last time the condition transitioned from one status to another.
                        This should be when the underlying condition changed.  If that is not known, then using the time when the API field changed is acceptable.
                      format: date-time
                      type: string
                    message:
                      description: |-
                        message is a human readable message indicating details about the transition.
                        This may be an empty string.
                      maxLength: 32768
                      type: string
                    observedGeneration:
                      description: |-
                        observedGeneration represents the .metadata.generation that the condition was set based upon.
                        For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date
                        with respect to the current state of the instance.
                      format: int64
                      minimum: 0
                      type: integer
                    reason:
                      description: |-
                        reason contains a programmatic identifier indicating the reason for the condition's last transition.
                        Producers of specific condition types may define expected values and meanings for this field,
                        and whether the values are considered a guaranteed API.
                        The value should be a CamelCase string.
                        This field may not be empty.
                      maxLength: 1024
                      minLength: 1
                      pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$
                      type: string
                    status:
                      description: status of the condition, one of True, False, Unknown.
                      enum:
                      - "True"
                      - "False"
                      - Unknown
                      type: string
                    type:
                      description: type of condition in CamelCase or in foo.example.com/CamelCase.
                      maxLength: 316
                      pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$
                      type: string
                  required:
                  - lastTransitionTime
                  - message
                  - reason
                  - status
                  - type
                  type: object
                type: array
                x-kubernetes-list-map-keys:
                - type
                x-kubernetes-list-type: map
              discoveredBackends:
                description: DiscoveredBackends lists discovered backend configurations
                  from the MCPGroup
                items:
                  description: |-
                    DiscoveredBackend represents a backend server discovered by vMCP runtime.
                    This type is shared with the Kubernetes operator CRD (VirtualMCPServer.Status.DiscoveredBackends).
                  properties:
                    authConfigRef:
                      description: AuthConfigRef is the name of the discovered MCPExternalAuthConfig
                        (if any)
                      type: string
                    authType:
                      description: AuthType is the type of authentication configured
                      type: string
                    circuitBreakerState:
                      description: |-
                        CircuitBreakerState is the current circuit breaker state (closed, open, half-open).
                        Empty when circuit breaker is disabled or not configured.
                      enum:
                      - closed
                      - open
                      - half-open
                      type: string
                    circuitLastChanged:
                      description: |-
                        CircuitLastChanged is the timestamp when the circuit breaker state last changed.
                        Empty when circuit breaker is disabled or has never changed state.
                      format: date-time
                      type: string
                    consecutiveFailures:
                      description: |-
                        ConsecutiveFailures is the current count of consecutive health check failures.
                        Resets to 0 when the backend becomes healthy again.
                      type: integer
                    lastHealthCheck:
                      description: LastHealthCheck is the timestamp of the last health
                        check
                      format: date-time
                      type: string
                    message:
                      description: Message provides additional information about the
                        backend status
                      type: string
                    name:
                      description: Name is the name of the backend MCPServer
                      type: string
                    status:
                      description: |-
                        Status is the current status of the backend (ready, degraded, unavailable, unauthenticated, unknown).
                        Use BackendHealthStatus.ToCRDStatus() to populate this field.
                      type: string
                    url:
                      description: URL is the URL of the backend MCPServer
                      type: string
                  required:
                  - name
                  type: object
                type: array
                x-kubernetes-list-map-keys:
                - name
                x-kubernetes-list-type: map
              message:
                description: Message provides additional information about the current
                  phase
                type: string
              observedGeneration:
                description: ObservedGeneration is the most recent generation observed
                  for this VirtualMCPServer
                format: int64
                type: integer
              oidcConfigHash:
                description: |-
                  OIDCConfigHash is the hash of the referenced MCPOIDCConfig spec for change detection.
                  Only populated when IncomingAuth.OIDCConfigRef is set.
                type: string
              phase:
                default: Pending
                description: Phase is the current phase of the VirtualMCPServer
                enum:
                - Pending
                - Ready
                - Degraded
                - Failed
                type: string
              telemetryConfigHash:
                description: |-
                  TelemetryConfigHash is the hash of the referenced MCPTelemetryConfig spec for change detection.
                  Only populated when TelemetryConfigRef is set.
                type: string
              url:
                description: URL is the URL where the Virtual MCP server can be accessed
                type: string
            type: object
        type: object
    served: true
    storage: true
    subresources:
      status: {}
{{- end }}