Documentation
API Reference#
Packages#
kagent.dev/v1alpha1#
Package v1alpha1 contains API Schema definitions for the v1alpha1 API group.
Resource Types#
HTTPTransport#
HTTPTransport defines the configuration for a Streamable HTTP transport.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
targetPort integer | target port is the HTTP port that serves the MCP server.over HTTP | ||
path string | the target path where MCP is served | ||
tls HTTPTransportTLS | TLS defines the TLS configuration for HTTPS access to the MCP server. |
HTTPTransportTLS#
HTTPTransportTLS defines the TLS configuration for HTTP transport.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
secretRef string | SecretRef is a reference to a Kubernetes Secret containing the client certificate (tls.crt), key (tls.key), and optionally the CA certificate (ca.crt) for mTLS authentication. The Secret must be in the same namespace as the MCPServer. | ||
insecureSkipVerify boolean | InsecureSkipVerify disables SSL certificate verification. WARNING: This should ONLY be used in development/testing environments. Production deployments MUST use proper certificates. | false |
InitContainerConfig#
InitContainerConfig defines the configuration for the init container.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
image string | Image defines the full image reference for the init container. If specified, this overrides the default transport adapter image. Example: "myregistry.com/agentgateway/agentgateway:0.9.0-musl" | ||
imagePullPolicy PullPolicy | ImagePullPolicy defines the pull policy for the init container image. | Enum: [Always Never IfNotPresent] | |
resources ResourceRequirements | Resources defines the compute resource requirements for the init container. Use this to specify CPU and memory requests and limits for the init container. | ||
securityContext SecurityContext | SecurityContext defines the security context for the init container. If not specified, the main container's security context will be used. |
MCPServer#
MCPServer is the Schema for the mcpservers API.
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string | kagent.dev/v1alpha1 | ||
kind string | MCPServer | ||
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 | ||
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 | ||
metadata ObjectMeta | Refer to Kubernetes API documentation for fields of metadata. | ||
spec MCPServerSpec | |||
status MCPServerStatus |
MCPServerDeployment#
MCPServerDeployment
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
image string | Image defines the container image to to deploy the MCP server. | ||
imagePullPolicy PullPolicy | ImagePullPolicy defines the pull policy for the container image. | Enum: [Always Never IfNotPresent] | |
port integer | Port defines the port on which the MCP server will listen. | 3000 | |
cmd string | Cmd defines the command to run in the container to start the mcp server. | ||
args string array | Args defines the arguments to pass to the command. | ||
env object (keys:string, values:string) | Env defines the environment variables to set in the container. | ||
secretRefs LocalObjectReference array | SecretRefs defines the list of Kubernetes secrets to reference. These secrets will be mounted as volumes to the MCP server container. | ||
configMapRefs LocalObjectReference array | ConfigMapRefs defines the list of Kubernetes configmaps to reference. These configmaps will be mounted as volumes to the MCP server container. | ||
volumeMounts VolumeMount array | VolumeMounts defines the list of volume mounts for the MCP server container. This allows for more flexible volume mounting configurations. | ||
volumes Volume array | Volumes defines the list of volumes that can be mounted by containers. This allows for custom volume configurations beyond just secrets and configmaps. | ||
initContainer InitContainerConfig | InitContainer defines the configuration for the init container that copies the transport adapter binary. This is used for stdio transport type. | ||
serviceAccount ServiceAccountConfig | ServiceAccount defines the configuration for the ServiceAccount to be created. | ||
serviceAccountName string | ServiceAccountName is the name of an existing ServiceAccount to use. | ||
sidecars Container array | Sidecars defines additional containers to run alongside the MCP server container. These containers will share the same pod and can share volumes with the main container. | ||
labels object (keys:string, values:string) | Labels defines additional labels to add to the pod template. These labels will be merged with the default labels. | ||
annotations object (keys:string, values:string) | Annotations defines additional annotations to add to the pod template. These annotations will be merged with the default annotations. | ||
resources ResourceRequirements | Resources defines the compute resource requirements for the main MCP server container. Use this to specify CPU and memory requests and limits. Example: resources: requests: cpu: "100m" memory: "128Mi" limits: cpu: "500m" memory: "512Mi" | ||
securityContext SecurityContext | SecurityContext defines the security context for the main MCP server container. Use this to configure container-level security settings such as: - runAsUser/runAsGroup: Run as specific user/group - runAsNonRoot: Ensure container doesn't run as root - readOnlyRootFilesystem: Make root filesystem read-only - allowPrivilegeEscalation: Prevent privilege escalation - capabilities: Add or drop Linux capabilities | ||
podSecurityContext PodSecurityContext | PodSecurityContext defines the security context for the entire pod. Use this to configure pod-level security settings such as: - runAsUser/runAsGroup: Default user/group for all containers - fsGroup: Group ownership of mounted volumes - seccompProfile: Seccomp profile for the pod - sysctls: Kernel parameters to set | ||
tolerations Toleration array | Tolerations defines the tolerations for the pod. Use this to schedule pods on nodes with matching taints. | ||
affinity Affinity | Affinity defines the affinity rules for the pod. Use this to control pod placement based on node labels, pod labels, or other scheduling constraints. | ||
nodeSelector object (keys:string, values:string) | NodeSelector defines the node selector for the pod. Use this to constrain pods to nodes with specific labels. | ||
replicas integer | Replicas defines the number of desired pod replicas. Defaults to 1 if not specified. | 1 | |
imagePullSecrets LocalObjectReference array | ImagePullSecrets defines the list of secrets to use for pulling container images. |
MCPServerSpec#
MCPServerSpec defines the desired state of MCPServer.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
deployment MCPServerDeployment | Configuration to Deploy the MCP Server using a docker container | ||
transportType TransportType | TransportType defines the type of mcp server being run | Enum: [stdio http] | |
stdioTransport StdioTransport | StdioTransport defines the configuration for a standard input/output transport. | ||
httpTransport HTTPTransport | HTTPTransport defines the configuration for a Streamable HTTP transport. | ||
timeout Duration | Timeout defines the default connection timeout for clients connecting to this MCP server. MCP servers deployed via the MCPServer CRD use a sidecar gateway that spawns a new stdio process (e.g. via uvx/npx) for each session. Process startup can take 2-8 seconds depending on package cache state, which may exceed the default timeout used by some clients. This value is propagated to the generated RemoteMCPServer resources when they do not specify an explicit timeout. | 30s |
MCPServerStatus#
MCPServerStatus defines the observed state of MCPServer.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
conditions Condition array | Conditions describe the current conditions of the MCPServer. Implementations should prefer to express MCPServer conditions using the MCPServerConditionType and MCPServerConditionReasonconstants so that operators and tools can converge on a common vocabulary to describe MCPServer state. Known condition types are: * "Accepted" * "ResolvedRefs" * "Programmed" * "Ready" | MaxItems: 8 | |
observedGeneration integer | ObservedGeneration is the most recent generation observed for this MCPServer. It corresponds to the MCPServer's generation, which is updated on mutation by the API Server. |
ServiceAccountConfig#
ServiceAccountConfig defines the configuration for the ServiceAccount.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
annotations object (keys:string, values:string) | Annotations to add to the ServiceAccount. This is useful for configuring AWS IRSA (IAM Roles for Service Accounts) or other cloud provider integrations. Example: {"eks.amazonaws.com/role-arn": "arn:aws:iam::123456789012:role/my-role"} | ||
labels object (keys:string, values:string) | Labels to add to the ServiceAccount. |
StdioTransport#
StdioTransport defines the configuration for a standard input/output transport.
Appears in:
TransportType#
Underlying type: string
MCPServerTransportType defines the type of transport for the MCP server.
Appears in:
| Field | Description |
|---|---|
stdio | TransportTypeStdio indicates that the MCP server uses standard input/output for communication. |
http | TransportTypeHTTP indicates that the MCP server uses Streamable HTTP for communication. |
Kagent Lab: Discover kagent and kmcp
Free, on‑demand lab: build custom AI agents with kagent and integrate tools via kmcp on Kubernetes.