API Reference¶

Packages¶

mcp.x-k8s.io/v1alpha1

mcp.x-k8s.io/v1alpha1¶

Package v1alpha1 contains API Schema definitions for the mcp v1alpha1 API group.

Resource Types¶

MCPServer

ContainerImageSource¶

ContainerImageSource defines a container image source.

Appears in: - Source

Field	Description	Default	Validation
`ref` string	Ref is the container image containing the MCP server implementation. Must be a valid OCI image reference. Examples: - ghcr.io/modelcontextprotocol/servers/filesystem:latest - ghcr.io/modelcontextprotocol/servers/github:v1.0.0 - custom-registry.io/my-mcp-server:1.2.3 - custom-registry.io/my-mcp-server@sha256:1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef		MaxLength: 1000 MinLength: 1 Required: {}

HealthConfig¶

HealthConfig defines health check configuration for the MCP server. If not specified, no health probes will be configured.

The probes are passed directly to the Deployment's container spec without any transformation, providing full access to the Kubernetes Probe API. This includes all probe types (httpGet, tcpSocket, exec, grpc) and all configuration options (initialDelaySeconds, periodSeconds, timeoutSeconds, successThreshold, failureThreshold).

Validation: - MinProperties: 1

Appears in: - RuntimeConfig

Field	Description	Default	Validation
`livenessProbe` Probe	LivenessProbe defines the liveness probe for the MCP server container. Kubernetes uses liveness probes to know when to restart a container. If not specified, no liveness probe will be configured. This probe is passed directly to the container spec without transformation, providing full compatibility with the Kubernetes Probe API.		Optional: {}
`readinessProbe` Probe	ReadinessProbe defines the readiness probe for the MCP server container. Kubernetes uses readiness probes to know when a container is ready to start accepting traffic. If not specified, no readiness probe will be configured. This probe is passed directly to the container spec without transformation, providing full compatibility with the Kubernetes Probe API.		Optional: {}

MCPServer¶

MCPServer runs a Model Context Protocol (MCP) server in Kubernetes.

MCPServer creates and manages a Deployment and Service to run an MCP server from a container image. The MCP server exposes tools, resources, and prompts that AI applications can use via the Model Context Protocol.

Example:

apiVersion: mcp.x-k8s.io/v1alpha1
kind: MCPServer
metadata:
  name: example
spec:
  source:
    type: ContainerImage
    containerImage:
      ref: example-mcp-image
  config:
    port: 8080

The controller manages Deployment and Service resources with the same name as the MCPServer, using ownerReferences to establish ownership. The controller will reject updates to resources owned by other controllers or resources with no controller owner (to prevent silent overwrites of manually-created resources), but will adopt orphaned resources from a deleted MCPServer with the same name to enable seamless recreation.

Field	Description	Validation
`apiVersion` string	`mcp.x-k8s.io/v1alpha1`
`kind` string	`MCPServer`
`metadata` ObjectMeta	Refer to Kubernetes API documentation for fields of `metadata`.	Optional: {}
`spec` MCPServerSpec	spec defines the desired state of MCPServer	Required: {}
`status` MCPServerStatus	status defines the observed state of MCPServer	Optional: {}

MCPServerAddress¶

MCPServerAddress contains the address information for the MCPServer.

Appears in: - MCPServerStatus

Field	Description	Default	Validation
`url` string	URL is the cluster-internal address of the MCP server service. Format: http://..svc.cluster.local:/		Optional: {}

MCPServerSpec¶

MCPServerSpec defines the desired state of MCPServer.

Appears in: - MCPServer

Field	Description	Validation
`source` Source	Source is a required field that defines where the MCP server should be sourced from. Currently supports container images, with potential for additional source types in the future. This configuration determines how the MCP server will be deployed and run.	Required: {}
`config` ServerConfig	Config is a required field that defines how the MCP server should be configured when it runs. This includes runtime settings such as the server port, command-line arguments, environment variables, and storage mounts.	Required: {}
`runtime` RuntimeConfig	Runtime defines runtime management configuration. If not specified, default runtime settings will be applied.	MinProperties: 1 Optional: {}

MCPServerStatus¶

MCPServerStatus defines the observed state of MCPServer.

Appears in: - MCPServer

Field	Description	Validation
`observedGeneration` integer	ObservedGeneration reflects the generation most recently observed by the controller. This allows users to determine if the status reflects the latest spec changes. When observedGeneration matches metadata.generation, the status is up-to-date.	Optional: {}
`deploymentName` string	DeploymentName is the name of the Deployment created for this MCPServer.	Optional: {}
`serviceName` string	ServiceName is the name of the Service created for this MCPServer.	Optional: {}
`address` MCPServerAddress	Address contains the address of the MCP server service.	Optional: {}
`conditions` Condition array	Conditions represent the latest available observations of the MCPServer's state. Standard condition types: - "Accepted": Configuration is valid and all referenced resources exist - "Ready": MCP server is operational and ready to serve requests The "Accepted" condition validates configuration before creating resources. Reasons: Valid (True), Invalid (False with details in message) The "Ready" condition indicates overall server readiness. Status=True means at least one instance is healthy and serving requests. Reasons: - Available: Server is ready (Status=True) - ConfigurationInvalid: Accepted=False, cannot proceed - DeploymentUnavailable: No healthy instances (all deployment/pod issues) - ScaledToZero: Deployment scaled to 0 replicas - Initializing: Waiting for initial status Note: Specific failure details (ImagePullBackOff, OOMKilled, CrashLoop, etc.) are included in the condition message, not the reason.	Optional: {}

MountPermissions¶

Underlying type: string

MountPermissions defines the access permissions for a volume mount.

Validation: - Enum: [ReadOnly ReadWrite RecursiveReadOnly]

Appears in: - StorageMount

Field	Description
`ReadOnly`	MountPermissionsReadOnly indicates the mount is read-only.
`ReadWrite`	MountPermissionsReadWrite indicates the mount is read-write.
`RecursiveReadOnly`	MountPermissionsRecursiveReadOnly indicates the mount and all its submounts are recursively read-only. This provides stronger guarantees than ReadOnly alone.

RuntimeConfig¶

RuntimeConfig defines runtime execution configuration for the MCP server.

This section covers how the MCP server executes and behaves at runtime, including replicas, security, resource allocation, and health probes.

If not specified, default runtime settings will be applied. See individual field documentation for specific defaults.

Validation: - MinProperties: 1

Appears in: - MCPServerSpec

Field	Description	Validation
`replicas` integer	Replicas is the number of MCP server pod replicas to run. Defaults to 1 if not specified. Set to 0 to scale down the deployment. This field is a pointer (*int32) to distinguish between: - nil (not specified) -> defaults to 1 replica - ptr.To(0) (explicit 0) -> scale-to-zero This follows the same pattern as Deployment.Spec.Replicas in k8s.io/api/apps/v1.	Minimum: 0 Optional: {}
`security` SecurityConfig	Security defines security-related configuration. If not specified, default security settings will be applied.	Optional: {}
`resources` ResourceRequirements	Resources defines the resource requirements for the MCP server container. This includes CPU and memory requests and limits. If not specified, the container will run without explicit resource constraints. Supports partial specification (e.g., only requests or only limits). Example: resources: requests: cpu: "100m" memory: "256Mi" limits: cpu: "500m" memory: "512Mi"	Optional: {}
`health` HealthConfig	Health defines health check configuration for the MCP server. If not specified, no health probes will be configured.	MinProperties: 1 Optional: {}

SecurityConfig¶

SecurityConfig defines security-related configuration. If not specified, default security settings will be applied. See individual field documentation for specific defaults.

Appears in: - RuntimeConfig

Field	Description	Validation
`serviceAccountName` string	ServiceAccountName is the name of the ServiceAccount to use for the MCP server pods. The ServiceAccount should have appropriate RBAC permissions for the MCP server's operations. If not specified, the default ServiceAccount for the namespace will be used. Must be a string that follows the DNS1123 subdomain format. Must be at most 253 characters in length, and must consist only of lower case alphanumeric characters, '-' and '.', and must start and end with an alphanumeric character. Example: For kubernetes-mcp-server with read-only access, create a ServiceAccount and bind it to the 'view' ClusterRole.	MaxLength: 253 Optional: {}
`podSecurityContext` PodSecurityContext	PodSecurityContext specifies the security context for the MCP server pod.	Optional: {}
`securityContext` SecurityContext	SecurityContext specifies the security context for the MCP server container.	Optional: {}

ServerConfig¶

ServerConfig defines how the MCP server should be configured when it runs.

Appears in: - MCPServerSpec

Field	Description	Default	Validation
`port` integer	Port is a required field that specifies the port number on which the MCP server listens for connections. Must be between 1 and 65535. This should match the port that the MCP server container exposes and will be used for configuring the Kubernetes Service.		Maximum: 65535 Minimum: 1 Required: {}
`arguments` string array	Arguments are command line arguments for the MCP server container. Use this to pass configuration flags to the server. Example: ["--config", "/etc/mcp-config/config.toml", "--verbose"] When not specified, the container image's default arguments (CMD/ENTRYPOINT) are used. An empty array [] is allowed and will override the container image's default arguments with no arguments. Empty strings within the array are not allowed.		Optional: {}
`env` EnvVar array	Env is a list of environment variables to set in the MCP server container. Supports the full Kubernetes EnvVar API including valueFrom for secrets and configmaps.		Optional: {}
`envFrom` EnvFromSource array	EnvFrom is a list of sources to populate environment variables in the MCP server container. Each entry injects all key-value pairs from a Secret or ConfigMap as environment variables. The keys become the variable names. Useful when a Secret's keys already match the expected env var names (e.g., GITHUB_TOKEN).		Optional: {}
`storage` StorageMount array	Storage defines storage mounts for ConfigMaps, Secrets, and EmptyDirs. Each item uses native Kubernetes volume source types for consistency and feature parity. If specified, must contain at least 1 item. Maximum 64 items. Each storage mount must have a unique path.		MaxItems: 64 MinItems: 1 Optional: {}
`path` string	Path is the HTTP path where the MCP server listens for SSE/Streamable HTTP connections. This path is appended to the service address in the status URL. Must be a valid URI path component starting with '/'. Maximum 253 characters. Cannot contain spaces, control characters, or query/fragment separators (? #). Examples: /mcp, /api/v1/mcp, /services/mcp-server Defaults to /mcp if not specified.	/mcp	MaxLength: 253 MinLength: 1 Optional: {}

Source¶

Source defines where the MCP server's container image (or other source types in the future) is located.

Appears in: - MCPServerSpec

Field	Description	Default	Validation
`type` SourceType	Type is a required field that configures how the MCP server should be sourced. Allowed values are: ContainerImage. When set to ContainerImage, the MCP server will be sourced directly from an OCI container image following the configuration specified in containerImage.		Enum: [ContainerImage] Required: {}
`containerImage` ContainerImageSource	ContainerImage specifies container image details when Type is ContainerImage.		Optional: {}

SourceType¶

Underlying type: string

SourceType defines the type of source for the MCP server.

Validation: - Enum: [ContainerImage]

Appears in: - Source

Field	Description
`ContainerImage`	SourceTypeContainerImage indicates the source is a container image.

StorageMount¶

StorageMount defines a storage mount combining volume source and mount configuration. The Path and Permissions fields apply to all storage types, while Source contains the type-specific configuration (ConfigMap, Secret, or EmptyDir).

Appears in: - ServerConfig

Field	Description	Default	Validation
`path` string	Path is a required field that specifies where the volume should be mounted in the container. Must be an absolute path (starting with /). The ConfigMap or Secret data will be accessible to the MCP server process at this location. Must be between 1 and 4096 characters, start with '/', and must not contain ':'.		MaxLength: 4096 MinLength: 1 Required: {}
`permissions` MountPermissions	Permissions specifies the access permissions for the mount. Allowed values are ReadOnly, ReadWrite, and RecursiveReadOnly. When set to ReadOnly, the mount is read-only. When set to ReadWrite, the mount is read-write. When set to RecursiveReadOnly, the mount and all submounts are recursively read-only. Defaults to ReadOnly for ConfigMap and Secret mounts. For EmptyDir mounts, ReadWrite is more common for writable scratch space.	ReadOnly	Enum: [ReadOnly ReadWrite RecursiveReadOnly] Optional: {}
`source` StorageSource	Source defines where the storage data comes from (ConfigMap, Secret, or EmptyDir).		Required: {}

StorageSource¶

StorageSource defines the source of the storage to mount (ConfigMap, Secret, or EmptyDir).

Appears in: - StorageMount

Field	Description	Validation
`type` StorageType	Type is a required field that specifies the type of volume source. Allowed values are: ConfigMap, Secret, EmptyDir. This determines which volume source field (configMap, secret, or emptyDir) should be configured.	Enum: [ConfigMap Secret EmptyDir] Required: {}
`configMap` ConfigMapVolumeSource	ConfigMap specifies a ConfigMap volume source (when Type is ConfigMap). Uses native Kubernetes ConfigMapVolumeSource type for full feature parity.	Optional: {}
`secret` SecretVolumeSource	Secret specifies a Secret volume source (when Type is Secret). Uses native Kubernetes SecretVolumeSource type for full feature parity.	Optional: {}
`emptyDir` EmptyDirVolumeSource	EmptyDir specifies an EmptyDir volume source (when Type is EmptyDir). Uses native Kubernetes EmptyDirVolumeSource type for full feature parity.	Optional: {}

StorageType¶

Underlying type: string

StorageType defines the type of storage mount.

Validation: - Enum: [ConfigMap Secret EmptyDir]

Appears in: - StorageSource

Field	Description
`ConfigMap`	StorageTypeConfigMap indicates a ConfigMap volume source.
`Secret`	StorageTypeSecret indicates a Secret volume source.
`EmptyDir`	StorageTypeEmptyDir indicates an EmptyDir volume source.