---
title: "Export workload configuration"
method: GET
path: "/api/v1beta/workloads/{name}/export"
tags: ["workloads"]
---

# Export workload configuration

`GET /api/v1beta/workloads/{name}/export`

Export a workload's run configuration as JSON

## Path parameters

- `name` string, required

## Response `200`

OK

- GithubComStacklokToolhivePkgRunnerRunConfig
  - `additional_middleware_configs` TypesMiddlewareConfig[] — AdditionalMiddlewareConfigs carries pre-built middleware configs injected by external-auth handlers (reached via *[]RunConfigBuilderOption) rather than derived from typed RunConfig fields. PopulateMiddlewareConfigs splices these into the chain in the backend-egress group — after auth and before recovery — instead of discarding them. Upstream carries these configs verbatim and never inspects their parameters; the middleware type identity (e.g. an enterprise auth type) is supplied by the caller via types.MiddlewareConfig.Type. Each entry's Type is expected to be a NEW egress middleware type (e.g. OBO), not one already produced from a typed RunConfig field (auth, authz, audit, tokenExchange, awssts, …). Dispatch in the proxyrunner is purely by Type string, so an injected Type that shadows a typed-field type would add a second instance of that middleware to the chain; the seam does not validate against this.
    - `parameters` object — Parameters is a JSON object containing the middleware parameters. It is stored as a raw message to allow flexible parameter types.
    - `type` string — Type is a string representing the middleware type.
  - `allow_docker_gateway` boolean — AllowDockerGateway permits outbound connections to Docker gateway addresses (host.docker.internal, gateway.docker.internal, 172.17.0.1). These are blocked by default in the egress proxy even when InsecureAllowAll is set. Only applicable to Docker deployments with network isolation enabled. Gateway access is port-independent: it ignores the permission profile's allowed ports, so once enabled the gateway is reachable on any port.
  - `allowed_origins` string[] — AllowedOrigins is the allowlist of values accepted on the HTTP Origin header, used for DNS-rebinding protection per MCP 2025-11-25 §"Security Warning". When empty and Host is loopback (127.0.0.1 / localhost / [::1]), a default loopback-only allowlist is derived at middleware-wiring time. When empty and Host is non-loopback, the middleware is disabled — operators exposing the proxy publicly must configure an explicit allowlist.
  - `audit_config` AuditConfig — DEPRECATED: Middleware configuration. AuditConfig contains the audit logging configuration
    - `component` string — Component is the component name to use in audit events. +optional
    - `detectApplicationErrors` boolean — DetectApplicationErrors controls whether the audit middleware inspects JSON-RPC response bodies for application-level errors when the HTTP status code indicates success (2xx). When enabled, a small prefix of the response body is buffered to detect JSON-RPC error fields, independent of the IncludeResponseData setting. +kubebuilder:default=true +optional
    - `enabled` boolean — Enabled controls whether audit logging is enabled. When true, enables audit logging with the configured options. +kubebuilder:default=false +optional
    - `eventTypes` string[] — EventTypes specifies which event types to audit. If empty, all events are audited. +optional
    - `excludeEventTypes` string[] — ExcludeEventTypes specifies which event types to exclude from auditing. This takes precedence over EventTypes. +optional
    - `includeRequestData` boolean — IncludeRequestData determines whether to include request data in audit logs. +kubebuilder:default=false +optional
    - `includeResponseData` boolean — IncludeResponseData determines whether to include response data in audit logs. +kubebuilder:default=false +optional
    - `logFile` string — LogFile specifies the file path for audit logs. If empty, logs to stdout. +optional
    - `maxDataSize` integer — MaxDataSize limits the size of request/response data included in audit logs (in bytes). +kubebuilder:default=1024 +optional
    - `maxDelegationDepth` integer — MaxDelegationDepth caps how many nested RFC 8693 "act" entries are recorded in an audit event's delegation chain. Deeper chains are truncated (marked with truncated=true). Defaults to 10 when unset. +kubebuilder:validation:Minimum=1 +kubebuilder:default=10 +optional
  - `audit_config_path` string — DEPRECATED: Middleware configuration. AuditConfigPath is the path to the audit configuration file
  - `authz_config` GithubComStacklokToolhivePkgAuthzConfig — DEPRECATED: Middleware configuration. AuthzConfig contains the authorization configuration
    - `type` string — Type is the type of authorization configuration (e.g., "cedarv1").
    - `version` string — Version is the version of the configuration format.
  - `authz_config_path` string — DEPRECATED: Middleware configuration. AuthzConfigPath is the path to the authorization configuration file
  - `aws_sts_config` GithubComStacklokToolhivePkgAuthAwsstsConfig — AWSStsConfig contains AWS STS token exchange configuration for accessing AWS services
    - `fallback_role_arn` string — FallbackRoleArn is the IAM role ARN to assume when no role mapping matches.
    - `region` string — Region is the AWS region for STS and SigV4 signing.
    - `role_claim` string — RoleClaim is the JWT claim to use for role mapping (default: "groups").
    - `role_mappings` GithubComStacklokToolhivePkgAuthAwsstsRoleMapping[] — RoleMappings maps JWT claim values to IAM roles with priority.
      - `claim` string — Claim is the simple claim value to match (e.g., group name). Internally compiles to a CEL expression: "<claim_value>" in claims["<role_claim>"] Mutually exclusive with Matcher.
      - `matcher` string — Matcher is a CEL expression for complex matching against JWT claims. The expression has access to a "claims" variable containing all JWT claims. Examples: - "admins" in claims["groups"] - claims["sub"] == "user123" && !("act" in claims) Mutually exclusive with Claim.
      - `priority` integer — Priority determines selection order (lower number = higher priority). When multiple mappings match, the one with the lowest priority is selected. When nil (omitted), the mapping has the lowest possible priority, and configuration order acts as tie-breaker via stable sort.
      - `role_arn` string — RoleArn is the IAM role ARN to assume when this mapping matches.
    - `service` string — Service is the AWS service name for SigV4 signing (default: "aws-mcp").
    - `session_duration` integer — SessionDuration is the duration in seconds for assumed role credentials (default: 3600).
    - `session_name_claim` string — SessionNameClaim is the JWT claim to use for role session name (default: "sub").
    - `subject_provider_name` string — SubjectProviderName identifies which upstream provider's access token to use for STS AssumeRoleWithWebIdentity. Used by vMCP only. When empty, the bearer token from the incoming HTTP request is used.
  - `base_name` string — BaseName is the base name used for the container (without prefixes)
  - `cmd_args` string[] — CmdArgs are the arguments to pass to the container
  - `container_labels` object — ContainerLabels are the labels to apply to the container
  - `container_name` string — ContainerName is the name of the container
  - `debug` boolean — Debug indicates whether debug mode is enabled
  - `embedded_auth_server_config` AuthserverRunConfig — EmbeddedAuthServerConfig contains configuration for the embedded OAuth2/OIDC authorization server. When set, the proxy runner will start an embedded auth server that delegates to upstream IDPs. This is the serializable RunConfig; secrets are referenced by file paths or env var names.
    - `allow_confidential_client_registration` boolean — AllowConfidentialClientRegistration permits Dynamic Client Registration of confidential clients: when true, /oauth/register accepts token_endpoint_auth_method values client_secret_basic and client_secret_post in addition to "none" (still the default on omission) and mints a client_secret returned exactly once. Confidential clients are restricted to https non-loopback redirect URIs, and registrations idle for more than DefaultDCRClientTTL (30 days) are evicted and must re-register. This gates registration only: disabling it does not revoke or reject already-minted secrets at the token endpoint. Security: /oauth/register is unauthenticated, so this issues client secrets to any caller. Combining it with InsecureAllowHTTP is rejected by Validate.
    - `allow_private_key_jwt_registration` boolean — AllowPrivateKeyJWTRegistration permits Dynamic Client Registration of clients using private_key_jwt authentication. This is independent of AllowConfidentialClientRegistration and defaults to false. Registration behavior is controlled independently by the DCR handler and discovery metadata. Security: /oauth/register is unauthenticated. Unlike AllowConfidentialClientRegistration, this is NOT rejected when combined with InsecureAllowHTTP: registration never returns a secret for a private_key_jwt client, so there is nothing for cleartext HTTP to expose.
    - `allowed_audiences` string[] — AllowedAudiences is the list of valid resource URIs that tokens can be issued for. Per RFC 8707, the "resource" parameter in authorization and token requests is validated against this list. Required for MCP compliance.
    - `authorization_endpoint_base_url` string — AuthorizationEndpointBaseURL overrides the base URL used for the authorization_endpoint in the OAuth discovery document. When set, the discovery document will advertise `{authorization_endpoint_base_url}/oauth/authorize` instead of `{issuer}/oauth/authorize`. All other endpoints remain derived from the issuer.
    - `baseline_client_scopes` string[] — BaselineClientScopes is a baseline set of OAuth 2.0 scopes unioned into every DCR registration. All values must appear in ScopesSupported; the auth server rejects this RunConfig at startup otherwise. Empty means current behavior is preserved (registered scope = client-requested, or DefaultScopes if empty). When ScopesSupported is empty, the subset check uses registration.DefaultScopes (the same set applyDefaults would substitute at startup) — so BaselineClientScopes containing standard OIDC scopes works without enumerating ScopesSupported explicitly.
    - `cimd` AuthserverCIMDRunConfig — CIMD controls client_id metadata document support. When enabled, the embedded authorization server accepts HTTPS URLs as client_id values and resolves them via the CIMD protocol instead of requiring DCR.
      - `cache_fallback_ttl` string — CacheFallbackTTL is the fixed TTL applied to every cached CIMD document. Cache-Control header parsing is not yet implemented; all entries use this value. Format: Go duration string (e.g. "5m", "10m", "1h"). Defaults to 5 minutes when Enabled is true and this field is omitted.
      - `cache_max_size` integer — CacheMaxSize is the maximum number of CIMD documents held in the LRU cache. Defaults to 256 when Enabled is true and this field is zero.
      - `enabled` boolean — Enabled activates CIMD client lookup when true.
    - `delegate_clients` AuthserverDelegateClientRunConfig[] — DelegateClients declares confidential OAuth clients to register at authorization-server startup, including clients intended for RFC 8693 token exchange. Independent of AllowConfidentialClientRegistration: declaring a client here does not require or enable self-service confidential DCR, and setting that flag does not declare or enable any client here. They govern different endpoints — this field is static configuration the operator controls directly, while the flag is admission policy for the unauthenticated /oauth/register endpoint. See DelegateClientRunConfig for the per-client field reference.
      - `audiences` string[] — Audiences are the RFC 8707 resource values this client may request a token for. Required, and must be a subset of RunConfig.AllowedAudiences: a declared client must not receive every allowed audience just because this was left empty.
      - `client_id` string — ClientID is the OAuth client_id this client presents at the token endpoint.
      - `client_secret_env_var` string — ClientSecretEnvVar is the name of an environment variable containing the client secret. One of ClientSecretFile or ClientSecretEnvVar is required.
      - `client_secret_file` string — ClientSecretFile is the path to a file containing the client secret. If both this and ClientSecretEnvVar are set, the file takes precedence.
      - `scopes` string[] — Scopes are the OAuth scopes this client may request. Required, and must be a subset of RunConfig.ScopesSupported: a declared client must not receive every supported scope just because this was left empty.
    - `delegation_token_lifespan` string — DelegationTokenLifespan is the maximum lifetime for delegated tokens issued via RFC 8693 token exchange. Specified as a Go duration string (e.g., "15m"). If empty, defaults to 15 minutes.
    - `disable_upstream_token_injection` boolean — DisableUpstreamTokenInjection prevents the upstream swap middleware from being added. When true, the embedded auth server handles OAuth flows for clients, but instead of injecting upstream IdP tokens the proxy strips the client's credential headers (Authorization, Cookie, Proxy-Authorization) after the JWT is validated — the backend receives an unauthenticated request. Incompatible with token exchange and AWS STS, which would re-add credentials after the strip.
    - `force_confidential_redirect_uris` string[] — ForceConfidentialRedirectURIs lists redirect URIs that must be registered as confidential clients regardless of the token_endpoint_auth_method the DCR request declares. A registration whose redirect_uris contains an EXACT match for one of these entries is issued a real client_secret and reported back as token_endpoint_auth_method "client_secret_post", even if the request said "none" or omitted the field. This exists for MCP clients (Perplexity is the known case) that declare themselves public (token_endpoint_auth_method: "none") per RFC 7591 but then refuse to proceed because the response carries no client_secret — a self-contradictory request no conformant server can satisfy as written. RFC 7591 §3.2.1 permits the server to substitute metadata, so this takes such a client at its word that it wants a secret. Exact matching is deliberate: it is not a way to obtain a usable credential for another client. An attacker who registers with someone else's callback URI is issued a secret for a client whose authorization codes are delivered to that someone else's redirect endpoint, not to the attacker — the secret is useless without also controlling the callback. Requires AllowConfidentialClientRegistration; every entry must be a valid https non-loopback URI (Validate rejects loopback entries — the same restriction AllowConfidentialClientRegistration itself enforces exists so secrets do not land in distributed native apps, and this override must not bypass it). Remove an entry once the client is fixed to handle "none" registrations correctly.
    - `hmac_secret_files` string[] — HMACSecretFiles contains file paths to HMAC secrets for signing authorization codes and refresh tokens (opaque tokens). First file is the current secret (must be at least 32 bytes), subsequent files are for rotation/verification of existing tokens. If empty, an ephemeral secret will be auto-generated (development only).
    - `insecure_allow_confidential_over_loopback_http` boolean — InsecureAllowConfidentialOverLoopbackHTTP opts in to confidential clients when Issuer is a plain-HTTP loopback URL. Without this flag, that combination is rejected: a loopback http:// issuer is normally fine for local development (the traffic never leaves the machine), but client secrets would otherwise travel over cleartext. Defaults to false. Has no effect when there are no confidential clients or Issuer is https. Applies identically to delegate clients and DCR-registered clients. The Kubernetes CRD requires the explicit opt-in for a delegate client with an HTTP issuer; the shared transport validator enforces that its host is loopback — see EmbeddedAuthServerConfig's doc comment. private_key_jwt registration has no equivalent flag or transport restriction: unlike confidential registration, it never returns a client_secret (or any other secret) in the DCR response, so there is nothing here for cleartext HTTP to expose.
    - `insecure_allow_http` boolean — InsecureAllowHTTP permits an http:// issuer URL for non-localhost hosts. Only set this for in-cluster Kubernetes deployments on a trusted network. Production deployments reachable outside the cluster MUST use https://.
    - `issuer` string — Issuer is the issuer identifier for this authorization server. This will be included in the "iss" claim of issued tokens. Must be a valid HTTPS URL (or HTTP for localhost) without query, fragment, or trailing slash.
    - `schema_version` string — SchemaVersion is the version of the RunConfig schema.
    - `scopes_supported` string[] — ScopesSupported lists the OAuth 2.0 scope values advertised in discovery documents. If empty, defaults to registration.DefaultScopes (["openid", "profile", "email", "offline_access"]).
    - `signing_key_config` AuthserverSigningKeyRunConfig — SigningKeyConfig configures the signing key provider for JWT operations. If nil or empty, an ephemeral signing key will be auto-generated (development only).
      - `fallback_key_files` string[] — FallbackKeyFiles are filenames of additional keys for verification (relative to KeyDir). These keys are included in the JWKS endpoint for token verification but are NOT used for signing new tokens. Useful for key rotation.
      - `key_dir` string — KeyDir is the directory containing PEM-encoded private key files. All key filenames are relative to this directory. In Kubernetes, this is typically a mounted Secret volume.
      - `signing_key_file` string — SigningKeyFile is the filename of the primary signing key (relative to KeyDir). This key is used for signing new tokens.
    - `storage` StorageRunConfig — Storage configures the storage backend for the auth server. If nil, defaults to in-memory storage.
      - `redis_config` StorageRedisRunConfig — RedisConfig is the Redis-specific configuration when Type is "redis".
        - `acl_user_config` StorageACLUserRunConfig — ACLUserConfig contains ACL user authentication configuration.
          - `password_env_var` string — PasswordEnvVar is the environment variable containing the Redis password.
          - `username_env_var` string — UsernameEnvVar is the environment variable containing the Redis username.
        - `addr` string — Addr is the Redis server address (host:port). Required for standalone and cluster modes. Mutually exclusive with SentinelConfig.
        - `auth_type` string — AuthType must be "aclUser" - only ACL user authentication is supported.
        - `cluster_mode` boolean — ClusterMode enables the Redis Cluster protocol. Requires Addr to be set.
        - `dial_timeout` string — DialTimeout is the timeout for establishing connections (e.g., "5s").
        - `key_prefix` string — KeyPrefix for multi-tenancy, typically "thv:auth:{ns}:{name}:".
        - `read_timeout` string — ReadTimeout is the timeout for read operations (e.g., "3s").
        - `sentinel_config` StorageSentinelRunConfig — SentinelConfig contains Sentinel-specific configuration. Mutually exclusive with Addr.
          - `db` integer — DB is the Redis database number (default: 0).
          - `master_name` string — MasterName is the name of the Redis Sentinel master.
          - `sentinel_addrs` string[] — SentinelAddrs is the list of Sentinel addresses (host:port).
        - `sentinel_tls` StorageRedisTLSRunConfig — SentinelTLS configures TLS for Sentinel connections. Only applies when SentinelConfig is set.
          - `ca_cert_file` string — CACertFile is the path to a PEM-encoded CA certificate file.
          - `insecure_skip_verify` boolean — InsecureSkipVerify skips certificate verification.
        - `tls` StorageRedisTLSRunConfig — SentinelTLS configures TLS for Sentinel connections. Only applies when SentinelConfig is set.
          - `ca_cert_file` string — CACertFile is the path to a PEM-encoded CA certificate file.
          - `insecure_skip_verify` boolean — InsecureSkipVerify skips certificate verification.
        - `write_timeout` string — WriteTimeout is the timeout for write operations (e.g., "3s").
      - `type` string — Type specifies the storage backend type. Defaults to "memory".
    - `token_lifespans` AuthserverTokenLifespanRunConfig — TokenLifespans configures the duration that various tokens are valid. If nil, defaults are applied (access: 1h, refresh: 7d, authCode: 10m).
      - `access_token_lifespan` string — AccessTokenLifespan is the duration that access tokens are valid. If empty, defaults to 1 hour.
      - `auth_code_lifespan` string — AuthCodeLifespan is the duration that authorization codes are valid. If empty, defaults to 10 minutes.
      - `refresh_token_lifespan` string — RefreshTokenLifespan is the duration that refresh tokens are valid. If empty, defaults to 7 days (168h).
    - `trusted_issuers` TokenexchangeTrustedIssuer[] — TrustedIssuers lists external OIDC issuers whose tokens are accepted as RFC 8693 subject tokens or RFC 7523 JWT-bearer assertions. Issuers with jwtBearerGrant enabled may be used for the JWT-bearer grant without an RFC 8693 delegation policy. Empty (the default) means only self-issued subject tokens are accepted. See tokenexchange.TrustedIssuer for the per-issuer field reference, and docs/arch/17-token-exchange-delegation.md for the trust model, consent signals, and operator-facing constraints (audience/scope bounding, subject namespace qualification, required client binding) that aren't visible from the config shape alone.
      - `actor_claim` string — ActorClaim names the claim identifying the client that requested the subject token from THIS EXTERNAL ISSUER (used by AllowedActors below). Values are in the external issuer's namespace, NOT ToolHive client IDs. Defaults to "azp"; use "appid" for Microsoft Entra v1, "cid" for Okta. The special value "client_id" reads ValidatedClaims.ClientID instead of Extra (assignClaim routes it to that field) — it is still the external token's client_id claim, not a ToolHive one.
      - `actor_matcher` string — ActorMatcher is an admin-authored CEL expression evaluated against the complete signature-verified JWT claims map as "claims". A true result authorizes delegation alongside AllowedActors; a syntax or type error fails configuration validation. An expression that compiles but does not return bool is NOT caught at that point, though — it compiles successfully and is only rejected the first time it is evaluated against a real token, denying that token (and every one after it, since the expression will never return bool). Any other runtime evaluation error denies the token the same way.
      - `allow_may_act` boolean — AllowMayAct permits this external issuer's may_act claim to authorize delegation. It defaults to false; external issuers must be opted in explicitly because may_act bypasses AllowedActors and ActorMatcher. It does not affect self-issued subject tokens. When enabled, AllowedDelegateClients must name specific ToolHive clients rather than use the wildcard.
      - `allow_private_ips` boolean — AllowPrivateIPs permits OIDC discovery and JWKS fetches for THIS issuer to resolve to a private or loopback address. Use only when the issuer is hosted inside the same cluster and has no public endpoint.
      - `allowed_actors` string[] — AllowedActors is the allowlist of ActorClaim values authorized to exchange a subject token from this issuer when it carries no "may_act" claim. ActorMatcher can additionally authorize a token by matching its complete verified claims map; either signal is sufficient. When both are empty, only may_act-bearing tokens are accepted, and only if AllowMayAct is also true for this issuer. By itself names no ToolHive client — see AllowedDelegateClients and docs/arch/17-token-exchange-delegation.md ("Accepted limitations" #1).
      - `allowed_delegate_clients` string[] — AllowedDelegateClients restricts which ToolHive client IDs may exchange a subject token from this issuer, for BOTH consent paths. Required (validateTrustedIssuer rejects empty/absent); "*" permits any confidential client holding the grant. See docs/arch/17-token-exchange-delegation.md ("Accepted limitations" #1).
      - `expected_audience` string — ExpectedAudience is the expected "aud" claim value that must appear in an RFC 8693 subject token's audience list (a resource/API identifier, not a client ID — required for delegation unless JWTBearerGrant is configured; see looksLikeResourceIdentifier). RFC 7523 assertions use the token endpoint as their audience instead. See docs/arch/17-token-exchange-delegation.md ("ID/access-token discrimination") for why and its limits.
      - `insecure_allow_http` boolean — InsecureAllowHTTP permits plain-HTTP OIDC discovery and JWKS fetches for THIS issuer only. Development and testing only — never set in production. Does not relax the private-IP guard; see AllowPrivateIPs. Deliberately per-issuer: this server's own InsecureAllowHTTP must not silently permit plaintext discovery for every trusted external issuer too — a network attacker who can intercept that traffic could substitute a JWKS and forge subject tokens for that issuer's namespace.
      - `issuer_url` string — IssuerURL is the expected "iss" claim value (exact match).
      - `jwks_url` string — JWKSURL is the URL to fetch the issuer's JSON Web Key Set from. If empty, it is resolved via OIDC discovery at {IssuerURL}/.well-known/openid-configuration.
      - `jwt_bearer_grant` TokenexchangeJWTBearerGrantPolicy — JWTBearerGrant optionally enables the plain RFC 7523 JWT-bearer grant. It accepts assertions from this issuer without client authentication and limits their maximum age, subjects, and RFC 8707 resources. It is independent from RFC 8693 delegation policy.
        - `accepted_audiences` string[] — AcceptedAudiences is the set of "this AS" identity strings an assertion's "aud" claim must intersect — e.g. to support migrating this server's issuer/token-endpoint URL, or exposing it under more than one valid name. Each value uniquely identifies this authorization server for this grant; it is NOT a resource/API identifier — a bare resource audience is deliberately not accepted here, that would let any RFC 8707 resource-scoped token satisfy the grant instead of only tokens minted for this AS. Defaults to [tokenEndpoint] when empty, preserving prior exact-match behavior.
        - `max_assertion_age` string
        - `subject_bindings` TokenexchangeJWTBearerSubjectBinding[]
          - `allowed_resources` string[]
          - `subject` string
    - `upstreams` AuthserverUpstreamRunConfig[] — Upstreams configures connections to upstream Identity Providers. At least one upstream is required - the server delegates authentication to these providers. Multiple upstreams are supported for sequential authorization chains.
      - `name` string — Name uniquely identifies this upstream. Used for routing decisions and session binding in multi-upstream scenarios. If empty when only one upstream is configured, defaults to "default".
      - `oauth2_config` AuthserverOAuth2UpstreamRunConfig — OAuth2Config contains OAuth 2.0-specific configuration. Required when Type is "oauth2", must be nil when Type is "oidc".
        - `additional_authorization_params` object — AdditionalAuthorizationParams are extra query parameters to include in authorization requests. Useful for provider-specific parameters like Google's access_type=offline.
        - `allow_private_ips` boolean — AllowPrivateIPs permits the upstream provider's HTTP client to connect to private IP ranges (RFC-1918, link-local). When DCRConfig is set, this also gates the DCR discovery and registration calls made on this upstream's behalf (see pkg/authserver/runner/dcr_adapter.go), so a single flag covers the whole upstream rather than needing a separate DCR-specific setting. Use only when the upstream is hosted inside the same cluster and has no public endpoint. HTTP-scheme restrictions are unchanged — HTTPS is still required for non-localhost hosts. Defaults to false.
        - `authorization_endpoint` string — AuthorizationEndpoint is the URL for the OAuth authorization endpoint.
        - `ca_file_path` string — CAFilePath is the path to a PEM CA bundle added to the system roots.
        - `client_id` string — ClientID is the OAuth 2.0 client identifier registered with the upstream IDP. Mutually exclusive with DCRConfig: when DCRConfig is set, ClientID is obtained at runtime via RFC 7591 Dynamic Client Registration and must be left empty.
        - `client_secret_env_var` string — ClientSecretEnvVar is the name of an environment variable containing the client secret. Mutually exclusive with ClientSecretFile. Optional for public clients using PKCE.
        - `client_secret_file` string — ClientSecretFile is the path to a file containing the OAuth 2.0 client secret. Mutually exclusive with ClientSecretEnvVar. Optional for public clients using PKCE.
        - `dcr_config` AuthserverDCRUpstreamConfig — 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 via ClientID / ClientSecretFile / ClientSecretEnvVar, and ClientID must be left empty. Mutually exclusive with ClientID.
          - `discovery_url` string — DiscoveryURL is the exact RFC 8414 / OIDC Discovery document URL to fetch at runtime. 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. Per RFC 8414 §3.3, the document's "issuer" field must exactly match the upstream issuer configured on the parent run-config. Use this field when the upstream publishes discovery metadata at a path that differs from the issuer-derived well-known paths — for example a multi-tenant IdP whose metadata lives at https://idp.example.com/tenants/acme/.well-known/openid-configuration. Mutually exclusive with RegistrationEndpoint.
          - `initial_access_token_env_var` string — InitialAccessTokenEnvVar is the name of an environment variable containing the RFC 7591 initial access token. Mutually exclusive with InitialAccessTokenFile.
          - `initial_access_token_file` string — InitialAccessTokenFile is the path to a file containing the RFC 7591 initial access token presented to the registration endpoint. Mutually exclusive with InitialAccessTokenEnvVar. Both may be omitted for open registration endpoints.
          - `registration_endpoint` string — RegistrationEndpoint is the RFC 7591 registration endpoint URL used directly, bypassing discovery. Because no discovery is performed, server-capability fields (token_endpoint_auth_methods_supported, scopes_supported) are unavailable on this code path; the caller is expected to also supply AuthorizationEndpoint, TokenEndpoint, and an explicit Scopes list on the parent OAuth2UpstreamRunConfig. Auth method falls back to the resolver's default (client_secret_basic). Mutually exclusive with DiscoveryURL.
          - `software_id` string — SoftwareID is the RFC 7591 "software_id" registration metadata value, identifying the client software independent of any particular registration instance.
          - `software_statement` string — SoftwareStatement is the RFC 7591 "software_statement" JWT asserting metadata about the client software, signed by a party the authorization server trusts.
        - `identity_from_token` AuthserverIdentityFromTokenRunConfig — 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. Mirrors the CRD type (cmd/thv-operator/api/v1beta1.IdentityFromTokenConfig) — the authoritative trust-model and uniqueness documentation lives there.
          - `email_path` string — EmailPath is the dot-notation path to the email address field.
          - `name_path` string — NamePath is the dot-notation path to the display name field.
          - `subject_path` string — SubjectPath is the dot-notation path to the subject (user ID) field. Required when IdentityFromToken is set.
        - `insecure_allow_http` boolean — InsecureAllowHTTP permits plain-HTTP authorization and token endpoint URLs for this upstream. Only for in-cluster development environments (e.g. an OAuth2 provider served over HTTP in a kind cluster) where TLS is not available. Never set this in production.
        - `redirect_uri` string — RedirectURI is the callback URL where the upstream IDP will redirect after authentication. When not specified, defaults to `{issuer}/oauth/callback`.
        - `scopes` string[] — Scopes are the OAuth scopes to request from the upstream IDP.
        - `token_endpoint` string — TokenEndpoint is the URL for the OAuth token endpoint.
        - `token_response_mapping` AuthserverTokenResponseMappingRunConfig — TokenResponseMapping configures custom field extraction from non-standard token responses. When set, the token exchange bypasses golang.org/x/oauth2 and extracts fields using the configured dot-notation paths.
          - `access_token_path` string — AccessTokenPath is the dot-notation path to the access token (required).
          - `expires_in_path` string — ExpiresInPath is the dot-notation path to the expires_in value. Defaults to "expires_in".
          - `refresh_token_path` string — RefreshTokenPath is the dot-notation path to the refresh token. Defaults to "refresh_token".
          - `scope_path` string — ScopePath is the dot-notation path to the scope. Defaults to "scope".
        - `userinfo` AuthserverUserInfoRunConfig — UserInfo contains configuration for fetching user information. Optional: when nil, the upstream OAuth2 provider derives a deterministic subject by SHA-256-hashing the access token (with a "tk-" prefix) instead of calling a userinfo endpoint. OIDC providers always derive Subject from the ID token and are unaffected.
          - `additional_headers` object — AdditionalHeaders contains extra headers to include in the userinfo request. Useful for providers that require specific headers (e.g., GitHub's Accept header).
          - `endpoint_url` string — EndpointURL is the URL of the userinfo endpoint.
          - `field_mapping` AuthserverUserInfoFieldMappingRunConfig — FieldMapping contains custom field mapping configuration for non-standard providers. If nil, standard OIDC field names are used ("sub", "name", "email").
            - `email_fields` string[] — EmailFields is an ordered list of field names to try for the email address. The first non-empty value found will be used. Default: ["email"]
            - `name_fields` string[] — NameFields is an ordered list of field names to try for the display name. The first non-empty value found will be used. Default: ["name"]
            - `subject_fields` string[] — SubjectFields is an ordered list of field names to try for the user ID. The first non-empty value found will be used. Default: ["sub"]
          - `http_method` string — HTTPMethod is the HTTP method to use for the userinfo request. If not specified, defaults to GET.
      - `oidc_config` AuthserverOIDCUpstreamRunConfig — OIDCConfig contains OIDC-specific configuration. Required when Type is "oidc", must be nil when Type is "oauth2".
        - `additional_authorization_params` object — AdditionalAuthorizationParams are extra query parameters to include in authorization requests. Useful for provider-specific parameters like Google's access_type=offline.
        - `allow_private_ips` boolean — AllowPrivateIPs permits the OIDC discovery and token HTTP clients to connect to private IP ranges (RFC-1918, link-local). Use only when the upstream is hosted inside the same cluster and has no public endpoint. HTTP-scheme restrictions are unchanged — HTTPS is still required for non-localhost hosts. Defaults to false.
        - `ca_file_path` string — CAFilePath is the path to a PEM CA bundle added to the system roots.
        - `client_id` string — ClientID is the OAuth 2.0 client identifier registered with the upstream IDP.
        - `client_secret_env_var` string — ClientSecretEnvVar is the name of an environment variable containing the client secret. Mutually exclusive with ClientSecretFile. Optional for public clients using PKCE.
        - `client_secret_file` string — ClientSecretFile is the path to a file containing the OAuth 2.0 client secret. Mutually exclusive with ClientSecretEnvVar. Optional for public clients using PKCE.
        - `insecure_allow_http` boolean — InsecureAllowHTTP permits a plain-HTTP issuer URL and HTTP discovery endpoints for this upstream. Only for in-cluster development environments (e.g. Dex served over HTTP in a kind cluster) where TLS is not available. Never set this in production.
        - `issuer_url` string — IssuerURL is the OIDC issuer URL for automatic endpoint discovery. Must be a valid HTTPS URL.
        - `redirect_uri` string — RedirectURI is the callback URL where the upstream IDP will redirect after authentication. When not specified, defaults to `{issuer}/oauth/callback`.
        - `scopes` string[] — Scopes are the OAuth scopes to request from the upstream IDP. If not specified, defaults to ["openid", "offline_access"]. When using AdditionalAuthorizationParams with provider-specific refresh token mechanisms (e.g., Google's access_type=offline), set explicit scopes to avoid sending both offline_access and the provider-specific parameter.
        - `subject_claim` string — SubjectClaim names the validated ID-token claim to use as the upstream subject. Defaults to "sub" when empty. Set for IdPs where "sub" isn't stable per user (e.g. Entra/Azure AD's "oid"). See upstream.OIDCConfig.
        - `userinfo_override` AuthserverUserInfoRunConfig — UserInfo contains configuration for fetching user information. Optional: when nil, the upstream OAuth2 provider derives a deterministic subject by SHA-256-hashing the access token (with a "tk-" prefix) instead of calling a userinfo endpoint. OIDC providers always derive Subject from the ID token and are unaffected.
          - `additional_headers` object — AdditionalHeaders contains extra headers to include in the userinfo request. Useful for providers that require specific headers (e.g., GitHub's Accept header).
          - `endpoint_url` string — EndpointURL is the URL of the userinfo endpoint.
          - `field_mapping` AuthserverUserInfoFieldMappingRunConfig — FieldMapping contains custom field mapping configuration for non-standard providers. If nil, standard OIDC field names are used ("sub", "name", "email").
            - `email_fields` string[] — EmailFields is an ordered list of field names to try for the email address. The first non-empty value found will be used. Default: ["email"]
            - `name_fields` string[] — NameFields is an ordered list of field names to try for the display name. The first non-empty value found will be used. Default: ["name"]
            - `subject_fields` string[] — SubjectFields is an ordered list of field names to try for the user ID. The first non-empty value found will be used. Default: ["sub"]
          - `http_method` string — HTTPMethod is the HTTP method to use for the userinfo request. If not specified, defaults to GET.
      - `type` string — Type specifies the provider type: "oidc" or "oauth2".
  - `endpoint_prefix` string — EndpointPrefix is an explicit prefix to prepend to SSE endpoint URLs. This is used to handle path-based ingress routing scenarios.
  - `env_file_dir` string — DEPRECATED: No longer appears to be used. EnvFileDir is the directory path to load environment files from
  - `env_vars` object — EnvVars are the parsed environment variables as key-value pairs
  - `group` string — Group is the name of the group this workload belongs to, if any
  - `header_forward` GithubComStacklokToolhivePkgRunnerHeaderForwardConfig — HeaderForward contains configuration for injecting headers into requests to remote servers.
    - `add_headers_from_secret` object — AddHeadersFromSecret is a map of header names to secret names. The key is the header name, the value is the secret name in ToolHive's secrets manager. Resolved at runtime via WithSecrets() into resolvedHeaders. The actual secret value is only held in memory, never persisted.
    - `add_plaintext_headers` object — AddPlaintextHeaders is a map of header names to literal values to inject into requests. WARNING: These values are stored in plaintext in the configuration. For sensitive values (API keys, tokens), use AddHeadersFromSecret instead.
  - `host` string — Host is the host for the HTTP proxy
  - `ignore_config` IgnoreConfig — IgnoreConfig contains configuration for ignore processing
    - `loadGlobal` boolean — Whether to load global ignore patterns
    - `printOverlays` boolean — Whether to print resolved overlay paths for debugging
  - `image` string — Image is the Docker image to run
  - `isolate_network` boolean — IsolateNetwork indicates whether to isolate the network for the container
  - `jwks_auth_token_file` string — DEPRECATED: No longer appears to be used. JWKSAuthTokenFile is the path to file containing auth token for JWKS/OIDC requests
  - `k8s_pod_template_patch` string — K8sPodTemplatePatch is a JSON string to patch the Kubernetes pod template Only applicable when using Kubernetes runtime
  - `mcpserver_generation` integer — MCPServerGeneration is the K8s .metadata.generation of the MCPServer CR that rendered this RunConfig. The Kubernetes runtime uses it as a monotonic version to prevent stale rolling-update pods from overwriting a newer RunConfig's StatefulSet apply. Zero value means unversioned (backward-compat with older operators, or non-operator callers).
  - `middleware_configs` TypesMiddlewareConfig[] — MiddlewareConfigs contains the list of middleware to apply to the transport and the configuration for each middleware.
    - `parameters` object — Parameters is a JSON object containing the middleware parameters. It is stored as a raw message to allow flexible parameter types.
    - `type` string — Type is a string representing the middleware type.
  - `mutating_webhooks` GithubComStacklokToolhivePkgWebhookConfig[] — MutatingWebhooks contains the configuration for mutating webhook middleware. Mutating webhooks run before validating webhooks, per RFC THV-0017 ordering.
    - `failure_policy` 'fail' | 'ignore' — FailurePolicy determines behavior when the webhook call fails.
    - `hmac_secret_ref` string — HMACSecretRef is an optional reference to an HMAC secret for payload signing.
    - `name` string — Name is a unique identifier for this webhook.
    - `timeout` integer — Timeout is the maximum time to wait for a webhook response.
    - `tls_config` GithubComStacklokToolhivePkgWebhookTLSConfig — TLSConfig holds optional TLS configuration (CA bundles, client certs).
      - `ca_bundle_path` string — CABundlePath is the path to a CA certificate bundle for server verification.
      - `client_cert_path` string — ClientCertPath is the path to a client certificate for mTLS.
      - `client_key_path` string — ClientKeyPath is the path to a client key for mTLS.
      - `insecure_skip_verify` boolean — InsecureSkipVerify disables server certificate verification. WARNING: This should only be used for development/testing.
    - `url` string — URL is the HTTPS endpoint to call.
  - `name` string — Name is the name of the MCP server
  - `oidc_config` AuthTokenValidatorConfig — DEPRECATED: Middleware configuration. OIDCConfig contains OIDC configuration
    - `allowPrivateIP` boolean — AllowPrivateIP allows JWKS/OIDC endpoints on private IP addresses
    - `audience` string — Audience is the expected audience for the token
    - `authTokenFile` string — AuthTokenFile is the path to file containing bearer token for authentication
    - `cacertPath` string — CACertPath is the path to the CA certificate bundle for HTTPS requests
    - `clientID` string — ClientID is the OIDC client ID
    - `clientSecret` string — ClientSecret is the optional OIDC client secret for introspection
    - `insecureAllowHTTP` boolean — InsecureAllowHTTP allows HTTP (non-HTTPS) OIDC issuers for development/testing WARNING: This is insecure and should NEVER be used in production
    - `introspectionURL` string — IntrospectionURL is the optional introspection endpoint for validating tokens
    - `issuer` string — Issuer is the OIDC issuer URL (e.g., https://accounts.google.com)
    - `jwksurl` string — JWKSURL is the URL to fetch the JWKS from
    - `resourceURL` string — ResourceURL is the explicit resource URL for OAuth discovery (RFC 9728)
    - `scopes` string[] — Scopes is the list of OAuth scopes to advertise in the well-known endpoint (RFC 9728) If empty, defaults to ["openid"]
  - `permission_profile_name_or_path` string — PermissionProfileNameOrPath is the name or path of the permission profile
  - `port` integer — Port is the port for the HTTP proxy to listen on (host port)
  - `proxy_mode` 'sse' | 'streamable-http' — ProxyMode is the effective HTTP protocol the proxy uses. For stdio transports, this is the configured mode (sse or streamable-http). For direct transports (sse/streamable-http), this matches the transport type. Note: "sse" is deprecated; use "streamable-http" instead.
  - `publish` string[] — Publish lists ports to publish to the host in format "hostPort:containerPort"
  - `rate_limit_config` V1beta1RateLimitConfig — RateLimitConfig contains the CRD rate limiting configuration. When set, rate limiting middleware is added to the proxy middleware chain.
    - `perUser` TypesRateLimitBucket — PerUser token bucket configuration for this tool. +optional
      - `maxTokens` integer — MaxTokens is the maximum number of tokens (bucket capacity). This is also the burst size: the maximum number of requests that can be served instantaneously before the bucket is depleted. +kubebuilder:validation:Required +kubebuilder:validation:Minimum=1
      - `refillPeriod` V1Duration — 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"). +kubebuilder:validation:Required
    - `shared` TypesRateLimitBucket — PerUser token bucket configuration for this tool. +optional
      - `maxTokens` integer — MaxTokens is the maximum number of tokens (bucket capacity). This is also the burst size: the maximum number of requests that can be served instantaneously before the bucket is depleted. +kubebuilder:validation:Required +kubebuilder:validation:Minimum=1
      - `refillPeriod` V1Duration — 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"). +kubebuilder:validation:Required
    - `tools` TypesToolRateLimitConfig[] — 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. +listType=map +listMapKey=name +optional
      - `name` string — Name is the MCP tool name this limit applies to. +kubebuilder:validation:Required +kubebuilder:validation:MinLength=1
      - `perUser` TypesRateLimitBucket — PerUser token bucket configuration for this tool. +optional
        - `maxTokens` integer — MaxTokens is the maximum number of tokens (bucket capacity). This is also the burst size: the maximum number of requests that can be served instantaneously before the bucket is depleted. +kubebuilder:validation:Required +kubebuilder:validation:Minimum=1
        - `refillPeriod` V1Duration — 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"). +kubebuilder:validation:Required
      - `shared` TypesRateLimitBucket — PerUser token bucket configuration for this tool. +optional
        - `maxTokens` integer — MaxTokens is the maximum number of tokens (bucket capacity). This is also the burst size: the maximum number of requests that can be served instantaneously before the bucket is depleted. +kubebuilder:validation:Required +kubebuilder:validation:Minimum=1
        - `refillPeriod` V1Duration — 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"). +kubebuilder:validation:Required
  - `rate_limit_namespace` string — RateLimitNamespace is the Kubernetes namespace for Redis key derivation.
  - `registry_api_url` string — RegistryAPIURL is the registry API URL that served this server's metadata. Empty when the server was not discovered via registry lookup.
  - `registry_server_name` string — RegistryServerName is the registry entry name used to look up this server's metadata. Empty when the server was not discovered via registry lookup.
  - `registry_url` string — RegistryURL is the registry URL that served this server's metadata. Empty when the server was not discovered via registry lookup.
  - `remote_auth_config` RemoteConfig — RemoteAuthConfig contains OAuth configuration for remote MCP servers
    - `authorize_url` string
    - `bearer_token` string — Bearer token configuration (alternative to OAuth)
    - `bearer_token_file` string
    - `cached_cimd_client_id` string — CachedCIMDClientID stores the CIMD metadata URL used as client_id when CIMD authentication was used. Kept separate from CachedClientID (which holds DCR-issued IDs) so the two can have independent lifecycles — DCR credential rotation clears CachedClientID without touching the stable CIMD URL. Read by resolveClientCredentials to send the correct client_id on token refresh.
    - `cached_client_id` string — Cached DCR client credentials for persistence across restarts. These are obtained during Dynamic Client Registration and needed to refresh tokens. ClientID is stored as plain text since it's public information.
    - `cached_client_secret_ref` string
    - `cached_dcr_callback_port` integer — CachedDCRCallbackPort is the callback port that was actually registered during DCR. It may differ from CallbackPort when the requested port was unavailable and a fallback port was selected.
    - `cached_refresh_token_ref` string — Cached OAuth token reference for persistence across restarts. The refresh token is stored securely in the secret manager, and this field contains the reference to retrieve it (e.g., "OAUTH_REFRESH_TOKEN_workload"). This enables session restoration without requiring a new browser-based login.
    - `cached_reg_client_uri` string — CachedRegClientURI is the registration_client_uri from the DCR response. This is the endpoint used for RFC 7592 client read/update/delete operations. Stored as plain text since it is not sensitive.
    - `cached_reg_token_ref` string — CachedRegTokenRef is a secret manager reference to the registration_access_token returned in the DCR response. Used for RFC 7592 client update operations. Stored as a secret reference since it's sensitive.
    - `cached_secret_expiry` string — ClientSecretExpiresAt indicates when the client secret expires (if provided by the DCR server). A zero value means the secret does not expire.
    - `cached_token_auth_method` string — CachedTokenEndpointAuthMethod is the auth method used for the token endpoint (e.g., "client_secret_basic", "none"). Persisted for RFC 7592 updates.
    - `cached_token_expiry` string
    - `callback_port` integer
    - `client_id` string
    - `client_secret` string
    - `client_secret_file` string
    - `issuer` string — OAuth endpoint configuration (from registry)
    - `oauth_params` object — OAuth parameters for server-specific customization
    - `resource` string — Resource is the OAuth 2.0 resource indicator (RFC 8707).
    - `scope_param_name` string — ScopeParamName overrides the query parameter name used to send scopes in the authorization URL. When empty, the standard "scope" parameter is used. Some providers require a non-standard name (e.g., Slack uses "user_scope").
    - `scopes` string[]
    - `skip_browser` boolean
    - `timeout` string
    - `token_url` string
    - `use_pkce` boolean
  - `remote_url` string — RemoteURL is the URL of the remote MCP server (if running remotely)
  - `runtime_config` TemplatesRuntimeConfig — RuntimeConfig allows overriding the default runtime configuration for this specific workload (base images and packages)
    - `additional_packages` string[] — AdditionalPackages lists extra packages to install in the builder and runtime stages. Examples for Alpine: ["git", "make", "gcc"] Examples for Debian: ["git", "build-essential"]
    - `build_with` string[] — BuildWith lists build-time dependency constraints, interpreted per package ecosystem. For uvx:// builds these are PEP 508 requirement specifiers passed to `uv tool install --with`, used to constrain transitive dependencies the package itself leaves unbounded (e.g. "mcp<2"). Ecosystems without constraint support (npx://, go://) reject a non-empty BuildWith at build time.
    - `builder_image` string — BuilderImage is the full image reference for the builder stage. An empty string signals "use the default for this transport type" during config merging. Examples: "golang:1.26-alpine", "node:24-alpine", "python:3.14-slim"
    - `runtime_env` object — RuntimeEnv contains environment variables to inject into the Dockerfile's final runtime stage. Unlike BuildEnv (pkg/container/templates.TemplateData.BuildEnv), which only affects the builder stage, these variables are baked into the shipped image and are present in the running container's process environment at startup. Use this for values a packaged MCP server reads at process start (e.g. feature flags, cache backend selection), not for build-time package manager configuration. Keys must be uppercase with underscores, values are validated for safety.
  - `scaling_config` GithubComStacklokToolhivePkgRunnerScalingConfig — ScalingConfig contains configuration for horizontal scaling of the proxy runner. Only applicable when running in Kubernetes with the ToolHive operator. When nil, no scaling configuration is applied (single-replica default behavior).
    - `backend_replicas` integer — BackendReplicas is the desired StatefulSet replica count for the proxy runner backend. When nil, replicas are unmanaged (preserving HPA or manual kubectl control). When set (including 0), the value is an explicit replica count.
    - `session_redis` GithubComStacklokToolhivePkgRunnerSessionRedisConfig — SessionRedis holds non-sensitive Redis connection parameters for distributed session storage. Populated only when MCPServer.spec.sessionStorage.provider == "redis". The Redis password is not included — it is injected as env var THV_SESSION_REDIS_PASSWORD. +optional
      - `address` string — Address is the Redis server address (host:port).
      - `db` integer — DB is the Redis database number.
      - `key_prefix` string — KeyPrefix is an optional prefix applied to all Redis keys used by ToolHive.
  - `schema_version` string — SchemaVersion is the version of the RunConfig schema
  - `secrets` string[] — Secrets are the secret parameters to pass to the container Format: "<secret name>,target=<target environment variable>"
  - `session_ttl` string — SessionTTL is the inactivity timeout for proxy sessions, expressed as a Go duration string (e.g. "30m", "2h", "168h"). Empty uses the transport default (2h). Negative durations and values that fail time.ParseDuration are rejected at runtime. String (not time.Duration) keeps the wire format unit-explicit: a time.Duration field serializes as nanoseconds in JSON.
  - `stateless` boolean — Stateless indicates the server only supports POST (no SSE/GET). When true, the proxy returns 405 for incoming GET requests and uses a POST-based health check instead of the default GET probe. Applies to both remote URLs and local container workloads.
  - `strict_protocol_validation` boolean — StrictProtocolValidation enables strict MCP-Protocol-Version validation on the streamable HTTP proxy: a request whose header names an unknown MCP revision is rejected with HTTP 400. Default false accepts any version string (an absent header is always accepted in either mode).
  - `target_host` string — TargetHost is the host to forward traffic to (only applicable to SSE transport)
  - `target_port` integer — TargetPort is the port for the container to expose (only applicable to SSE transport)
  - `telemetry_config` TelemetryConfig — DEPRECATED: Middleware configuration. TelemetryConfig contains the OpenTelemetry configuration
    - `caCertPath` string — CACertPath is the file path to a CA certificate bundle for the OTLP endpoint. When set, the OTLP exporters use this CA to verify the collector's TLS certificate instead of relying solely on the system CA pool. +optional
    - `customAttributes` object — CustomAttributes contains custom resource attributes to be added to all telemetry signals. These are parsed from CLI flags (--otel-custom-attributes) or environment variables (OTEL_RESOURCE_ATTRIBUTES) as key=value pairs. +optional
    - `enablePrometheusMetricsPath` boolean — EnablePrometheusMetricsPath controls whether to expose Prometheus-style /metrics endpoint. The metrics are served at /metrics on a dedicated diagnostics port rather than on the main transport port, so the endpoint can be restricted by port and is not routed alongside application traffic. The endpoint is unauthenticated either way. See PrometheusPort and pkg/diagnostics. This is separate from OTLP metrics which are sent to the Endpoint. +kubebuilder:default=false +optional
    - `endpoint` string — Endpoint is the OTLP endpoint URL +optional
    - `environmentVariables` string[] — EnvironmentVariables is a list of environment variable names that should be included in telemetry spans as attributes. Only variables in this list will be read from the host machine and included in spans for observability. Example: ["NODE_ENV", "DEPLOYMENT_ENV", "SERVICE_VERSION"] +optional
    - `headers` object — Headers contains authentication headers for the OTLP endpoint. +optional
    - `insecure` boolean — Insecure indicates whether to use HTTP instead of HTTPS for the OTLP endpoint. +kubebuilder:default=false +optional
    - `metricsEnabled` boolean — MetricsEnabled controls whether OTLP metrics are enabled. When false, OTLP metrics are not sent even if an endpoint is configured. This is independent of EnablePrometheusMetricsPath. +kubebuilder:default=false +optional
    - `metricsOnTransportPort` boolean — MetricsOnTransportPort controls whether /metrics is ALSO served on the main transport port, in addition to the diagnostics port. It exists to give deployments a migration window: while true, an existing scrape configuration aimed at the transport port keeps working, and a new one aimed at PrometheusPort works too, so a scraper can be moved and verified before the old location goes away. See https://github.com/stacklok/toolhive/issues/6384 for the removal timeline. +optional
    - `prometheusPort` integer — PrometheusPort is the port the Prometheus /metrics endpoint is served on when EnablePrometheusMetricsPath is true. It is deliberately not the main transport port, so that access can be restricted with a NetworkPolicy: NetworkPolicy matches on port, not on HTTP path, so a shared port makes "allow MCP traffic, deny metrics scraping" impossible to express. The endpoint itself is unauthenticated, so restricting who can reach this port is how it is protected. Zero selects the default diagnostics port (9464, the OpenTelemetry specification's Prometheus exporter default). If that port is taken the listener falls back to an available one and logs the resolved address. Do not route this port publicly. +optional
    - `samplingRate` string — SamplingRate is the trace sampling rate (0.0-1.0) as a string. Only used when TracingEnabled is true. Example: "0.05" for 5% sampling. +kubebuilder:default="0.05" +optional
    - `serviceName` string — ServiceName is the service name for telemetry. When omitted, defaults to the server name (e.g., VirtualMCPServer name). +optional
    - `serviceVersion` string — ServiceVersion is the service version for telemetry. When omitted, defaults to the ToolHive version. +optional
    - `tracingEnabled` boolean — TracingEnabled controls whether distributed tracing is enabled. When false, no tracer provider is created even if an endpoint is configured. +kubebuilder:default=false +optional
    - `useLegacyAttributes` boolean — UseLegacyAttributes controls whether legacy (pre-MCP OTEL semconv) attribute names are emitted alongside the new standard attribute names. When true, spans include both old and new attribute names for backward compatibility with existing dashboards. Currently defaults to true; this will change to false in a future release. +kubebuilder:default=true +optional
  - `thv_ca_bundle` string — DEPRECATED: No longer appears to be used. ThvCABundle is the path to the CA certificate bundle for ToolHive HTTP operations
  - `token_exchange_config` TokenexchangeConfig — TokenExchangeConfig contains token exchange configuration for external authentication
    - `audience` string — Audience is the target audience for the exchanged token
    - `client_id` string — ClientID is the OAuth 2.0 client identifier
    - `client_secret` string — ClientSecret is the OAuth 2.0 client secret
    - `external_token_header_name` string — ExternalTokenHeaderName is the name of the custom header to use when HeaderStrategy is "custom"
    - `header_strategy` string — HeaderStrategy determines how to inject the token Valid values: HeaderStrategyReplace (default), HeaderStrategyCustom
    - `scopes` string[] — Scopes is the list of scopes to request for the exchanged token
    - `subject_token_type` string — SubjectTokenType specifies the type of the subject token being exchanged. Common values: oauthproto.TokenTypeAccessToken (default), oauthproto.TokenTypeIDToken, oauthproto.TokenTypeJWT. If empty, defaults to oauthproto.TokenTypeAccessToken.
    - `token_url` string — TokenURL is the OAuth 2.0 token endpoint URL
  - `tools_filter` string[] — DEPRECATED: Middleware configuration. ToolsFilter is the list of tools to filter
  - `tools_override` object — DEPRECATED: Middleware configuration. ToolsOverride is a map from an actual tool to its overridden name and/or description
  - `transport` 'stdio' | 'sse' | 'streamable-http' | 'inspector' — Transport is the transport mode (stdio, sse, or streamable-http)
  - `trust_proxy_headers` boolean — TrustProxyHeaders indicates whether to trust X-Forwarded-* headers from reverse proxies
  - `upstream_swap_config` GithubComStacklokToolhivePkgAuthUpstreamswapConfig — UpstreamSwapConfig contains configuration for upstream token swap middleware. When set along with EmbeddedAuthServerConfig, this middleware exchanges ToolHive JWTs for upstream IdP tokens before forwarding requests to the MCP server.
    - `custom_header_name` string — CustomHeaderName is the header name when HeaderStrategy is "custom".
    - `header_strategy` string — HeaderStrategy determines how to inject the token: "replace" (default) or "custom".
    - `provider_name` string — ProviderName identifies which upstream provider's tokens to retrieve for injection. This is required and must match a configured upstream provider name.
  - `validating_webhooks` GithubComStacklokToolhivePkgWebhookConfig[] — ValidatingWebhooks contains the configuration for validating webhook middleware.
    - `failure_policy` 'fail' | 'ignore' — FailurePolicy determines behavior when the webhook call fails.
    - `hmac_secret_ref` string — HMACSecretRef is an optional reference to an HMAC secret for payload signing.
    - `name` string — Name is a unique identifier for this webhook.
    - `timeout` integer — Timeout is the maximum time to wait for a webhook response.
    - `tls_config` GithubComStacklokToolhivePkgWebhookTLSConfig — TLSConfig holds optional TLS configuration (CA bundles, client certs).
      - `ca_bundle_path` string — CABundlePath is the path to a CA certificate bundle for server verification.
      - `client_cert_path` string — ClientCertPath is the path to a client certificate for mTLS.
      - `client_key_path` string — ClientKeyPath is the path to a client key for mTLS.
      - `insecure_skip_verify` boolean — InsecureSkipVerify disables server certificate verification. WARNING: This should only be used for development/testing.
    - `url` string — URL is the HTTPS endpoint to call.
  - `volumes` string[] — Volumes are the directory mounts to pass to the container Format: "host-path:container-path[:ro]"

## Other responses

- `404` — Not Found

---

[API](https://skmtc.dev/stacklok/apis/toolhive-api.md) · [All operations](https://skmtc.dev/stacklok/apis/toolhive-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/stacklok/toolhive-api/revisions/e9f942effcda/schema)