MCPRemoteProxy

MCPRemoteProxy fronts a remote MCP server (reachable over HTTPS) with the same authentication, telemetry, and tool-filtering features that the operator applies to containerized servers. Use this when you want to apply ToolHive policies to a third-party hosted MCP endpoint.

API: toolhive.stacklok.dev/v1beta1 · Scope: Namespaced · Short names: rp, mcprp

Example

mcpremoteproxy.yaml

apiVersion: toolhive.stacklok.dev/v1beta1
kind: MCPRemoteProxy
metadata:
  name: my-mcpremoteproxy
  namespace: default
spec:
  remoteUrl: <string>

Schema

spec

MCPRemoteProxySpec defines the desired state of MCPRemoteProxy

Field	Type	Description
audit	object	Audit defines audit logging configuration for the proxy
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).
authzConfig	object	AuthzConfig defines authorization policy configuration for the proxy
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.
groupRef	object	GroupRef references the MCPGroup this proxy belongs to. The referenced MCPGroup must be in the same namespace.
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.
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.
proxyPort	integer	ProxyPort is the port to expose the MCP proxy on default 8080 · format int32 · min 1 · max 65535
remoteUrlrequired	string	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
resources	object	Resources defines the resource requirements for the proxy container
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. default "ClientIP" · 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.
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.
transport	string	Transport is the transport method for the remote proxy (sse or streamable-http) default "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 default false

spec.audit

Audit defines audit logging configuration for the proxy

Field	Type	Description
enabled	boolean	Enabled controls whether audit logging is enabled When true, enables audit logging with default configuration default false

↑ Back to spec

spec.authServerRef

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).

Field	Type	Description
kindrequired	string	Kind identifies the type of the referenced resource. default "MCPExternalAuthConfig" · enum: MCPExternalAuthConfig
namerequired	string	Name is the name of the referenced resource in the same namespace. minLength 1

↑ Back to spec

spec.authzConfig

AuthzConfig defines authorization policy configuration for the proxy

Field	Type	Description
configMap	object	ConfigMap references a ConfigMap containing authorization configuration Only used when Type is "configMap"
inline	object	Inline contains direct authorization configuration Only used when Type is "inline"
typerequired	string	Type is the type of authorization configuration default "configMap" · enum: configMap | inline

↑ Back to spec

spec.authzConfig.configMap

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

Field	Type	Description
key	string	Key is the key in the ConfigMap that contains the authorization configuration default "authz.json"
namerequired	string	Name is the name of the ConfigMap

↑ Back to spec.authzConfig

spec.authzConfig.inline

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

Field	Type	Description
entitiesJson	string	EntitiesJSON is a JSON string representing Cedar entities default "[]"
policiesrequired	string[]	Policies is a list of Cedar policy strings

↑ Back to spec.authzConfig

spec.externalAuthConfigRef

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.

Field	Type	Description
namerequired	string	Name is the name of the MCPExternalAuthConfig resource

↑ Back to spec

spec.groupRef

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

Field	Type	Description
namerequired	string	Name is the name of the MCPGroup resource in the same namespace minLength 1

↑ Back to spec

spec.headerForward

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.

Field	Type	Description
addHeadersFromSecret	object[]	AddHeadersFromSecret references Kubernetes Secrets for sensitive header values.
addPlaintextHeaders	map<string, string>	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.

↑ Back to spec

spec.headerForward.addHeadersFromSecret[]

AddHeadersFromSecret references Kubernetes Secrets for sensitive header values.

Field	Type	Description
headerNamerequired	string	HeaderName is the HTTP header name (e.g., "X-API-Key") minLength 1 · maxLength 255
valueSecretRefrequired	object	ValueSecretRef references the Secret and key containing the header value

↑ Back to spec.headerForward

spec.headerForward.addHeadersFromSecret.valueSecretRef

ValueSecretRef references the Secret and key containing the header value

Field	Type	Description
keyrequired	string	Key is the key within the secret
namerequired	string	Name is the name of the secret

↑ Back to spec.headerForward.addHeadersFromSecret

spec.oidcConfigRef

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.

Field	Type	Description
audiencerequired	string	Audience is the expected audience for token validation. This MUST be unique per server to prevent token replay attacks. minLength 1
namerequired	string	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"].

↑ Back to spec

spec.resourceOverrides

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

Field	Type	Description
proxyDeployment	object	ProxyDeployment defines overrides for the Proxy Deployment resource (toolhive proxy)
proxyService	object	ProxyService defines overrides for the Proxy Service resource (points to the proxy deployment)

↑ Back to spec

spec.resourceOverrides.proxyDeployment

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

Field	Type	Description
annotations	map<string, string>	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
imagePullSecrets	object[]	ImagePullSecrets allows specifying image pull secrets for the proxy runner These are applied to both the Deployment and the ServiceAccount
labels	map<string, string>	Labels to add or override on the resource
podTemplateMetadataOverrides	object	ResourceMetadataOverrides defines metadata overrides for a resource

↑ Back to spec.resourceOverrides

spec.resourceOverrides.proxyDeployment.env[]

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

Field	Type	Description
namerequired	string	Name of the environment variable
valuerequired	string	Value of the environment variable

↑ Back to spec.resourceOverrides.proxyDeployment

spec.resourceOverrides.proxyDeployment.imagePullSecrets[]

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

Field	Type	Description
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 default ""

↑ Back to spec.resourceOverrides.proxyDeployment

spec.resourceOverrides.proxyDeployment.podTemplateMetadataOverrides

ResourceMetadataOverrides defines metadata overrides for a resource

Field	Type	Description
annotations	map<string, string>	Annotations to add or override on the resource
labels	map<string, string>	Labels to add or override on the resource

↑ Back to spec.resourceOverrides.proxyDeployment

spec.resourceOverrides.proxyService

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

Field	Type	Description
annotations	map<string, string>	Annotations to add or override on the resource
labels	map<string, string>	Labels to add or override on the resource

↑ Back to spec.resourceOverrides

spec.resources

Resources defines the resource requirements for the proxy container

Field	Type	Description
limits	object	Limits describes the maximum amount of compute resources allowed
requests	object	Requests describes the minimum amount of compute resources required

↑ Back to spec

spec.resources.limits

Limits describes the maximum amount of compute resources allowed

Field	Type	Description
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)

↑ Back to spec.resources

spec.resources.requests

Requests describes the minimum amount of compute resources required

Field	Type	Description
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)

↑ Back to spec.resources

spec.telemetryConfigRef

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.

Field	Type	Description
namerequired	string	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.

↑ Back to spec

spec.toolConfigRef

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.

Field	Type	Description
namerequired	string	Name is the name of the MCPToolConfig resource in the same namespace

↑ Back to spec

status

MCPRemoteProxyStatus defines the observed state of MCPRemoteProxy

Field	Type	Description
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
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

status.conditions[]

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

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

↑ Back to status

Related resources

References:

• MCPExternalAuthConfig - via spec.authServerRef, spec.externalAuthConfigRef
• MCPGroup - via spec.groupRef
• MCPOIDCConfig - via spec.oidcConfigRef
• MCPTelemetryConfig - via spec.telemetryConfigRef
• MCPToolConfig - via spec.toolConfigRef