Skip to content

Update ToolHive reference docs for toolhive-operator-crds-0.0.83 #393

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jhrozek merged 1 commit into from
Dec 12, 2025
+31 −4
Merged

Update ToolHive reference docs for toolhive-operator-crds-0.0.83 #393

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 31 additions & 4 deletions static/api-specs/toolhive-crd-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -287,6 +287,22 @@ _Appears in:_
| `url` _string_ | URL is the URL of the backend MCPServer | | |


#### ElicitationResponseHandler



ElicitationResponseHandler defines how to handle user responses to elicitation requests



_Appears in:_
- [WorkflowStep](#workflowstep)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `action` _string_ | Action defines the action to take when the user declines or cancels<br />- skip_remaining: Skip remaining steps in the workflow<br />- abort: Abort the entire workflow execution<br />- continue: Continue to the next step | abort | Enum: [skip_remaining abort continue] <br /> |




#### EnvVar
Expand Down Expand Up @@ -359,6 +375,7 @@ _Appears in:_
| --- | --- |
| `tokenExchange` | ExternalAuthTypeTokenExchange is the type for RFC-8693 token exchange<br /> |
| `headerInjection` | ExternalAuthTypeHeaderInjection is the type for custom header injection<br /> |
| `unauthenticated` | ExternalAuthTypeUnauthenticated is the type for no authentication<br />This should only be used for backends on trusted networks (e.g., localhost, VPC)<br />or when authentication is handled by network-level security<br /> |


#### FailureHandlingConfig
Expand Down Expand Up @@ -495,6 +512,7 @@ _Appears in:_
| `jwksAllowPrivateIP` _boolean_ | JWKSAllowPrivateIP allows JWKS/OIDC endpoints on private IP addresses<br />Use with caution - only enable for trusted internal IDPs | false | |
| `protectedResourceAllowPrivateIP` _boolean_ | ProtectedResourceAllowPrivateIP allows protected resource endpoint on private IP addresses<br />Use with caution - only enable for trusted internal IDPs or testing | false | |
| `insecureAllowHTTP` _boolean_ | InsecureAllowHTTP allows HTTP (non-HTTPS) OIDC issuers for development/testing<br />WARNING: This is insecure and should NEVER be used in production<br />Only enable for local development, testing, or trusted internal networks | false | |
| `scopes` _string array_ | Scopes is the list of OAuth scopes to advertise in the well-known endpoint (RFC 9728)<br />If empty, defaults to ["openid"] | | |


#### KubernetesOIDCConfig
Expand Down Expand Up @@ -579,7 +597,7 @@ _Appears in:_

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `type` _[ExternalAuthType](#externalauthtype)_ | Type is the type of external authentication to configure | | Enum: [tokenExchange headerInjection] <br />Required: \{\} <br /> |
| `type` _[ExternalAuthType](#externalauthtype)_ | Type is the type of external authentication to configure | | Enum: [tokenExchange headerInjection unauthenticated] <br />Required: \{\} <br /> |
| `tokenExchange` _[TokenExchangeConfig](#tokenexchangeconfig)_ | TokenExchange configures RFC-8693 OAuth 2.0 Token Exchange<br />Only used when Type is "tokenExchange" | | |
| `headerInjection` _[HeaderInjectionConfig](#headerinjectionconfig)_ | HeaderInjection configures custom HTTP header injection<br />Only used when Type is "headerInjection" | | |

Expand Down Expand Up @@ -693,8 +711,10 @@ _Appears in:_
| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `phase` _[MCPGroupPhase](#mcpgroupphase)_ | Phase indicates current state | Pending | Enum: [Ready Pending Failed] <br /> |
| `servers` _string array_ | Servers lists server names in this group | | |
| `serverCount` _integer_ | ServerCount is the number of servers | | |
| `servers` _string array_ | Servers lists MCPServer names in this group | | |
| `serverCount` _integer_ | ServerCount is the number of MCPServers | | |
| `remoteProxies` _string array_ | RemoteProxies lists MCPRemoteProxy names in this group | | |
| `remoteProxyCount` _integer_ | RemoteProxyCount is the number of MCPRemoteProxies | | |
| `conditions` _[Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#condition-v1-meta) array_ | Conditions represent observations | | |


Expand Down Expand Up @@ -940,6 +960,7 @@ _Appears in:_
| `resources` _[ResourceRequirements](#resourcerequirements)_ | Resources defines the resource requirements for the proxy container | | |
| `trustProxyHeaders` _boolean_ | TrustProxyHeaders indicates whether to trust X-Forwarded-* headers from reverse proxies<br />When enabled, the proxy will use X-Forwarded-Proto, X-Forwarded-Host, X-Forwarded-Port,<br />and X-Forwarded-Prefix headers to construct endpoint URLs | false | |
| `resourceOverrides` _[ResourceOverrides](#resourceoverrides)_ | ResourceOverrides allows overriding annotations and labels for resources created by the operator | | |
| `groupRef` _string_ | GroupRef is the name of the MCPGroup this proxy belongs to<br />Must reference an existing MCPGroup in the same namespace | | |


#### MCPRemoteProxyStatus
Expand Down Expand Up @@ -1294,6 +1315,7 @@ _Appears in:_

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `logLevel` _string_ | LogLevel sets the logging level for the Virtual MCP server.<br />Set to "debug" to enable debug logging. When not set, defaults to info level. | | Enum: [debug] <br /> |
| `timeouts` _[TimeoutConfig](#timeoutconfig)_ | Timeouts configures timeout settings | | |
| `failureHandling` _[FailureHandlingConfig](#failurehandlingconfig)_ | FailureHandling configures failure handling behavior | | |

Expand Down Expand Up @@ -1695,6 +1717,7 @@ TelemetryConfig defines observability configuration for the MCP server
_Appears in:_
- [MCPRemoteProxySpec](#mcpremoteproxyspec)
- [MCPServerSpec](#mcpserverspec)
- [VirtualMCPServerSpec](#virtualmcpserverspec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
Expand Down Expand Up @@ -1973,6 +1996,7 @@ _Appears in:_
| `operational` _[OperationalConfig](#operationalconfig)_ | Operational defines operational settings like timeouts and health checks | | |
| `serviceType` _string_ | ServiceType specifies the Kubernetes service type for the Virtual MCP server | ClusterIP | Enum: [ClusterIP NodePort LoadBalancer] <br /> |
| `podTemplateSpec` _[RawExtension](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#rawextension-runtime-pkg)_ | PodTemplateSpec defines the pod template to use for the Virtual MCP server<br />This allows for customizing the pod configuration beyond what is provided by the other fields.<br />Note that to modify the specific container the Virtual MCP server runs in, you must specify<br />the 'vmcp' container name in the PodTemplateSpec.<br />This field accepts a PodTemplateSpec object as JSON/YAML. | | Type: object <br /> |
| `telemetry` _[TelemetryConfig](#telemetryconfig)_ | Telemetry configures OpenTelemetry-based observability for the Virtual MCP server<br />including distributed tracing, OTLP metrics export, and Prometheus metrics endpoint | | |


#### VirtualMCPServerStatus
Expand Down Expand Up @@ -2033,13 +2057,16 @@ _Appears in:_
| `id` _string_ | ID is the unique identifier for this step | | Required: \{\} <br /> |
| `type` _string_ | Type is the step type (tool, elicitation, etc.) | tool | Enum: [tool elicitation] <br /> |
| `tool` _string_ | Tool is the tool to call (format: "workload.tool_name")<br />Only used when Type is "tool" | | |
| `arguments` _object (keys:string, values:string)_ | Arguments is a map of argument templates<br />Supports Go template syntax with .params and .steps | | |
| `arguments` _[RawExtension](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#rawextension-runtime-pkg)_ | Arguments is a map of argument values with template expansion support.<br />Supports Go template syntax with .params and .steps for string values.<br />Non-string values (integers, booleans, arrays, objects) are passed as-is.<br />Note: the templating is only supported on the first level of the key-value pairs. | | Type: object <br /> |
| `message` _string_ | Message is the elicitation message<br />Only used when Type is "elicitation" | | |
| `schema` _[RawExtension](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#rawextension-runtime-pkg)_ | Schema defines the expected response schema for elicitation | | Type: object <br /> |
| `onDecline` _[ElicitationResponseHandler](#elicitationresponsehandler)_ | OnDecline defines the action to take when the user explicitly declines the elicitation<br />Only used when Type is "elicitation" | | |
| `onCancel` _[ElicitationResponseHandler](#elicitationresponsehandler)_ | OnCancel defines the action to take when the user cancels/dismisses the elicitation<br />Only used when Type is "elicitation" | | |
| `dependsOn` _string array_ | DependsOn lists step IDs that must complete before this step | | |
| `condition` _string_ | Condition is a template expression that determines if the step should execute | | |
| `onError` _[ErrorHandling](#errorhandling)_ | OnError defines error handling behavior | | |
| `timeout` _string_ | Timeout is the maximum execution time for this step | | |
| `defaultResults` _object (keys:string, values:[RawExtension](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#rawextension-runtime-pkg))_ | DefaultResults provides fallback output values when this step is skipped<br />(due to condition evaluating to false) or fails (when onError.action is "continue").<br />Each key corresponds to an output field name referenced by downstream steps.<br />Required if the step may be skipped AND downstream steps reference this step's output. | | Schemaless: \{\} <br /> |


#### WorkloadToolConfig
Expand Down