MCPServer 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

MCPServerSpec defines the desired state of MCPServer

args []string

Args are additional arguments to pass to the MCP server

audit object

Audit defines audit logging configuration for the MCP server

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 MCP server

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

backendReplicas integer

BackendReplicas is the desired number of MCP server backend pod replicas. This controls the backend Deployment (the MCP server container itself), independent of the proxy runner controlled by Replicas. When nil, the operator does not set Deployment.Spec.Replicas, leaving replica management to an HPA or other external controller.

format: int32

minimum: 0

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.

env []object

Env are environment variables to set in the MCP server container

name string required

Name of the environment variable

value string required

Value of the environment variable

externalAuthConfigRef object

ExternalAuthConfigRef references a MCPExternalAuthConfig resource for external authentication. The referenced MCPExternalAuthConfig must exist in the same namespace as this MCPServer.

name string required

Name is the name of the MCPExternalAuthConfig resource

groupRef object

GroupRef references the MCPGroup this server 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

image string required

Image is the container image for the MCP server

mcpPort integer

MCPPort is the port that MCP server listens to

format: int32

minimum: 1

maximum: 65535

oidcConfigRef object

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.

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"].

permissionProfile object

PermissionProfile defines the permission profile to use

key string

Key is the key in the ConfigMap that contains the permission profile Only used when Type is "configmap"

name string required

Name is the name of the permission profile If Type is "builtin", Name must be one of: "none", "network" If Type is "configmap", Name is the name of the ConfigMap

type string required

Type is the type of permission profile reference

enum: builtin, configmap

podTemplateSpec object

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.

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.

enum: sse, streamable-http

proxyPort integer

ProxyPort is the port to expose the proxy runner on

format: int32

minimum: 1

maximum: 65535

rateLimiting object

RateLimiting defines rate limiting configuration for the MCP server. Requires Redis session storage to be configured for distributed rate limiting.

perUser object

PerUser is a token bucket applied independently to each authenticated user at the server level. Requires authentication to be enabled. Each unique userID creates Redis keys that expire after 2x refillPeriod. Memory formula: unique_users_per_TTL_window * (1 + num_tools_with_per_user_limits) keys.

maxTokens integer required

MaxTokens is the maximum number of tokens (bucket capacity). This is also the burst size: the maximum number of requests that can be served instantaneously before the bucket is depleted.

format: int32

minimum: 1

refillPeriod string required

RefillPeriod is the duration to fully refill the bucket from zero to maxTokens. The effective refill rate is maxTokens / refillPeriod tokens per second. Format: Go duration string (e.g., "1m0s", "30s", "1h0m0s").

shared object

Shared is a token bucket shared across all users for the entire server.

maxTokens integer required

MaxTokens is the maximum number of tokens (bucket capacity). This is also the burst size: the maximum number of requests that can be served instantaneously before the bucket is depleted.

format: int32

minimum: 1

refillPeriod string required

tools []object

Tools defines per-tool rate limit overrides. Each entry applies additional rate limits to calls targeting a specific tool name. A request must pass both the server-level limit and the per-tool limit.

name string required

Name is the MCP tool name this limit applies to.

minLength: 1

perUser object

PerUser token bucket configuration for this tool.

maxTokens integer required

MaxTokens is the maximum number of tokens (bucket capacity). This is also the burst size: the maximum number of requests that can be served instantaneously before the bucket is depleted.

format: int32

minimum: 1

refillPeriod string required

shared object

Shared token bucket for this specific tool.

maxTokens integer required

MaxTokens is the maximum number of tokens (bucket capacity). This is also the burst size: the maximum number of requests that can be served instantaneously before the bucket is depleted.

format: int32

minimum: 1

refillPeriod string required

replicas integer

Replicas is the desired number of proxy runner (thv run) pod replicas. MCPServer creates two separate Deployments: one for the proxy runner and one for the MCP server backend. This field controls the proxy runner Deployment. When nil, the operator does not set Deployment.Spec.Replicas, leaving replica management to an HPA or other external controller.

format: int32

minimum: 0

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 MCP server 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)

secrets []object

Secrets are references to secrets to mount in the MCP server container

key string required

Key is the key in the secret itself

name string required

Name is the name of the secret

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

serviceAccount string

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

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

sessionStorage object

SessionStorage configures session storage for stateful horizontal scaling. When nil, no session storage is configured.

address string

Address is the Redis server address (required when provider is redis)

minLength: 1

db integer

DB is the Redis database number

format: int32

minimum: 0

keyPrefix string

KeyPrefix is an optional prefix for all Redis keys used by ToolHive

passwordRef object

PasswordRef is a reference to a Secret key containing the Redis password

key string required

Key is the key within the secret

name string required

Name is the name of the secret

provider string required

Provider is the session storage backend type

enum: memory, redis

telemetryConfigRef object

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.

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 MCPServer. Cross-namespace references are not supported for security and isolation reasons.

name string required

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

transport string

Transport is the transport method for the MCP server (stdio, streamable-http or sse)

enum: stdio, streamable-http, sse

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

volumes []object

Volumes are volumes to mount in the MCP server container

hostPath string required

HostPath is the path on the host to mount

mountPath string required

MountPath is the path in the container to mount to

name string required

Name is the name of the volume

readOnly boolean

ReadOnly specifies whether the volume should be mounted read-only

status object

MCPServerStatus defines the observed state of MCPServer

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 MCPServer'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

message string

Message provides additional information about the current phase

observedGeneration integer

ObservedGeneration reflects the generation most recently observed by the controller

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 MCPServer

enum: Pending, Ready, Failed, Terminating, Stopped

readyReplicas integer

ReadyReplicas is the number of ready proxy replicas

format: int32

telemetryConfigHash string

TelemetryConfigHash is the hash of the referenced MCPTelemetryConfig spec for change detection

toolConfigHash string

ToolConfigHash stores the hash of the referenced ToolConfig for change detection

url string

URL is the URL where the MCP server can be accessed