From 66f676d62b1bc4c45c92c4076f0b0ff839e7a736 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Fri, 3 Apr 2026 16:55:39 +0000 Subject: [PATCH] Update ToolHive reference docs for v0.15.0 --- docs/toolhive/reference/cli/thv_serve.md | 33 +- docs/toolhive/reference/crd-spec.md | 409 ++++++++++++++++++++- static/api-specs/toolhive-api.yaml | 441 ++++++++++++----------- 3 files changed, 651 insertions(+), 232 deletions(-) diff --git a/docs/toolhive/reference/cli/thv_serve.md b/docs/toolhive/reference/cli/thv_serve.md index 14cf65f0..c4551426 100644 --- a/docs/toolhive/reference/cli/thv_serve.md +++ b/docs/toolhive/reference/cli/thv_serve.md @@ -24,21 +24,24 @@ thv serve [flags] ### Options ``` - --experimental-mcp EXPERIMENTAL: Enable embedded MCP server for controlling ToolHive - --experimental-mcp-host string EXPERIMENTAL: Host for the embedded MCP server (default "localhost") - --experimental-mcp-port string EXPERIMENTAL: Port for the embedded MCP server (default "4483") - -h, --help help for serve - --host string Host address to bind the server to (default "127.0.0.1") - --oidc-audience string Expected audience for the token - --oidc-client-id string OIDC client ID - --oidc-client-secret string OIDC client secret (optional, for introspection) - --oidc-introspection-url string URL for token introspection endpoint - --oidc-issuer string OIDC issuer URL (e.g., https://accounts.google.com) - --oidc-jwks-url string URL to fetch the JWKS from - --oidc-scopes strings OAuth scopes to advertise in the well-known endpoint (RFC 9728, defaults to 'openid' if not specified) - --openapi Enable OpenAPI documentation endpoints (/api/openapi.json and /api/doc) - --port int Port to bind the server to (default 8080) - --socket string UNIX socket path to bind the server to (overrides host and port if provided) + --experimental-mcp EXPERIMENTAL: Enable embedded MCP server for controlling ToolHive + --experimental-mcp-host string EXPERIMENTAL: Host for the embedded MCP server (default "localhost") + --experimental-mcp-port string EXPERIMENTAL: Port for the embedded MCP server (default "4483") + -h, --help help for serve + --host string Host address to bind the server to (default "127.0.0.1") + --oidc-audience string Expected audience for the token + --oidc-client-id string OIDC client ID + --oidc-client-secret string OIDC client secret (optional, for introspection) + --oidc-introspection-url string URL for token introspection endpoint + --oidc-issuer string OIDC issuer URL (e.g., https://accounts.google.com) + --oidc-jwks-url string URL to fetch the JWKS from + --oidc-scopes strings OAuth scopes to advertise in the well-known endpoint (RFC 9728, defaults to 'openid' if not specified) + --openapi Enable OpenAPI documentation endpoints (/api/openapi.json and /api/doc) + --port int Port to bind the server to (default 8080) + --sentry-dsn string Sentry DSN for error tracking and distributed tracing (falls back to SENTRY_DSN env var) + --sentry-environment string Sentry environment name, e.g. production or development (falls back to SENTRY_ENVIRONMENT env var) + --sentry-traces-sample-rate float Sentry traces sample rate (0.0-1.0) for performance monitoring (default 1) + --socket string UNIX socket path to bind the server to (overrides host and port if provided) ``` ### Options inherited from parent commands diff --git a/docs/toolhive/reference/crd-spec.md b/docs/toolhive/reference/crd-spec.md index b32bc94b..bd97c3e9 100644 --- a/docs/toolhive/reference/crd-spec.md +++ b/docs/toolhive/reference/crd-spec.md @@ -191,6 +191,7 @@ _Appears in:_ | --- | --- | --- | --- | | `type` _string_ | Type is the authz type: "cedar", "none" | | | | `policies` _string array_ | Policies contains Cedar policy definitions (when Type = "cedar"). | | | +| `primaryUpstreamProvider` _string_ | PrimaryUpstreamProvider names the upstream IDP provider whose access
token should be used as the source of JWT claims for Cedar evaluation.
When empty, claims from the ToolHive-issued token are used.
Must match an upstream provider name configured in the embedded auth server
(e.g. "default", "github"). Only relevant when the embedded auth server is active. | | Optional: \{\}
| #### vmcp.config.CircuitBreakerConfig @@ -388,6 +389,8 @@ _Appears in:_ | `clientSecretEnv` _string_ | ClientSecretEnv is the name of the environment variable containing the client secret.
This is the secure way to reference secrets - the actual secret value is never stored
in configuration files, only the environment variable name.
The secret value will be resolved from this environment variable at runtime. | | | | `audience` _string_ | Audience is the required token audience. | | | | `resource` _string_ | Resource is the OAuth 2.0 resource indicator (RFC 8707).
Used in WWW-Authenticate header and OAuth discovery metadata (RFC 9728).
If not specified, defaults to Audience. | | | +| `jwksUrl` _string_ | JWKSURL is the explicit JWKS endpoint URL.
When set, skips OIDC discovery and fetches the JWKS directly from this URL.
This is useful when the OIDC issuer does not serve a /.well-known/openid-configuration. | | Optional: \{\}
| +| `introspectionUrl` _string_ | IntrospectionURL is the token introspection endpoint URL (RFC 7662).
When set, enables token introspection for opaque (non-JWT) tokens. | | Optional: \{\}
| | `scopes` _string array_ | Scopes are the required OAuth scopes. | | | | `protectedResourceAllowPrivateIp` _boolean_ | ProtectedResourceAllowPrivateIP allows protected resource endpoint on private IP addresses
Use with caution - only enable for trusted internal IDPs or testing | | | | `jwksAllowPrivateIp` _boolean_ | JwksAllowPrivateIP allows OIDC discovery and JWKS fetches to private IP addresses.
Enable when the embedded auth server runs on a loopback address and
the OIDC middleware needs to fetch its JWKS from that address.
Use with caution - only enable for trusted internal IDPs or testing. | | | @@ -741,12 +744,16 @@ _Appears in:_ - [api.v1alpha1.MCPExternalAuthConfigList](#apiv1alpha1mcpexternalauthconfiglist) - [api.v1alpha1.MCPGroup](#apiv1alpha1mcpgroup) - [api.v1alpha1.MCPGroupList](#apiv1alpha1mcpgrouplist) +- [api.v1alpha1.MCPOIDCConfig](#apiv1alpha1mcpoidcconfig) +- [api.v1alpha1.MCPOIDCConfigList](#apiv1alpha1mcpoidcconfiglist) - [api.v1alpha1.MCPRegistry](#apiv1alpha1mcpregistry) - [api.v1alpha1.MCPRegistryList](#apiv1alpha1mcpregistrylist) - [api.v1alpha1.MCPRemoteProxy](#apiv1alpha1mcpremoteproxy) - [api.v1alpha1.MCPRemoteProxyList](#apiv1alpha1mcpremoteproxylist) - [api.v1alpha1.MCPServer](#apiv1alpha1mcpserver) - [api.v1alpha1.MCPServerList](#apiv1alpha1mcpserverlist) +- [api.v1alpha1.MCPTelemetryConfig](#apiv1alpha1mcptelemetryconfig) +- [api.v1alpha1.MCPTelemetryConfigList](#apiv1alpha1mcptelemetryconfiglist) - [api.v1alpha1.MCPToolConfig](#apiv1alpha1mcptoolconfig) - [api.v1alpha1.MCPToolConfigList](#apiv1alpha1mcptoolconfiglist) - [api.v1alpha1.VirtualMCPCompositeToolDefinition](#apiv1alpha1virtualmcpcompositetooldefinition) @@ -955,6 +962,7 @@ CABundleSource defines a source for CA certificate bundles. _Appears in:_ - [api.v1alpha1.ConfigMapOIDCRef](#apiv1alpha1configmapoidcref) - [api.v1alpha1.InlineOIDCConfig](#apiv1alpha1inlineoidcconfig) +- [api.v1alpha1.InlineOIDCSharedConfig](#apiv1alpha1inlineoidcsharedconfig) | Field | Description | Default | Validation | | --- | --- | --- | --- | @@ -1243,6 +1251,7 @@ _Appears in:_ | `unauthenticated` | ExternalAuthTypeUnauthenticated is the type for no authentication
This should only be used for backends on trusted networks (e.g., localhost, VPC)
or when authentication is handled by network-level security
| | `embeddedAuthServer` | ExternalAuthTypeEmbeddedAuthServer is the type for embedded OAuth2/OIDC authorization server
This enables running an embedded auth server that delegates to upstream IDPs
| | `awsSts` | ExternalAuthTypeAWSSts is the type for AWS STS authentication
| +| `upstreamInject` | ExternalAuthTypeUpstreamInject is the type for upstream token injection
This injects an upstream IDP access token as the Authorization: Bearer header
| #### api.v1alpha1.GitAuthConfig @@ -1353,7 +1362,8 @@ _Appears in:_ | Field | Description | Default | Validation | | --- | --- | --- | --- | | `type` _string_ | Type defines the authentication type: anonymous or oidc
When no authentication is required, explicitly set this to "anonymous" | | Enum: [anonymous oidc]
Required: \{\}
| -| `oidcConfig` _[api.v1alpha1.OIDCConfigRef](#apiv1alpha1oidcconfigref)_ | OIDCConfig defines OIDC authentication configuration
Reuses MCPServer OIDC patterns | | Optional: \{\}
| +| `oidcConfig` _[api.v1alpha1.OIDCConfigRef](#apiv1alpha1oidcconfigref)_ | OIDCConfig defines OIDC authentication configuration.
Deprecated: Use OIDCConfigRef to reference a shared MCPOIDCConfig resource instead.
This field will be removed in v1beta1. OIDCConfig and OIDCConfigRef are mutually exclusive. | | Optional: \{\}
| +| `oidcConfigRef` _[api.v1alpha1.MCPOIDCConfigReference](#apiv1alpha1mcpoidcconfigreference)_ | 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. Mutually exclusive with oidcConfig. | | Optional: \{\}
| | `authzConfig` _[api.v1alpha1.AuthzConfigRef](#apiv1alpha1authzconfigref)_ | AuthzConfig defines authorization policy configuration
Reuses MCPServer authz patterns | | Optional: \{\}
| @@ -1392,10 +1402,8 @@ _Appears in:_ | `jwksUrl` _string_ | JWKSURL is the URL to fetch the JWKS from | | Optional: \{\}
| | `introspectionUrl` _string_ | IntrospectionURL is the URL for token introspection endpoint | | Optional: \{\}
| | `clientId` _string_ | ClientID is the OIDC client ID | | Optional: \{\}
| -| `clientSecret` _string_ | ClientSecret is the client secret for introspection (optional)
Deprecated: Use ClientSecretRef instead for better security | | Optional: \{\}
| -| `clientSecretRef` _[api.v1alpha1.SecretKeyRef](#apiv1alpha1secretkeyref)_ | ClientSecretRef is a reference to a Kubernetes Secret containing the client secret
If both ClientSecret and ClientSecretRef are provided, ClientSecretRef takes precedence | | Optional: \{\}
| -| `thvCABundlePath` _string_ | ThvCABundlePath is the path to CA certificate bundle file for HTTPS requests.
Deprecated: Use CABundleRef instead. ThvCABundlePath requires the CA bundle to
already exist in the proxy runner container (e.g., Kubernetes service account CA at
/var/run/secrets/kubernetes.io/serviceaccount/ca.crt). For custom CA certificates,
use CABundleRef which automatically mounts the ConfigMap and computes the path.
This field will be removed when the API graduates to v1beta1. | | Optional: \{\}
| -| `caBundleRef` _[api.v1alpha1.CABundleSource](#apiv1alpha1cabundlesource)_ | CABundleRef references a ConfigMap containing the CA certificate bundle.
When specified, ToolHive auto-mounts the ConfigMap and auto-computes ThvCABundlePath.
If ThvCABundlePath is explicitly set, it takes precedence over CABundleRef. | | Optional: \{\}
| +| `clientSecretRef` _[api.v1alpha1.SecretKeyRef](#apiv1alpha1secretkeyref)_ | ClientSecretRef is a reference to a Kubernetes Secret containing the client secret | | Optional: \{\}
| +| `caBundleRef` _[api.v1alpha1.CABundleSource](#apiv1alpha1cabundlesource)_ | CABundleRef references a ConfigMap containing the CA certificate bundle.
When specified, ToolHive auto-mounts the ConfigMap and auto-computes the CA bundle path. | | Optional: \{\}
| | `jwksAuthTokenPath` _string_ | JWKSAuthTokenPath is the path to file containing bearer token for JWKS/OIDC requests
The file must be mounted into the pod (e.g., via Secret volume) | | Optional: \{\}
| | `jwksAllowPrivateIP` _boolean_ | JWKSAllowPrivateIP allows JWKS/OIDC endpoints on private IP addresses
Use with caution - only enable for trusted internal IDPs | false | Optional: \{\}
| | `protectedResourceAllowPrivateIP` _boolean_ | ProtectedResourceAllowPrivateIP allows protected resource endpoint on private IP addresses
Use with caution - only enable for trusted internal IDPs or testing | false | Optional: \{\}
| @@ -1403,6 +1411,33 @@ _Appears in:_ | `scopes` _string array_ | Scopes is the list of OAuth scopes to advertise in the well-known endpoint (RFC 9728)
If empty, defaults to ["openid"] | | Optional: \{\}
| +#### api.v1alpha1.InlineOIDCSharedConfig + + + +InlineOIDCSharedConfig contains direct OIDC configuration. +This contains shared fields without audience and scopes, which are specified per-server +via MCPOIDCConfigReference. + + + +_Appears in:_ +- [api.v1alpha1.MCPOIDCConfigSpec](#apiv1alpha1mcpoidcconfigspec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `issuer` _string_ | Issuer is the OIDC issuer URL | | Required: \{\}
| +| `jwksUrl` _string_ | JWKSURL is the URL to fetch the JWKS from | | Optional: \{\}
| +| `introspectionUrl` _string_ | IntrospectionURL is the URL for token introspection endpoint | | Optional: \{\}
| +| `clientId` _string_ | ClientID is the OIDC client ID | | Optional: \{\}
| +| `clientSecretRef` _[api.v1alpha1.SecretKeyRef](#apiv1alpha1secretkeyref)_ | ClientSecretRef is a reference to a Kubernetes Secret containing the client secret | | Optional: \{\}
| +| `caBundleRef` _[api.v1alpha1.CABundleSource](#apiv1alpha1cabundlesource)_ | CABundleRef references a ConfigMap containing the CA certificate bundle.
When specified, ToolHive auto-mounts the ConfigMap and auto-computes ThvCABundlePath. | | Optional: \{\}
| +| `jwksAuthTokenPath` _string_ | JWKSAuthTokenPath is the path to file containing bearer token for JWKS/OIDC requests | | Optional: \{\}
| +| `jwksAllowPrivateIP` _boolean_ | JWKSAllowPrivateIP allows JWKS/OIDC endpoints on private IP addresses | false | Optional: \{\}
| +| `protectedResourceAllowPrivateIP` _boolean_ | ProtectedResourceAllowPrivateIP allows protected resource endpoint on private IP addresses | false | Optional: \{\}
| +| `insecureAllowHTTP` _boolean_ | InsecureAllowHTTP allows HTTP (non-HTTPS) OIDC issuers for development/testing.
WARNING: This is insecure and should NEVER be used in production. | false | Optional: \{\}
| + + #### api.v1alpha1.KubernetesOIDCConfig @@ -1425,6 +1460,28 @@ _Appears in:_ | `useClusterAuth` _boolean_ | UseClusterAuth enables using the Kubernetes cluster's CA bundle and service account token
When true, uses /var/run/secrets/kubernetes.io/serviceaccount/ca.crt for TLS verification
and /var/run/secrets/kubernetes.io/serviceaccount/token for bearer token authentication
Defaults to true if not specified | | Optional: \{\}
| +#### api.v1alpha1.KubernetesServiceAccountOIDCConfig + + + +KubernetesServiceAccountOIDCConfig configures OIDC for Kubernetes service account token validation. +This contains shared fields without audience, which is specified per-server via MCPOIDCConfigReference. + + + +_Appears in:_ +- [api.v1alpha1.MCPOIDCConfigSpec](#apiv1alpha1mcpoidcconfigspec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `serviceAccount` _string_ | ServiceAccount is the name of the service account to validate tokens for.
If empty, uses the pod's service account. | | Optional: \{\}
| +| `namespace` _string_ | Namespace is the namespace of the service account.
If empty, uses the MCPServer's namespace. | | Optional: \{\}
| +| `issuer` _string_ | Issuer is the OIDC issuer URL. | https://kubernetes.default.svc | Optional: \{\}
| +| `jwksUrl` _string_ | JWKSURL is the URL to fetch the JWKS from.
If empty, OIDC discovery will be used to automatically determine the JWKS URL. | | Optional: \{\}
| +| `introspectionUrl` _string_ | IntrospectionURL is the URL for token introspection endpoint.
If empty, OIDC discovery will be used to automatically determine the introspection URL. | | Optional: \{\}
| +| `useClusterAuth` _boolean_ | UseClusterAuth enables using the Kubernetes cluster's CA bundle and service account token.
When true, uses /var/run/secrets/kubernetes.io/serviceaccount/ca.crt for TLS verification
and /var/run/secrets/kubernetes.io/serviceaccount/token for bearer token authentication.
Defaults to true if not specified. | | Optional: \{\}
| + + #### api.v1alpha1.MCPExternalAuthConfig @@ -1485,12 +1542,13 @@ _Appears in:_ | Field | Description | Default | Validation | | --- | --- | --- | --- | -| `type` _[api.v1alpha1.ExternalAuthType](#apiv1alpha1externalauthtype)_ | Type is the type of external authentication to configure | | Enum: [tokenExchange headerInjection bearerToken unauthenticated embeddedAuthServer awsSts]
Required: \{\}
| +| `type` _[api.v1alpha1.ExternalAuthType](#apiv1alpha1externalauthtype)_ | Type is the type of external authentication to configure | | Enum: [tokenExchange headerInjection bearerToken unauthenticated embeddedAuthServer awsSts upstreamInject]
Required: \{\}
| | `tokenExchange` _[api.v1alpha1.TokenExchangeConfig](#apiv1alpha1tokenexchangeconfig)_ | TokenExchange configures RFC-8693 OAuth 2.0 Token Exchange
Only used when Type is "tokenExchange" | | Optional: \{\}
| | `headerInjection` _[api.v1alpha1.HeaderInjectionConfig](#apiv1alpha1headerinjectionconfig)_ | HeaderInjection configures custom HTTP header injection
Only used when Type is "headerInjection" | | Optional: \{\}
| | `bearerToken` _[api.v1alpha1.BearerTokenConfig](#apiv1alpha1bearertokenconfig)_ | BearerToken configures bearer token authentication
Only used when Type is "bearerToken" | | Optional: \{\}
| | `embeddedAuthServer` _[api.v1alpha1.EmbeddedAuthServerConfig](#apiv1alpha1embeddedauthserverconfig)_ | EmbeddedAuthServer configures an embedded OAuth2/OIDC authorization server
Only used when Type is "embeddedAuthServer" | | Optional: \{\}
| | `awsSts` _[api.v1alpha1.AWSStsConfig](#apiv1alpha1awsstsconfig)_ | AWSSts configures AWS STS authentication with SigV4 request signing
Only used when Type is "awsSts" | | Optional: \{\}
| +| `upstreamInject` _[api.v1alpha1.UpstreamInjectSpec](#apiv1alpha1upstreaminjectspec)_ | UpstreamInject configures upstream token injection for backend requests.
Only used when Type is "upstreamInject". | | Optional: \{\}
| #### api.v1alpha1.MCPExternalAuthConfigStatus @@ -1509,7 +1567,7 @@ _Appears in:_ | `conditions` _[Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#condition-v1-meta) array_ | Conditions represent the latest available observations of the MCPExternalAuthConfig's state | | Optional: \{\}
| | `observedGeneration` _integer_ | ObservedGeneration is the most recent generation observed for this MCPExternalAuthConfig.
It corresponds to the MCPExternalAuthConfig's generation, which is updated on mutation by the API Server. | | Optional: \{\}
| | `configHash` _string_ | ConfigHash is a hash of the current configuration for change detection | | Optional: \{\}
| -| `referencingServers` _string array_ | ReferencingServers is a list of MCPServer resources that reference this MCPExternalAuthConfig
This helps track which servers need to be reconciled when this config changes | | Optional: \{\}
| +| `referencingWorkloads` _[api.v1alpha1.WorkloadReference](#apiv1alpha1workloadreference) array_ | ReferencingWorkloads is a list of workload resources that reference this MCPExternalAuthConfig.
Each entry identifies the workload by kind and name. | | Optional: \{\}
| #### api.v1alpha1.MCPGroup @@ -1602,6 +1660,7 @@ _Appears in:_ | Field | Description | Default | Validation | | --- | --- | --- | --- | +| `observedGeneration` _integer_ | ObservedGeneration reflects the generation most recently observed by the controller | | Optional: \{\}
| | `phase` _[api.v1alpha1.MCPGroupPhase](#apiv1alpha1mcpgroupphase)_ | Phase indicates current state | Pending | Enum: [Ready Pending Failed]
Optional: \{\}
| | `servers` _string array_ | Servers lists MCPServer names in this group | | Optional: \{\}
| | `serverCount` _integer_ | ServerCount is the number of MCPServers | | Optional: \{\}
| @@ -1610,6 +1669,127 @@ _Appears in:_ | `conditions` _[Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#condition-v1-meta) array_ | Conditions represent observations | | Optional: \{\}
| +#### api.v1alpha1.MCPOIDCConfig + + + +MCPOIDCConfig is the Schema for the mcpoidcconfigs API. +MCPOIDCConfig resources are namespace-scoped and can only be referenced by +MCPServer resources within the same namespace. Cross-namespace references +are not supported for security and isolation reasons. + + + +_Appears in:_ +- [api.v1alpha1.MCPOIDCConfigList](#apiv1alpha1mcpoidcconfiglist) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `toolhive.stacklok.dev/v1alpha1` | | | +| `kind` _string_ | `MCPOIDCConfig` | | | +| `kind` _string_ | Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds | | Optional: \{\}
| +| `apiVersion` _string_ | APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources | | Optional: \{\}
| +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | | | +| `spec` _[api.v1alpha1.MCPOIDCConfigSpec](#apiv1alpha1mcpoidcconfigspec)_ | | | | +| `status` _[api.v1alpha1.MCPOIDCConfigStatus](#apiv1alpha1mcpoidcconfigstatus)_ | | | | + + +#### api.v1alpha1.MCPOIDCConfigList + + + +MCPOIDCConfigList contains a list of MCPOIDCConfig + + + + + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `toolhive.stacklok.dev/v1alpha1` | | | +| `kind` _string_ | `MCPOIDCConfigList` | | | +| `kind` _string_ | Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds | | Optional: \{\}
| +| `apiVersion` _string_ | APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources | | Optional: \{\}
| +| `metadata` _[ListMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#listmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | | | +| `items` _[api.v1alpha1.MCPOIDCConfig](#apiv1alpha1mcpoidcconfig) array_ | | | | + + +#### api.v1alpha1.MCPOIDCConfigReference + + + +MCPOIDCConfigReference is a reference to an MCPOIDCConfig resource with per-server overrides. +The referenced MCPOIDCConfig must be in the same namespace as the MCPServer. + + + +_Appears in:_ +- [api.v1alpha1.IncomingAuthConfig](#apiv1alpha1incomingauthconfig) +- [api.v1alpha1.MCPServerSpec](#apiv1alpha1mcpserverspec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `name` _string_ | Name is the name of the MCPOIDCConfig resource | | MinLength: 1
Required: \{\}
| +| `audience` _string_ | Audience is the expected audience for token validation.
This MUST be unique per server to prevent token replay attacks. | | MinLength: 1
Required: \{\}
| +| `scopes` _string array_ | Scopes is the list of OAuth scopes to advertise in the well-known endpoint (RFC 9728).
If empty, defaults to ["openid"]. | | Optional: \{\}
| + + +#### api.v1alpha1.MCPOIDCConfigSourceType + +_Underlying type:_ _string_ + +MCPOIDCConfigSourceType represents the type of OIDC configuration source for MCPOIDCConfig + + + +_Appears in:_ +- [api.v1alpha1.MCPOIDCConfigSpec](#apiv1alpha1mcpoidcconfigspec) + +| Field | Description | +| --- | --- | +| `kubernetesServiceAccount` | MCPOIDCConfigTypeKubernetesServiceAccount is the type for Kubernetes service account token validation
| +| `inline` | MCPOIDCConfigTypeInline is the type for inline OIDC configuration
| + + +#### api.v1alpha1.MCPOIDCConfigSpec + + + +MCPOIDCConfigSpec defines the desired state of MCPOIDCConfig. +MCPOIDCConfig resources are namespace-scoped and can only be referenced by +MCPServer resources in the same namespace. + + + +_Appears in:_ +- [api.v1alpha1.MCPOIDCConfig](#apiv1alpha1mcpoidcconfig) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `type` _[api.v1alpha1.MCPOIDCConfigSourceType](#apiv1alpha1mcpoidcconfigsourcetype)_ | Type is the type of OIDC configuration source | | Enum: [kubernetesServiceAccount inline]
Required: \{\}
| +| `kubernetesServiceAccount` _[api.v1alpha1.KubernetesServiceAccountOIDCConfig](#apiv1alpha1kubernetesserviceaccountoidcconfig)_ | KubernetesServiceAccount configures OIDC for Kubernetes service account token validation.
Only used when Type is "kubernetesServiceAccount". | | Optional: \{\}
| +| `inline` _[api.v1alpha1.InlineOIDCSharedConfig](#apiv1alpha1inlineoidcsharedconfig)_ | Inline contains direct OIDC configuration.
Only used when Type is "inline". | | Optional: \{\}
| + + +#### api.v1alpha1.MCPOIDCConfigStatus + + + +MCPOIDCConfigStatus defines the observed state of MCPOIDCConfig + + + +_Appears in:_ +- [api.v1alpha1.MCPOIDCConfig](#apiv1alpha1mcpoidcconfig) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `conditions` _[Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#condition-v1-meta) array_ | Conditions represent the latest available observations of the MCPOIDCConfig's state | | Optional: \{\}
| +| `observedGeneration` _integer_ | ObservedGeneration is the most recent generation observed for this MCPOIDCConfig. | | Optional: \{\}
| +| `configHash` _string_ | ConfigHash is a hash of the current configuration for change detection | | Optional: \{\}
| +| `referencingWorkloads` _[api.v1alpha1.WorkloadReference](#apiv1alpha1workloadreference) array_ | ReferencingWorkloads is a list of workload resources that reference this MCPOIDCConfig.
Each entry identifies the workload by kind and name. | | Optional: \{\}
| + + #### api.v1alpha1.MCPRegistry @@ -1837,6 +2017,7 @@ _Appears in:_ | Field | Description | Default | Validation | | --- | --- | --- | --- | +| `observedGeneration` _integer_ | ObservedGeneration reflects the generation most recently observed by the controller | | Optional: \{\}
| | `phase` _[api.v1alpha1.MCPRegistryPhase](#apiv1alpha1mcpregistryphase)_ | Phase represents the current overall phase of the MCPRegistry
Derived from sync and API status | | Enum: [Pending Ready Failed Syncing Terminating]
Optional: \{\}
| | `message` _string_ | Message provides additional information about the current phase | | Optional: \{\}
| | `syncStatus` _[api.v1alpha1.SyncStatus](#apiv1alpha1syncstatus)_ | SyncStatus provides detailed information about data synchronization | | Optional: \{\}
| @@ -1924,7 +2105,6 @@ _Appears in:_ | Field | Description | Default | Validation | | --- | --- | --- | --- | | `remoteURL` _string_ | RemoteURL is the URL of the remote MCP server to proxy | | Pattern: `^https?://`
Required: \{\}
| -| `port` _integer_ | Port is the port to expose the MCP proxy on
Deprecated: Use ProxyPort instead | 8080 | Maximum: 65535
Minimum: 1
| | `proxyPort` _integer_ | ProxyPort is the port to expose the MCP proxy on | 8080 | Maximum: 65535
Minimum: 1
| | `transport` _string_ | Transport is the transport method for the remote proxy (sse or streamable-http) | streamable-http | Enum: [sse streamable-http]
| | `oidcConfig` _[api.v1alpha1.OIDCConfigRef](#apiv1alpha1oidcconfigref)_ | OIDCConfig defines OIDC authentication configuration for the proxy
This validates incoming tokens from clients. Required for proxy mode. | | Required: \{\}
| @@ -2045,8 +2225,6 @@ _Appears in:_ | `image` _string_ | Image is the container image for the MCP server | | Required: \{\}
| | `transport` _string_ | Transport is the transport method for the MCP server (stdio, streamable-http or sse) | stdio | Enum: [stdio streamable-http sse]
| | `proxyMode` _string_ | ProxyMode is the proxy mode for stdio transport (sse or streamable-http)
This setting is ONLY applicable when Transport is "stdio".
For direct transports (sse, streamable-http), this field is ignored.
The default value is applied by Kubernetes but will be ignored for non-stdio transports. | streamable-http | Enum: [sse streamable-http]
Optional: \{\}
| -| `port` _integer_ | Port is the port to expose the MCP server on
Deprecated: Use ProxyPort instead | 8080 | Maximum: 65535
Minimum: 1
| -| `targetPort` _integer_ | TargetPort is the port that MCP server listens to
Deprecated: Use McpPort instead | | Maximum: 65535
Minimum: 1
Optional: \{\}
| | `proxyPort` _integer_ | ProxyPort is the port to expose the proxy runner on | 8080 | Maximum: 65535
Minimum: 1
| | `mcpPort` _integer_ | McpPort is the port that MCP server listens to | | Maximum: 65535
Minimum: 1
Optional: \{\}
| | `args` _string array_ | Args are additional arguments to pass to the MCP server | | Optional: \{\}
| @@ -2058,13 +2236,14 @@ _Appears in:_ | `permissionProfile` _[api.v1alpha1.PermissionProfileRef](#apiv1alpha1permissionprofileref)_ | PermissionProfile defines the permission profile to use | | Optional: \{\}
| | `podTemplateSpec` _[RawExtension](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#rawextension-runtime-pkg)_ | PodTemplateSpec defines the pod template to use for the MCP server
This allows for customizing the pod configuration beyond what is provided by the other fields.
Note that to modify the specific container the MCP server runs in, you must specify
the `mcp` container name in the PodTemplateSpec.
This field accepts a PodTemplateSpec object as JSON/YAML. | | Type: object
Optional: \{\}
| | `resourceOverrides` _[api.v1alpha1.ResourceOverrides](#apiv1alpha1resourceoverrides)_ | ResourceOverrides allows overriding annotations and labels for resources created by the operator | | Optional: \{\}
| -| `oidcConfig` _[api.v1alpha1.OIDCConfigRef](#apiv1alpha1oidcconfigref)_ | OIDCConfig defines OIDC authentication configuration for the MCP server | | Optional: \{\}
| +| `oidcConfig` _[api.v1alpha1.OIDCConfigRef](#apiv1alpha1oidcconfigref)_ | OIDCConfig defines OIDC authentication configuration for the MCP server.
Deprecated: Use OIDCConfigRef to reference a shared MCPOIDCConfig resource instead.
This field will be removed in v1beta1. OIDCConfig and OIDCConfigRef are mutually exclusive. | | Optional: \{\}
| +| `oidcConfigRef` _[api.v1alpha1.MCPOIDCConfigReference](#apiv1alpha1mcpoidcconfigreference)_ | OIDCConfigRef references a shared MCPOIDCConfig resource for OIDC authentication.
The referenced MCPOIDCConfig must exist in the same namespace as this MCPServer.
Per-server overrides (audience, scopes) are specified here; shared provider config
lives in the MCPOIDCConfig resource. Mutually exclusive with oidcConfig. | | Optional: \{\}
| | `authzConfig` _[api.v1alpha1.AuthzConfigRef](#apiv1alpha1authzconfigref)_ | AuthzConfig defines authorization policy configuration for the MCP server | | Optional: \{\}
| | `audit` _[api.v1alpha1.AuditConfig](#apiv1alpha1auditconfig)_ | Audit defines audit logging configuration for the MCP server | | Optional: \{\}
| -| `tools` _string array_ | ToolsFilter is the filter on tools applied to the MCP server
Deprecated: Use ToolConfigRef instead | | Optional: \{\}
| -| `toolConfigRef` _[api.v1alpha1.ToolConfigRef](#apiv1alpha1toolconfigref)_ | ToolConfigRef references a MCPToolConfig resource for tool filtering and renaming.
The referenced MCPToolConfig must exist in the same namespace as this MCPServer.
Cross-namespace references are not supported for security and isolation reasons.
If specified, this takes precedence over the inline ToolsFilter field. | | Optional: \{\}
| +| `toolConfigRef` _[api.v1alpha1.ToolConfigRef](#apiv1alpha1toolconfigref)_ | ToolConfigRef references a MCPToolConfig resource for tool filtering and renaming.
The referenced MCPToolConfig must exist in the same namespace as this MCPServer.
Cross-namespace references are not supported for security and isolation reasons. | | Optional: \{\}
| | `externalAuthConfigRef` _[api.v1alpha1.ExternalAuthConfigRef](#apiv1alpha1externalauthconfigref)_ | ExternalAuthConfigRef references a MCPExternalAuthConfig resource for external authentication.
The referenced MCPExternalAuthConfig must exist in the same namespace as this MCPServer. | | Optional: \{\}
| -| `telemetry` _[api.v1alpha1.TelemetryConfig](#apiv1alpha1telemetryconfig)_ | Telemetry defines observability configuration for the MCP server | | Optional: \{\}
| +| `telemetryConfigRef` _[api.v1alpha1.MCPTelemetryConfigReference](#apiv1alpha1mcptelemetryconfigreference)_ | TelemetryConfigRef references an MCPTelemetryConfig resource for shared telemetry configuration.
The referenced MCPTelemetryConfig must exist in the same namespace as this MCPServer.
Cross-namespace references are not supported for security and isolation reasons.
Mutually exclusive with the deprecated inline Telemetry field. | | Optional: \{\}
| +| `telemetry` _[api.v1alpha1.TelemetryConfig](#apiv1alpha1telemetryconfig)_ | Telemetry defines inline observability configuration for the MCP server.
Deprecated: Use TelemetryConfigRef to reference a shared MCPTelemetryConfig resource instead.
This field will be removed in a future release. Setting both telemetry and telemetryConfigRef
is rejected by CEL validation. | | Optional: \{\}
| | `trustProxyHeaders` _boolean_ | TrustProxyHeaders indicates whether to trust X-Forwarded-* headers from reverse proxies
When enabled, the proxy will use X-Forwarded-Proto, X-Forwarded-Host, X-Forwarded-Port,
and X-Forwarded-Prefix headers to construct endpoint URLs | false | Optional: \{\}
| | `endpointPrefix` _string_ | EndpointPrefix is the path prefix to prepend to SSE endpoint URLs.
This is used to handle path-based ingress routing scenarios where the ingress
strips a path prefix before forwarding to the backend. | | Optional: \{\}
| | `groupRef` _string_ | GroupRef is the name of the MCPGroup this server belongs to
Must reference an existing MCPGroup in the same namespace | | Optional: \{\}
| @@ -2088,14 +2267,148 @@ _Appears in:_ | Field | Description | Default | Validation | | --- | --- | --- | --- | | `conditions` _[Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#condition-v1-meta) array_ | Conditions represent the latest available observations of the MCPServer's state | | Optional: \{\}
| +| `observedGeneration` _integer_ | ObservedGeneration reflects the generation most recently observed by the controller | | Optional: \{\}
| | `toolConfigHash` _string_ | ToolConfigHash stores the hash of the referenced ToolConfig for change detection | | Optional: \{\}
| | `externalAuthConfigHash` _string_ | ExternalAuthConfigHash is the hash of the referenced MCPExternalAuthConfig spec | | Optional: \{\}
| +| `oidcConfigHash` _string_ | OIDCConfigHash is the hash of the referenced MCPOIDCConfig spec for change detection | | Optional: \{\}
| +| `telemetryConfigHash` _string_ | TelemetryConfigHash is the hash of the referenced MCPTelemetryConfig spec for change detection | | Optional: \{\}
| | `url` _string_ | URL is the URL where the MCP server can be accessed | | Optional: \{\}
| | `phase` _[api.v1alpha1.MCPServerPhase](#apiv1alpha1mcpserverphase)_ | Phase is the current phase of the MCPServer | | Enum: [Pending Running Failed Terminating Stopped]
Optional: \{\}
| | `message` _string_ | Message provides additional information about the current phase | | Optional: \{\}
| | `readyReplicas` _integer_ | ReadyReplicas is the number of ready proxy replicas | | Optional: \{\}
| +#### api.v1alpha1.MCPTelemetryConfig + + + +MCPTelemetryConfig is the Schema for the mcptelemetryconfigs API. +MCPTelemetryConfig resources are namespace-scoped and can only be referenced by +MCPServer resources within the same namespace. Cross-namespace references +are not supported for security and isolation reasons. + + + +_Appears in:_ +- [api.v1alpha1.MCPTelemetryConfigList](#apiv1alpha1mcptelemetryconfiglist) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `toolhive.stacklok.dev/v1alpha1` | | | +| `kind` _string_ | `MCPTelemetryConfig` | | | +| `kind` _string_ | Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds | | Optional: \{\}
| +| `apiVersion` _string_ | APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources | | Optional: \{\}
| +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | | | +| `spec` _[api.v1alpha1.MCPTelemetryConfigSpec](#apiv1alpha1mcptelemetryconfigspec)_ | | | | +| `status` _[api.v1alpha1.MCPTelemetryConfigStatus](#apiv1alpha1mcptelemetryconfigstatus)_ | | | | + + +#### api.v1alpha1.MCPTelemetryConfigList + + + +MCPTelemetryConfigList contains a list of MCPTelemetryConfig + + + + + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `toolhive.stacklok.dev/v1alpha1` | | | +| `kind` _string_ | `MCPTelemetryConfigList` | | | +| `kind` _string_ | Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds | | Optional: \{\}
| +| `apiVersion` _string_ | APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources | | Optional: \{\}
| +| `metadata` _[ListMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#listmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | | | +| `items` _[api.v1alpha1.MCPTelemetryConfig](#apiv1alpha1mcptelemetryconfig) array_ | | | | + + +#### api.v1alpha1.MCPTelemetryConfigReference + + + +MCPTelemetryConfigReference is a reference to an MCPTelemetryConfig resource +with per-server overrides. The referenced MCPTelemetryConfig must be in the +same namespace as the MCPServer. + + + +_Appears in:_ +- [api.v1alpha1.MCPServerSpec](#apiv1alpha1mcpserverspec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `name` _string_ | Name is the name of the MCPTelemetryConfig resource | | MinLength: 1
Required: \{\}
| +| `serviceName` _string_ | ServiceName overrides the telemetry service name for this specific server.
This MUST be unique per server for proper observability (e.g., distinguishing
traces and metrics from different servers sharing the same collector).
If empty, defaults to the server name with "thv-" prefix at runtime. | | Optional: \{\}
| + + +#### api.v1alpha1.MCPTelemetryConfigSpec + + + +MCPTelemetryConfigSpec defines the desired state of MCPTelemetryConfig. +The spec uses a nested structure with openTelemetry and prometheus sub-objects +for clear separation of concerns. + + + +_Appears in:_ +- [api.v1alpha1.MCPTelemetryConfig](#apiv1alpha1mcptelemetryconfig) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `openTelemetry` _[api.v1alpha1.MCPTelemetryOTelConfig](#apiv1alpha1mcptelemetryotelconfig)_ | OpenTelemetry defines OpenTelemetry configuration (OTLP endpoint, tracing, metrics) | | Optional: \{\}
| +| `prometheus` _[api.v1alpha1.PrometheusConfig](#apiv1alpha1prometheusconfig)_ | Prometheus defines Prometheus-specific configuration | | Optional: \{\}
| + + +#### api.v1alpha1.MCPTelemetryConfigStatus + + + +MCPTelemetryConfigStatus defines the observed state of MCPTelemetryConfig + + + +_Appears in:_ +- [api.v1alpha1.MCPTelemetryConfig](#apiv1alpha1mcptelemetryconfig) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `conditions` _[Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#condition-v1-meta) array_ | Conditions represent the latest available observations of the MCPTelemetryConfig's state | | Optional: \{\}
| +| `observedGeneration` _integer_ | ObservedGeneration is the most recent generation observed for this MCPTelemetryConfig. | | Optional: \{\}
| +| `configHash` _string_ | ConfigHash is a hash of the current configuration for change detection | | Optional: \{\}
| +| `referencingWorkloads` _[api.v1alpha1.WorkloadReference](#apiv1alpha1workloadreference) array_ | ReferencingWorkloads lists workloads that reference this MCPTelemetryConfig | | Optional: \{\}
| + + +#### api.v1alpha1.MCPTelemetryOTelConfig + + + +MCPTelemetryOTelConfig defines OpenTelemetry configuration for shared MCPTelemetryConfig resources. +Unlike OpenTelemetryConfig (used by inline MCPServer telemetry), this type: + - Omits ServiceName (per-server field set via MCPTelemetryConfigReference) + - Uses map[string]string for Headers (not []string) + - Adds SensitiveHeaders for Kubernetes Secret-backed credentials + - Adds ResourceAttributes for shared OTel resource attributes + + + +_Appears in:_ +- [api.v1alpha1.MCPTelemetryConfigSpec](#apiv1alpha1mcptelemetryconfigspec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `enabled` _boolean_ | Enabled controls whether OpenTelemetry is enabled | false | Optional: \{\}
| +| `endpoint` _string_ | Endpoint is the OTLP endpoint URL for tracing and metrics | | Optional: \{\}
| +| `insecure` _boolean_ | Insecure indicates whether to use HTTP instead of HTTPS for the OTLP endpoint | false | Optional: \{\}
| +| `headers` _object (keys:string, values:string)_ | Headers contains authentication headers for the OTLP endpoint.
For secret-backed credentials, use sensitiveHeaders instead. | | Optional: \{\}
| +| `sensitiveHeaders` _[api.v1alpha1.SensitiveHeader](#apiv1alpha1sensitiveheader) array_ | SensitiveHeaders contains headers whose values are stored in Kubernetes Secrets.
Use this for credential headers (e.g., API keys, bearer tokens) instead of
embedding secrets in the headers field. | | Optional: \{\}
| +| `resourceAttributes` _object (keys:string, values:string)_ | ResourceAttributes contains custom resource attributes to be added to all telemetry signals.
These become OTel resource attributes (e.g., deployment.environment, service.namespace).
Note: service.name is intentionally excluded — it is set per-server via
MCPTelemetryConfigReference.ServiceName. | | Optional: \{\}
| +| `metrics` _[api.v1alpha1.OpenTelemetryMetricsConfig](#apiv1alpha1opentelemetrymetricsconfig)_ | Metrics defines OpenTelemetry metrics-specific configuration | | Optional: \{\}
| +| `tracing` _[api.v1alpha1.OpenTelemetryTracingConfig](#apiv1alpha1opentelemetrytracingconfig)_ | Tracing defines OpenTelemetry tracing configuration | | Optional: \{\}
| +| `useLegacyAttributes` _boolean_ | UseLegacyAttributes controls whether legacy attribute names are emitted alongside
the new MCP OTEL semantic convention names. Defaults to true for backward compatibility.
This will change to false in a future release and eventually be removed. | true | Optional: \{\}
| + + #### api.v1alpha1.MCPToolConfig @@ -2173,9 +2486,10 @@ _Appears in:_ | Field | Description | Default | Validation | | --- | --- | --- | --- | +| `conditions` _[Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#condition-v1-meta) array_ | Conditions represent the latest available observations of the MCPToolConfig's state | | Optional: \{\}
| | `observedGeneration` _integer_ | ObservedGeneration is the most recent generation observed for this MCPToolConfig.
It corresponds to the MCPToolConfig's generation, which is updated on mutation by the API Server. | | Optional: \{\}
| | `configHash` _string_ | ConfigHash is a hash of the current configuration for change detection | | Optional: \{\}
| -| `referencingServers` _string array_ | ReferencingServers is a list of MCPServer resources that reference this MCPToolConfig
This helps track which servers need to be reconciled when this config changes | | Optional: \{\}
| +| `referencingWorkloads` _[api.v1alpha1.WorkloadReference](#apiv1alpha1workloadreference) array_ | ReferencingWorkloads is a list of workload resources that reference this MCPToolConfig.
Each entry identifies the workload by kind and name. | | Optional: \{\}
| #### api.v1alpha1.ModelCacheConfig @@ -2331,6 +2645,7 @@ OpenTelemetryMetricsConfig defines OpenTelemetry metrics configuration _Appears in:_ +- [api.v1alpha1.MCPTelemetryOTelConfig](#apiv1alpha1mcptelemetryotelconfig) - [api.v1alpha1.OpenTelemetryConfig](#apiv1alpha1opentelemetryconfig) | Field | Description | Default | Validation | @@ -2347,6 +2662,7 @@ OpenTelemetryTracingConfig defines OpenTelemetry tracing configuration _Appears in:_ +- [api.v1alpha1.MCPTelemetryOTelConfig](#apiv1alpha1mcptelemetryotelconfig) - [api.v1alpha1.OpenTelemetryConfig](#apiv1alpha1opentelemetryconfig) | Field | Description | Default | Validation | @@ -2437,6 +2753,7 @@ PrometheusConfig defines Prometheus-specific configuration _Appears in:_ +- [api.v1alpha1.MCPTelemetryConfigSpec](#apiv1alpha1mcptelemetryconfigspec) - [api.v1alpha1.TelemetryConfig](#apiv1alpha1telemetryconfig) | Field | Description | Default | Validation | @@ -2669,10 +2986,12 @@ _Appears in:_ - [api.v1alpha1.HeaderFromSecret](#apiv1alpha1headerfromsecret) - [api.v1alpha1.HeaderInjectionConfig](#apiv1alpha1headerinjectionconfig) - [api.v1alpha1.InlineOIDCConfig](#apiv1alpha1inlineoidcconfig) +- [api.v1alpha1.InlineOIDCSharedConfig](#apiv1alpha1inlineoidcsharedconfig) - [api.v1alpha1.OAuth2UpstreamConfig](#apiv1alpha1oauth2upstreamconfig) - [api.v1alpha1.OIDCUpstreamConfig](#apiv1alpha1oidcupstreamconfig) - [api.v1alpha1.RedisACLUserConfig](#apiv1alpha1redisacluserconfig) - [api.v1alpha1.RedisTLSConfig](#apiv1alpha1redistlsconfig) +- [api.v1alpha1.SensitiveHeader](#apiv1alpha1sensitiveheader) - [api.v1alpha1.SessionStorageConfig](#apiv1alpha1sessionstorageconfig) - [api.v1alpha1.TokenExchangeConfig](#apiv1alpha1tokenexchangeconfig) @@ -2700,6 +3019,25 @@ _Appears in:_ | `targetEnvName` _string_ | TargetEnvName is the environment variable to be used when setting up the secret in the MCP server
If left unspecified, it defaults to the key | | Optional: \{\}
| +#### api.v1alpha1.SensitiveHeader + + + +SensitiveHeader represents a header whose value is stored in a Kubernetes Secret. +This allows credential headers (e.g., API keys, bearer tokens) to be securely +referenced without embedding secrets inline in the MCPTelemetryConfig resource. + + + +_Appears in:_ +- [api.v1alpha1.MCPTelemetryOTelConfig](#apiv1alpha1mcptelemetryotelconfig) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `name` _string_ | Name is the header name (e.g., "Authorization", "X-API-Key") | | MinLength: 1
Required: \{\}
| +| `secretKeyRef` _[api.v1alpha1.SecretKeyRef](#apiv1alpha1secretkeyref)_ | SecretKeyRef is a reference to a Kubernetes Secret key containing the header value | | Required: \{\}
| + + #### api.v1alpha1.SentinelServiceRef _Underlying type:_ _[api.v1alpha1.struct{Name string "json:\"name\""; Namespace string "json:\"namespace,omitempty\""; Port int32 "json:\"port,omitempty\""}](#apiv1alpha1struct{name string "json:\"name\""; namespace string "json:\"namespace,omitempty\""; port int32 "json:\"port,omitempty\""})_ @@ -2875,6 +3213,7 @@ _Appears in:_ | `scopes` _string array_ | Scopes is a list of OAuth 2.0 scopes to request for the exchanged token | | Optional: \{\}
| | `subjectTokenType` _string_ | SubjectTokenType is the type of the incoming subject token.
Accepts short forms: "access_token" (default), "id_token", "jwt"
Or full URNs: "urn:ietf:params:oauth:token-type:access_token",
"urn:ietf:params:oauth:token-type:id_token",
"urn:ietf:params:oauth:token-type:jwt"
For Google Workload Identity Federation with OIDC providers (like Okta), use "id_token" | | Pattern: `^(access_token\|id_token\|jwt\|urn:ietf:params:oauth:token-type:(access_token\|id_token\|jwt))?$`
Optional: \{\}
| | `externalTokenHeaderName` _string_ | ExternalTokenHeaderName is the name of the custom header to use for the exchanged token.
If set, the exchanged token will be added to this custom header (e.g., "X-Upstream-Token").
If empty or not set, the exchanged token will replace the Authorization header (default behavior). | | Optional: \{\}
| +| `subjectProviderName` _string_ | SubjectProviderName is the name of the upstream provider whose token is used as the
RFC 8693 subject token instead of identity.Token when performing token exchange. | | Optional: \{\}
| #### api.v1alpha1.TokenLifespanConfig @@ -2976,6 +3315,24 @@ _Appears in:_ | `annotations` _[api.v1alpha1.ToolAnnotationsOverride](#apiv1alpha1toolannotationsoverride)_ | Annotations overrides specific tool annotation fields.
Only specified fields are overridden; others pass through from the backend. | | Optional: \{\}
| +#### api.v1alpha1.UpstreamInjectSpec + + + +UpstreamInjectSpec holds configuration for upstream token injection. +This strategy injects an upstream IDP access token obtained by the embedded +authorization server into backend requests as the Authorization: Bearer header. + + + +_Appears in:_ +- [api.v1alpha1.MCPExternalAuthConfigSpec](#apiv1alpha1mcpexternalauthconfigspec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `providerName` _string_ | ProviderName is the name of the upstream IDP provider whose access token
should be injected as the Authorization: Bearer header. | | MinLength: 1
Required: \{\}
| + + #### api.v1alpha1.UpstreamProviderConfig @@ -3272,6 +3629,7 @@ _Appears in:_ | `url` _string_ | URL is the URL where the Virtual MCP server can be accessed | | Optional: \{\}
| | `discoveredBackends` _[api.v1alpha1.DiscoveredBackend](#apiv1alpha1discoveredbackend) array_ | DiscoveredBackends lists discovered backend configurations from the MCPGroup | | Optional: \{\}
| | `backendCount` _integer_ | BackendCount is the number of healthy/ready backends
(excludes unavailable, degraded, and unknown backends) | | Optional: \{\}
| +| `oidcConfigHash` _string_ | OIDCConfigHash is the hash of the referenced MCPOIDCConfig spec for change detection.
Only populated when IncomingAuth.OIDCConfigRef is set. | | Optional: \{\}
| #### api.v1alpha1.Volume @@ -3293,3 +3651,24 @@ _Appears in:_ | `readOnly` _boolean_ | ReadOnly specifies whether the volume should be mounted read-only | false | Optional: \{\}
| +#### api.v1alpha1.WorkloadReference + + + +WorkloadReference identifies a workload that references a shared configuration resource. +Namespace is implicit — cross-namespace references are not supported. + + + +_Appears in:_ +- [api.v1alpha1.MCPExternalAuthConfigStatus](#apiv1alpha1mcpexternalauthconfigstatus) +- [api.v1alpha1.MCPOIDCConfigStatus](#apiv1alpha1mcpoidcconfigstatus) +- [api.v1alpha1.MCPTelemetryConfigStatus](#apiv1alpha1mcptelemetryconfigstatus) +- [api.v1alpha1.MCPToolConfigStatus](#apiv1alpha1mcptoolconfigstatus) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `kind` _string_ | Kind is the type of workload resource | | Enum: [MCPServer VirtualMCPServer MCPRemoteProxy]
Required: \{\}
| +| `name` _string_ | Name is the name of the workload resource | | MinLength: 1
Required: \{\}
| + + diff --git a/static/api-specs/toolhive-api.yaml b/static/api-specs/toolhive-api.yaml index 6a2a3f65..306f81dc 100644 --- a/static/api-specs/toolhive-api.yaml +++ b/static/api-specs/toolhive-api.yaml @@ -1,57 +1,5 @@ components: schemas: - auth.TokenValidatorConfig: - description: |- - DEPRECATED: Middleware configuration. - OIDCConfig contains OIDC configuration - properties: - allowPrivateIP: - description: AllowPrivateIP allows JWKS/OIDC endpoints on private IP addresses - type: boolean - audience: - description: Audience is the expected audience for the token - type: string - authTokenFile: - description: AuthTokenFile is the path to file containing bearer token for - authentication - type: string - cacertPath: - description: CACertPath is the path to the CA certificate bundle for HTTPS - requests - type: string - clientID: - description: ClientID is the OIDC client ID - type: string - clientSecret: - description: ClientSecret is the optional OIDC client secret for introspection - 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 optional introspection endpoint for - validating tokens - type: string - issuer: - description: Issuer is the OIDC issuer URL (e.g., https://accounts.google.com) - type: string - jwksurl: - description: JWKSURL is the URL to fetch the JWKS from - type: string - resourceURL: - description: ResourceURL is the explicit resource URL for OAuth discovery - (RFC 9728) - 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 - type: object github_com_stacklok_toolhive-core_registry_types.Registry: description: Full registry data properties: @@ -141,6 +89,58 @@ components: +optional type: integer type: object + github_com_stacklok_toolhive_pkg_auth.TokenValidatorConfig: + description: |- + DEPRECATED: Middleware configuration. + OIDCConfig contains OIDC configuration + properties: + allowPrivateIP: + description: AllowPrivateIP allows JWKS/OIDC endpoints on private IP addresses + type: boolean + audience: + description: Audience is the expected audience for the token + type: string + authTokenFile: + description: AuthTokenFile is the path to file containing bearer token for + authentication + type: string + cacertPath: + description: CACertPath is the path to the CA certificate bundle for HTTPS + requests + type: string + clientID: + description: ClientID is the OIDC client ID + type: string + clientSecret: + description: ClientSecret is the optional OIDC client secret for introspection + 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 optional introspection endpoint for + validating tokens + type: string + issuer: + description: Issuer is the OIDC issuer URL (e.g., https://accounts.google.com) + type: string + jwksurl: + description: JWKSURL is the URL to fetch the JWKS from + type: string + resourceURL: + description: ResourceURL is the explicit resource URL for OAuth discovery + (RFC 9728) + 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 + type: object github_com_stacklok_toolhive_pkg_auth_awssts.Config: description: AWSStsConfig contains AWS STS token exchange configuration for accessing AWS services @@ -467,7 +467,7 @@ components: signing_key_config: $ref: '#/components/schemas/github_com_stacklok_toolhive_pkg_authserver.SigningKeyRunConfig' storage: - $ref: '#/components/schemas/storage.RunConfig' + $ref: '#/components/schemas/github_com_stacklok_toolhive_pkg_authserver_storage.RunConfig' token_lifespans: $ref: '#/components/schemas/github_com_stacklok_toolhive_pkg_authserver.TokenLifespanRunConfig' upstreams: @@ -629,6 +629,86 @@ components: If not specified, defaults to GET. type: string type: object + github_com_stacklok_toolhive_pkg_authserver_storage.ACLUserRunConfig: + description: ACLUserConfig contains ACL user authentication configuration. + properties: + password_env_var: + description: PasswordEnvVar is the environment variable containing the Redis + password. + type: string + username_env_var: + description: UsernameEnvVar is the environment variable containing the Redis + username. + type: string + type: object + github_com_stacklok_toolhive_pkg_authserver_storage.RedisRunConfig: + description: RedisConfig is the Redis-specific configuration when Type is "redis". + properties: + acl_user_config: + $ref: '#/components/schemas/github_com_stacklok_toolhive_pkg_authserver_storage.ACLUserRunConfig' + auth_type: + description: AuthType must be "aclUser" - only ACL user authentication is + supported. + type: string + dial_timeout: + description: DialTimeout is the timeout for establishing connections (e.g., + "5s"). + type: string + key_prefix: + description: KeyPrefix for multi-tenancy, typically "thv:auth:{ns}:{name}:". + type: string + read_timeout: + description: ReadTimeout is the timeout for read operations (e.g., "3s"). + type: string + sentinel_config: + $ref: '#/components/schemas/github_com_stacklok_toolhive_pkg_authserver_storage.SentinelRunConfig' + sentinel_tls: + $ref: '#/components/schemas/github_com_stacklok_toolhive_pkg_authserver_storage.RedisTLSRunConfig' + tls: + $ref: '#/components/schemas/github_com_stacklok_toolhive_pkg_authserver_storage.RedisTLSRunConfig' + write_timeout: + description: WriteTimeout is the timeout for write operations (e.g., "3s"). + type: string + type: object + github_com_stacklok_toolhive_pkg_authserver_storage.RedisTLSRunConfig: + description: |- + SentinelTLS configures TLS for Sentinel connections. + Falls back to TLS config when nil. + properties: + ca_cert_file: + description: CACertFile is the path to a PEM-encoded CA certificate file. + type: string + insecure_skip_verify: + description: InsecureSkipVerify skips certificate verification. + type: boolean + type: object + github_com_stacklok_toolhive_pkg_authserver_storage.RunConfig: + description: |- + Storage configures the storage backend for the auth server. + If nil, defaults to in-memory storage. + properties: + redis_config: + $ref: '#/components/schemas/github_com_stacklok_toolhive_pkg_authserver_storage.RedisRunConfig' + type: + description: Type specifies the storage backend type. Defaults to "memory". + type: string + type: object + github_com_stacklok_toolhive_pkg_authserver_storage.SentinelRunConfig: + description: SentinelConfig contains Sentinel-specific configuration. + properties: + db: + description: 'DB is the Redis database number (default: 0).' + type: integer + master_name: + description: MasterName is the name of the Redis Sentinel master. + type: string + sentinel_addrs: + description: SentinelAddrs is the list of Sentinel addresses (host:port). + items: + type: string + type: array + uniqueItems: false + type: object github_com_stacklok_toolhive_pkg_authz.Config: description: |- DEPRECATED: Middleware configuration. @@ -719,6 +799,47 @@ components: name: $ref: '#/components/schemas/github_com_stacklok_toolhive_pkg_client.ClientApp' type: object + github_com_stacklok_toolhive_pkg_container_runtime.WorkloadStatus: + description: Current status of the workload + enum: + - running + - stopped + - error + - starting + - stopping + - unhealthy + - removing + - unknown + - unauthenticated + - running + - stopped + - error + - starting + - stopping + - unhealthy + - removing + - unknown + - unauthenticated + - running + - stopped + - error + - starting + - stopping + - unhealthy + - removing + - unknown + - unauthenticated + type: string + x-enum-varnames: + - WorkloadStatusRunning + - WorkloadStatusStopped + - WorkloadStatusError + - WorkloadStatusStarting + - WorkloadStatusStopping + - WorkloadStatusUnhealthy + - WorkloadStatusRemoving + - WorkloadStatusUnknown + - WorkloadStatusUnauthenticated github_com_stacklok_toolhive_pkg_container_templates.RuntimeConfig: description: |- RuntimeConfig allows overriding the default runtime configuration @@ -785,18 +906,7 @@ components: restart) type: string status: - description: Status is the current status of the workload. - enum: - - running - - stopped - - error - - starting - - stopping - - unhealthy - - removing - - unknown - - unauthenticated - type: string + $ref: '#/components/schemas/github_com_stacklok_toolhive_pkg_container_runtime.WorkloadStatus' status_context: description: |- StatusContext provides additional context about the workload's status. @@ -809,13 +919,7 @@ components: type: array uniqueItems: false transport_type: - description: TransportType is the type of transport used for this workload. - enum: - - stdio - - sse - - streamable-http - - inspector - type: string + $ref: '#/components/schemas/github_com_stacklok_toolhive_pkg_transport_types.TransportType' url: description: URL is the URL of the workload exposed by the ToolHive proxy. type: string @@ -835,6 +939,16 @@ components: type: array uniqueItems: false type: object + github_com_stacklok_toolhive_pkg_ignore.Config: + description: IgnoreConfig contains configuration for ignore processing + properties: + loadGlobal: + description: Whether to load global ignore patterns + type: boolean + printOverlays: + description: Whether to print resolved overlay paths for debugging + type: boolean + type: object github_com_stacklok_toolhive_pkg_registry.OAuthPublicConfig: description: |- AuthConfig contains the non-secret OAuth configuration when auth is configured. @@ -946,7 +1060,7 @@ components: description: Host is the host for the HTTP proxy type: string ignore_config: - $ref: '#/components/schemas/ignore.Config' + $ref: '#/components/schemas/github_com_stacklok_toolhive_pkg_ignore.Config' image: description: Image is the Docker image to run type: string @@ -969,14 +1083,14 @@ components: MiddlewareConfigs contains the list of middleware to apply to the transport and the configuration for each middleware. items: - $ref: '#/components/schemas/types.MiddlewareConfig' + $ref: '#/components/schemas/github_com_stacklok_toolhive_pkg_transport_types.MiddlewareConfig' type: array uniqueItems: false name: description: Name is the name of the MCP server type: string oidc_config: - $ref: '#/components/schemas/auth.TokenValidatorConfig' + $ref: '#/components/schemas/github_com_stacklok_toolhive_pkg_auth.TokenValidatorConfig' permission_profile_name_or_path: description: PermissionProfileNameOrPath is the name or path of the permission profile @@ -985,13 +1099,7 @@ components: description: Port is the port for the HTTP proxy to listen on (host port) type: integer proxy_mode: - description: |- - ProxyMode is the proxy mode for stdio transport ("sse" or "streamable-http") - Note: "sse" is deprecated; use "streamable-http" instead. - enum: - - sse - - streamable-http - type: string + $ref: '#/components/schemas/github_com_stacklok_toolhive_pkg_transport_types.ProxyMode' publish: description: Publish lists ports to publish to the host in format "hostPort:containerPort" items: @@ -1051,13 +1159,7 @@ components: ToolsOverride is a map from an actual tool to its overridden name and/or description type: object transport: - description: Transport is the transport mode (stdio, sse, or streamable-http) - enum: - - stdio - - sse - - streamable-http - - inspector - type: string + $ref: '#/components/schemas/github_com_stacklok_toolhive_pkg_transport_types.TransportType' trust_proxy_headers: description: TrustProxyHeaders indicates whether to trust X-Forwarded-* headers from reverse proxies @@ -1352,6 +1454,53 @@ components: +optional type: boolean type: object + github_com_stacklok_toolhive_pkg_transport_types.MiddlewareConfig: + properties: + parameters: + description: |- + Parameters is a JSON object containing the middleware parameters. + It is stored as a raw message to allow flexible parameter types. + type: object + type: + description: Type is a string representing the middleware type. + type: string + type: object + github_com_stacklok_toolhive_pkg_transport_types.ProxyMode: + description: |- + 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. + enum: + - sse + - streamable-http + - sse + - streamable-http + type: string + x-enum-varnames: + - ProxyModeSSE + - ProxyModeStreamableHTTP + github_com_stacklok_toolhive_pkg_transport_types.TransportType: + description: Transport is the transport mode (stdio, sse, or streamable-http) + enum: + - stdio + - sse + - streamable-http + - inspector + - stdio + - sse + - streamable-http + - inspector + - stdio + - sse + - streamable-http + - inspector + type: string + x-enum-varnames: + - TransportTypeStdio + - TransportTypeSSE + - TransportTypeStreamableHTTP + - TransportTypeInspector github_com_stacklok_toolhive_pkg_webhook.Config: properties: failure_policy: @@ -1401,16 +1550,6 @@ components: WARNING: This should only be used for development/testing. type: boolean type: object - ignore.Config: - description: IgnoreConfig contains configuration for ignore processing - properties: - loadGlobal: - description: Whether to load global ignore patterns - type: boolean - printOverlays: - description: Whether to print resolved overlay paths for debugging - type: boolean - type: object permissions.InboundNetworkPermissions: description: Inbound defines inbound network permissions properties: @@ -2212,18 +2351,7 @@ components: description: Response containing workload status information properties: status: - description: Current status of the workload - enum: - - running - - stopped - - error - - starting - - stopping - - unhealthy - - removing - - unknown - - unauthenticated - type: string + $ref: '#/components/schemas/github_com_stacklok_toolhive_pkg_container_runtime.WorkloadStatus' type: object registry.EnvVar: properties: @@ -2613,97 +2741,6 @@ components: predicate_type: type: string type: object - storage.ACLUserRunConfig: - description: ACLUserConfig contains ACL user authentication configuration. - properties: - password_env_var: - description: PasswordEnvVar is the environment variable containing the Redis - password. - type: string - username_env_var: - description: UsernameEnvVar is the environment variable containing the Redis - username. - type: string - type: object - storage.RedisRunConfig: - description: RedisConfig is the Redis-specific configuration when Type is "redis". - properties: - acl_user_config: - $ref: '#/components/schemas/storage.ACLUserRunConfig' - auth_type: - description: AuthType must be "aclUser" - only ACL user authentication is - supported. - type: string - dial_timeout: - description: DialTimeout is the timeout for establishing connections (e.g., - "5s"). - type: string - key_prefix: - description: KeyPrefix for multi-tenancy, typically "thv:auth:{ns}:{name}:". - type: string - read_timeout: - description: ReadTimeout is the timeout for read operations (e.g., "3s"). - type: string - sentinel_config: - $ref: '#/components/schemas/storage.SentinelRunConfig' - sentinel_tls: - $ref: '#/components/schemas/storage.RedisTLSRunConfig' - tls: - $ref: '#/components/schemas/storage.RedisTLSRunConfig' - write_timeout: - description: WriteTimeout is the timeout for write operations (e.g., "3s"). - type: string - type: object - storage.RedisTLSRunConfig: - description: |- - SentinelTLS configures TLS for Sentinel connections. - Falls back to TLS config when nil. - properties: - ca_cert_file: - description: CACertFile is the path to a PEM-encoded CA certificate file. - type: string - insecure_skip_verify: - description: InsecureSkipVerify skips certificate verification. - type: boolean - type: object - storage.RunConfig: - description: |- - Storage configures the storage backend for the auth server. - If nil, defaults to in-memory storage. - properties: - redis_config: - $ref: '#/components/schemas/storage.RedisRunConfig' - type: - description: Type specifies the storage backend type. Defaults to "memory". - type: string - type: object - storage.SentinelRunConfig: - description: SentinelConfig contains Sentinel-specific configuration. - properties: - db: - description: 'DB is the Redis database number (default: 0).' - type: integer - master_name: - description: MasterName is the name of the Redis Sentinel master. - type: string - sentinel_addrs: - description: SentinelAddrs is the list of Sentinel addresses (host:port). - items: - type: string - type: array - uniqueItems: false - type: object - types.MiddlewareConfig: - properties: - parameters: - description: |- - Parameters is a JSON object containing the middleware parameters. - It is stored as a raw message to allow flexible parameter types. - type: object - type: - description: Type is a string representing the middleware type. - type: string - type: object externalDocs: description: "" url: ""