MCPRemoteProxy v1beta1 — toolhive.stacklok.dev

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

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

metadata object

spec object

MCPRemoteProxySpec defines the desired state of MCPRemoteProxy

audit object

Audit defines audit logging configuration for the proxy

enabled boolean

Enabled controls whether audit logging is enabled When true, enables audit logging with default configuration

authServerRef object

AuthServerRef optionally references a resource that configures an embedded OAuth 2.0/OIDC authorization server to authenticate MCP clients. Currently the only supported kind is MCPExternalAuthConfig (type: embeddedAuthServer).

kind string required

Kind identifies the type of the referenced resource.

enum: MCPExternalAuthConfig

name string required

Name is the name of the referenced resource in the same namespace.

minLength: 1

authzConfig object

AuthzConfig defines authorization policy configuration for the proxy

configMap object

ConfigMap references a ConfigMap containing authorization configuration Only used when Type is "configMap"

key string

Key is the key in the ConfigMap that contains the authorization configuration

name string required

Name is the name of the ConfigMap

inline object

Inline contains direct authorization configuration Only used when Type is "inline"

entitiesJson string

EntitiesJSON is a JSON string representing Cedar entities

policies []string required

Policies is a list of Cedar policy strings

minItems: 1

type string required

Type is the type of authorization configuration

enum: configMap, inline

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.

externalAuthConfigRef object

ExternalAuthConfigRef references a MCPExternalAuthConfig resource for token exchange. When specified, the proxy will exchange validated incoming tokens for remote service tokens. The referenced MCPExternalAuthConfig must exist in the same namespace as this MCPRemoteProxy.

name string required

Name is the name of the MCPExternalAuthConfig resource

groupRef object

GroupRef references the MCPGroup this proxy belongs to. The referenced MCPGroup must be in the same namespace.

name string required

Name is the name of the MCPGroup resource in the same namespace

minLength: 1

headerForward object

HeaderForward configures headers to inject into requests to the remote MCP server. Use this to add custom headers like X-Tenant-ID or correlation IDs.

addHeadersFromSecret []object

AddHeadersFromSecret references Kubernetes Secrets for sensitive header values.

headerName string required

HeaderName is the HTTP header name (e.g., "X-API-Key")

minLength: 1

maxLength: 255

valueSecretRef object required

ValueSecretRef references the Secret and key containing the header value

key string required

Key is the key within the secret

name string required

Name is the name of the secret

addPlaintextHeaders object

AddPlaintextHeaders is a map of header names to literal values to inject into requests. WARNING: Values are stored in plaintext and visible via kubectl commands. Use addHeadersFromSecret for sensitive data like API keys or tokens.

oidcConfigRef object

OIDCConfigRef references a shared MCPOIDCConfig resource for OIDC authentication. The referenced MCPOIDCConfig must exist in the same namespace as this MCPRemoteProxy. Per-server overrides (audience, scopes) are specified here; shared provider config lives in the MCPOIDCConfig resource.

audience string required

Audience is the expected audience for token validation. This MUST be unique per server to prevent token replay attacks.

minLength: 1

name string required

Name is the name of the MCPOIDCConfig resource

minLength: 1

resourceUrl string

ResourceURL is the public URL for OAuth protected resource metadata (RFC 9728). When the server is exposed via Ingress or gateway, set this to the external URL that MCP clients connect to. If not specified, defaults to the internal Kubernetes service URL.

scopes []string

Scopes is the list of OAuth scopes to advertise in the well-known endpoint (RFC 9728). If empty, defaults to ["openid"].

proxyPort integer

ProxyPort is the port to expose the MCP proxy on

format: int32

minimum: 1

maximum: 65535

remoteUrl string required

RemoteURL is the URL of the remote MCP server to proxy

pattern: ^https?://

resourceOverrides object

ResourceOverrides allows overriding annotations and labels for resources created by the operator

proxyDeployment object

ProxyDeployment defines overrides for the Proxy Deployment resource (toolhive proxy)

annotations object

Annotations to add or override on the resource

env []object

Env are environment variables to set in the proxy container (thv run process) These affect the toolhive proxy itself, not the MCP server it manages Use TOOLHIVE_DEBUG=true to enable debug logging in the proxy

name string required

Name of the environment variable

value string required

Value of the environment variable

imagePullSecrets []object

ImagePullSecrets allows specifying image pull secrets for the proxy runner These are applied to both the Deployment and the ServiceAccount

name string

Name of the referent. This field is effectively required, but due to backwards compatibility is allowed to be empty. Instances of this type with an empty value here are almost certainly wrong. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names

labels object

Labels to add or override on the resource

podTemplateMetadataOverrides object

ResourceMetadataOverrides defines metadata overrides for a resource

annotations object

Annotations to add or override on the resource

labels object

Labels to add or override on the resource

proxyService object

ProxyService defines overrides for the Proxy Service resource (points to the proxy deployment)

annotations object

Annotations to add or override on the resource

labels object

Labels to add or override on the resource

resources object

Resources defines the resource requirements for the proxy container

limits object

Limits describes the maximum amount of compute resources allowed

cpu string

CPU is the CPU limit in cores (e.g., "500m" for 0.5 cores)

memory string

Memory is the memory limit in bytes (e.g., "64Mi" for 64 megabytes)

requests object

Requests describes the minimum amount of compute resources required

cpu string

CPU is the CPU limit in cores (e.g., "500m" for 0.5 cores)

memory string

Memory is the memory limit in bytes (e.g., "64Mi" for 64 megabytes)

serviceAccount string

ServiceAccount is the name of an already existing service account to use by the proxy. If not specified, a ServiceAccount will be created automatically and used by the proxy.

sessionAffinity string

SessionAffinity controls whether the Service routes repeated client connections to the same pod. MCP protocols (SSE, streamable-http) are stateful, so ClientIP is the default. Set to "None" for stateless servers or when using an external load balancer with its own affinity.

enum: ClientIP, None

telemetryConfigRef object

TelemetryConfigRef references an MCPTelemetryConfig resource for shared telemetry configuration. The referenced MCPTelemetryConfig must exist in the same namespace as this MCPRemoteProxy. Cross-namespace references are not supported for security and isolation reasons.

name string required

Name is the name of the MCPTelemetryConfig resource

minLength: 1

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.

toolConfigRef object

ToolConfigRef references a MCPToolConfig resource for tool filtering and renaming. The referenced MCPToolConfig must exist in the same namespace as this MCPRemoteProxy. Cross-namespace references are not supported for security and isolation reasons. If specified, this allows filtering and overriding tools from the remote MCP server.

name string required

Name is the name of the MCPToolConfig resource in the same namespace

transport string

Transport is the transport method for the remote proxy (sse or streamable-http)

enum: sse, streamable-http

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

status object

MCPRemoteProxyStatus defines the observed state of MCPRemoteProxy

authServerConfigHash string

AuthServerConfigHash is the hash of the referenced authServerRef spec, used to detect configuration changes and trigger reconciliation.

conditions []object

Conditions represent the latest available observations of the MCPRemoteProxy's state

lastTransitionTime string required

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

message string required

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

minimum: 0

reason string required

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

status string required

status of the condition, one of True, False, Unknown.

enum: True, False, Unknown

type string required

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

externalAuthConfigHash string

ExternalAuthConfigHash is the hash of the referenced MCPExternalAuthConfig spec

externalUrl string

ExternalURL is the external URL where the proxy can be accessed (if exposed externally)

message string

Message provides additional information about the current phase

observedGeneration integer

ObservedGeneration reflects the generation of the most recently observed MCPRemoteProxy

format: int64

oidcConfigHash string

OIDCConfigHash is the hash of the referenced MCPOIDCConfig spec for change detection

phase string

Phase is the current phase of the MCPRemoteProxy

enum: Pending, Ready, Failed, Terminating

telemetryConfigHash string

TelemetryConfigHash stores the hash of the referenced MCPTelemetryConfig for change detection

toolConfigHash string

ToolConfigHash stores the hash of the referenced ToolConfig for change detection

url string

URL is the internal cluster URL where the proxy can be accessed