MCPWebhookConfig
MCPWebhookConfig is a ToolHive custom resource.
API: toolhive.stacklok.dev/v1alpha1
· Scope: Namespaced · Short names: mwc
Example
apiVersion: toolhive.stacklok.dev/v1alpha1
kind: MCPWebhookConfig
metadata:
name: my-mcpwebhookconfig
namespace: default
spec: {}
Schema
spec
MCPWebhookConfigSpec defines the desired state of MCPWebhookConfig
| Field | Type | Description |
|---|---|---|
mutating | object[] | Mutating webhooks are called to transform MCP requests before processing. |
validating | object[] | Validating webhooks are called to approve or deny MCP requests. |
spec.mutating[]
Mutating webhooks are called to transform MCP requests before processing.
| Field | Type | Description |
|---|---|---|
failurePolicy | string | FailurePolicy defines how to handle errors when communicating with the webhook. Supported values: "fail", "ignore". Defaults to "fail". default "fail" · enum: fail | ignore |
hmacSecretRef | object | HMACSecretRef references a Kubernetes Secret containing the HMAC signing key used to sign the webhook payload. If set, the X-Toolhive-Signature header will be injected. |
namerequired | string | Name is a unique identifier for this webhook minLength 1 · maxLength 63 |
timeout | string | Timeout configures the maximum time to wait for the webhook to respond. Defaults to 10s if not specified. Maximum is 30s. format duration |
tlsConfig | object | TLSConfig contains optional TLS configuration for the webhook connection. |
urlrequired | string | URL is the endpoint to call for this webhook. Must be an HTTP/HTTPS URL. format uri |
spec.mutating.hmacSecretRef
HMACSecretRef references a Kubernetes Secret containing the HMAC signing key used to sign the webhook payload. If set, the X-Toolhive-Signature header will be injected.
| Field | Type | Description |
|---|---|---|
keyrequired | string | Key is the key within the secret |
namerequired | string | Name is the name of the secret |
spec.mutating.tlsConfig
TLSConfig contains optional TLS configuration for the webhook connection.
| Field | Type | Description |
|---|---|---|
caSecretRef | object | CASecretRef references a Secret containing the CA certificate bundle used to verify the webhook server's certificate. Contains a bundle of PEM-encoded X.509 certificates. |
clientCertSecretRef | object | ClientCertSecretRef references a Secret containing the client certificate for mTLS authentication. The referenced key must contain a PEM-encoded client certificate. Use ClientKeySecretRef to provide the corresponding private key. |
clientKeySecretRef | object | ClientKeySecretRef references a Secret containing the private key for the client certificate. Required when ClientCertSecretRef is set to enable mTLS. |
insecureSkipVerify | boolean | InsecureSkipVerify disables server certificate verification. WARNING: This should only be used for development/testing and not in production environments. |
spec.mutating.tlsConfig.caSecretRef
CASecretRef references a Secret containing the CA certificate bundle used to verify the webhook server's certificate. Contains a bundle of PEM-encoded X.509 certificates.
| Field | Type | Description |
|---|---|---|
keyrequired | string | Key is the key within the secret |
namerequired | string | Name is the name of the secret |
spec.mutating.tlsConfig.clientCertSecretRef
ClientCertSecretRef references a Secret containing the client certificate for mTLS authentication. The referenced key must contain a PEM-encoded client certificate. Use ClientKeySecretRef to provide the corresponding private key.
| Field | Type | Description |
|---|---|---|
keyrequired | string | Key is the key within the secret |
namerequired | string | Name is the name of the secret |
spec.mutating.tlsConfig.clientKeySecretRef
ClientKeySecretRef references a Secret containing the private key for the client certificate. Required when ClientCertSecretRef is set to enable mTLS.
| Field | Type | Description |
|---|---|---|
keyrequired | string | Key is the key within the secret |
namerequired | string | Name is the name of the secret |
spec.validating[]
Validating webhooks are called to approve or deny MCP requests.
| Field | Type | Description |
|---|---|---|
failurePolicy | string | FailurePolicy defines how to handle errors when communicating with the webhook. Supported values: "fail", "ignore". Defaults to "fail". default "fail" · enum: fail | ignore |
hmacSecretRef | object | HMACSecretRef references a Kubernetes Secret containing the HMAC signing key used to sign the webhook payload. If set, the X-Toolhive-Signature header will be injected. |
namerequired | string | Name is a unique identifier for this webhook minLength 1 · maxLength 63 |
timeout | string | Timeout configures the maximum time to wait for the webhook to respond. Defaults to 10s if not specified. Maximum is 30s. format duration |
tlsConfig | object | TLSConfig contains optional TLS configuration for the webhook connection. |
urlrequired | string | URL is the endpoint to call for this webhook. Must be an HTTP/HTTPS URL. format uri |
spec.validating.hmacSecretRef
HMACSecretRef references a Kubernetes Secret containing the HMAC signing key used to sign the webhook payload. If set, the X-Toolhive-Signature header will be injected.
| Field | Type | Description |
|---|---|---|
keyrequired | string | Key is the key within the secret |
namerequired | string | Name is the name of the secret |
spec.validating.tlsConfig
TLSConfig contains optional TLS configuration for the webhook connection.
| Field | Type | Description |
|---|---|---|
caSecretRef | object | CASecretRef references a Secret containing the CA certificate bundle used to verify the webhook server's certificate. Contains a bundle of PEM-encoded X.509 certificates. |
clientCertSecretRef | object | ClientCertSecretRef references a Secret containing the client certificate for mTLS authentication. The referenced key must contain a PEM-encoded client certificate. Use ClientKeySecretRef to provide the corresponding private key. |
clientKeySecretRef | object | ClientKeySecretRef references a Secret containing the private key for the client certificate. Required when ClientCertSecretRef is set to enable mTLS. |
insecureSkipVerify | boolean | InsecureSkipVerify disables server certificate verification. WARNING: This should only be used for development/testing and not in production environments. |
spec.validating.tlsConfig.caSecretRef
CASecretRef references a Secret containing the CA certificate bundle used to verify the webhook server's certificate. Contains a bundle of PEM-encoded X.509 certificates.
| Field | Type | Description |
|---|---|---|
keyrequired | string | Key is the key within the secret |
namerequired | string | Name is the name of the secret |
spec.validating.tlsConfig.clientCertSecretRef
ClientCertSecretRef references a Secret containing the client certificate for mTLS authentication. The referenced key must contain a PEM-encoded client certificate. Use ClientKeySecretRef to provide the corresponding private key.
| Field | Type | Description |
|---|---|---|
keyrequired | string | Key is the key within the secret |
namerequired | string | Name is the name of the secret |
spec.validating.tlsConfig.clientKeySecretRef
ClientKeySecretRef references a Secret containing the private key for the client certificate. Required when ClientCertSecretRef is set to enable mTLS.
| Field | Type | Description |
|---|---|---|
keyrequired | string | Key is the key within the secret |
namerequired | string | Name is the name of the secret |
status
MCPWebhookConfigStatus defines the observed state of MCPWebhookConfig
| Field | Type | Description |
|---|---|---|
conditions | object[] | Conditions represent the latest available observations |
configHash | string | ConfigHash is a hash of the spec, used for detecting changes |
observedGeneration | integer | ObservedGeneration is the last observed generation corresponding to the current status format int64 |
referencingWorkloads | object[] | ReferencingWorkloads is a list of workload resources that reference this MCPWebhookConfig. Each entry identifies the workload by kind and name. |
status.conditions[]
Conditions represent the latest available observations
| Field | Type | Description |
|---|---|---|
lastTransitionTimerequired | string | lastTransitionTime is the last time the condition transitioned from one status to another. This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable. format date-time |
messagerequired | string | message is a human readable message indicating details about the transition. This may be an empty string. maxLength 32768 |
observedGeneration | integer | observedGeneration represents the .metadata.generation that the condition was set based upon. For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date with respect to the current state of the instance. format int64 · min 0 |
reasonrequired | string | reason contains a programmatic identifier indicating the reason for the condition's last transition. Producers of specific condition types may define expected values and meanings for this field, and whether the values are considered a guaranteed API. The value should be a CamelCase string. This field may not be empty. pattern ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$ · minLength 1 · maxLength 1024 |
statusrequired | string | status of the condition, one of True, False, Unknown. enum: True | False | Unknown |
typerequired | string | type of condition in CamelCase or in foo.example.com/CamelCase. pattern ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$ · maxLength 316 |
status.referencingWorkloads[]
ReferencingWorkloads is a list of workload resources that reference this MCPWebhookConfig. Each entry identifies the workload by kind and name.
| Field | Type | Description |
|---|---|---|
kindrequired | string | Kind is the type of workload resource enum: MCPServer | VirtualMCPServer | MCPRemoteProxy |
namerequired | string | Name is the name of the workload resource minLength 1 |
Related resources
Referenced by:
- MCPServer - via
spec.webhookConfigRef