K8S-MCP-INTERFACE: Kubernetes Abstraction Layer for Generative Models

This component, referred to as K8S-MCP-INTERFACE, functions as a robust Model Context Protocol (MCP) service endpoint designed specifically to bridge Large Language Models (LLMs) with the operational mechanics of Kubernetes clusters. It facilitates querying cluster state and orchestrating resource manipulation using the structured MCP messaging paradigm.

Core Capabilities

• Enumeration of discoverable resources within the target Kubernetes API domain.
• Listing of cluster-scoped resources.
• Listing of resources confined to specific namespaces.
• Fetching detailed resource manifests, including access to derived views such as resource status, scaling metrics, and container output streams (logs).
• Provisioning or updating (idempotent application) of both cluster-wide and namespaced resources.
• Initiating remote command execution within running containers, complete with mechanisms for enforcing execution deadlines.
• Implementation rooted in the Kubernetes API Machinery's unstructured client, ensuring adaptability and broad compatibility.
• Integrated traffic throttling to safeguard the API server against overly aggressive client interactions.

Rationale for Selection

K8S-MCP-INTERFACE offers distinct advantages when serving as the Kubernetes interface for AI agents:

Native Implementation Synergy

• Developed in Go, aligning with Kubernetes' primary language stack.
• Optimized performance profile suitable for high-throughput server tasks.
• Leverages Go's intrinsic safety features for type checking and concurrent operations.
• Direct interoperability with core Kubernetes client libraries.

Direct API Conduit

• Bypasses reliance on external tools like kubectl or Helm for core interactions.
• Communicates directly against the Kubernetes Control Plane endpoint.
• Minimizes operational latency and enhances system robustness.

Comprehensive Resource Adaptability

• Utilizes the unstructured client to support any registered Kubernetes object, including custom resources (CRDs).
• Eliminates the need to pre-define schemas for every supported resource type.
• Automatically incorporates support for future Kubernetes API additions.

Design Philosophy

• Singular focus on essential Kubernetes interaction primitives.
• Codebase emphasizes clarity, maintainability, and clear separation of functional units.
• Minimal external library footprint for lightweight deployment.

Production Readiness

• Engineered for stability and responsiveness in demanding operational settings.
• Robust error propagation and resource handling protocols.
• Built-in defense against denial-of-service via request throttling.
• Architected for comprehensive unit testing coverage.

Operational Requirements

• Go runtime version 1.24 or newer.
• Access credentials for a target Kubernetes cluster (kubeconfig file).
• The task runner utility (v3+) for development workflows.

Deployment Procedure

1. Obtain the source repository:

   bash git clone https://github.com/StacklokLabs/mkp.git cd mkp

2. Fetch necessary project dependencies:

   bash task install

3. Compile the executable server binary:

   bash task build

Execution Guide

Launching the Service Endpoint

To initiate the service utilizing the default credentials path:

bash task run

To specify an alternative kubeconfig location:

bash KUBECONFIG=/path/to/custom/config task run-with-kubeconfig

To bind the service to a non-default network port:

bash MCP_PORT=9091 task run

Available MCP Interaction Tools

The K8S-MCP-INTERFACE exposes the following structured methods for agent interaction:

get_k8s_entity

Retrieves a specified Kubernetes object or one of its dynamic sub-paths.

Parameters:

• scope (required): Classification of the resource scope ("cluster" or "namespaced").
• api_group: The API grouping identifier (e.g., "apps", "networking.k8s.io").
• api_version (required): The version segment of the API (e.g., "v1", "v1beta1").
• resource_kind (required): The plural name of the resource collection (e.g., "deployments").
• target_ns: The containing namespace (mandatory for namespaced entities).
• entity_name (required): The unique identifier of the resource instance.
• sub_path: The specific subresource endpoint to query (e.g., "status", "scale", "logs").
• query_params: Supplementary parameters appended to the API request (see examples).

Example (Fetching Deployment Status):

{ "name": "get_k8s_entity", "arguments": { "scope": "namespaced", "api_group": "apps", "api_version": "v1", "resource_kind": "deployments", "target_ns": "production", "entity_name": "web-frontend", "sub_path": "status" } }

Example (Retrieving Container Logs with Filters):

{ "name": "get_k8s_entity", "arguments": { "scope": "namespaced", "api_group": "", "api_version": "v1", "resource_kind": "pods", "target_ns": "logging", "entity_name": "data-processor-xyz", "sub_path": "logs", "query_params": { "container": "processor-main", "sinceSeconds": "7200", "timestamps": "true" } } }

Pod Log Parameter Specifics:

• container: Designates the target container within the Pod.
• previous: Boolean flag to retrieve logs from a terminated container instance.
• sinceSeconds: Filters output to logs generated after the specified duration in seconds.
• sinceTime: Filters logs based on an RFC3339 timestamp.
• timestamps: Instructs the API to prefix each line with a timestamp.
• limitBytes: Imposes a ceiling on the total bytes returned.
• tailLines: Limits output to the final N lines of the log stream.

Default log constraints (100 lines, 32KB) are enforced to optimize LLM context utilization, modifiable via query_params.

Regular Resource Query Parameter:

• resourceVersion: Allows fetching the object state as it existed at a specific version token.

scan_k8s_collection

Performs a bulk listing of resources belonging to a specified collection.

Parameters:

• scope (required): Resource scope ("cluster" or "namespaced").
• api_group: API group identifier.
• api_version (required): API version identifier.
• resource_kind (required): Plural resource collection name.
• target_ns: Namespace (mandatory for namespaced collections).
• label_filter: Standard Kubernetes label selector string for filtering.
• detail_annotations: Inclusion flag for metadata annotations (default: true).
• omit_annotation_keys: List of annotation keys (supports globbing with *) to remove from results.
• include_only_annotation_keys: If set, only these specified annotations will be retained.

Annotation Exclusion Logic

This tool features advanced metadata trimming to mitigate context bloat from extensive annotations (e.g., large GPU device metadata).

Excluding Specific Annotations (Example: NVIDIA metadata):

{ "name": "scan_k8s_collection", "arguments": { "scope": "clustered", "api_group": "", "api_version": "v1", "resource_kind": "nodes", "omit_annotation_keys": [ "nvidia.com/*", "kubectl.kubernetes.io/last-applied-configuration" ] } }

Annotation Rule Summary:

• kubectl.kubernetes.io/last-applied-configuration is excluded by default.
• omit_annotation_keys recognizes trailing wildcards (*).
• If include_only_annotation_keys is active, it overrides all other inclusion/exclusion rules.
• Setting detail_annotations: false suppresses all metadata annotations.

deploy_k8s_entity

Applies a new or modified declarative manifest to the cluster.

Parameters:

• scope (required): Resource scope ("cluster" or "namespaced").
• api_group: API group identifier.
• api_version (required): API version identifier.
• resource_kind (required): Plural resource collection name.
• target_ns: Namespace (required for namespaced entities).
• payload_manifest (required): The YAML/JSON structure representing the desired state.

Example (Deploying a new Deployment):

{ "name": "deploy_k8s_entity", "arguments": { "scope": "namespaced", "api_group": "apps", "api_version": "v1", "resource_kind": "deployments", "target_ns": "default", "payload_manifest": { "apiVersion": "apps/v1", "kind": "Deployment", "metadata": { "name": "nginx-proxy", "labels": {"agent":"mkp"} }, "spec": { "replicas": 1, "selector": {"matchLabels": {"app": "nginx"}}, "template": { "metadata": {"labels": {"app": "nginx"}}, "spec": { "containers": [ { "name": "web", "image": "nginx:stable-alpine", "ports": [{"containerPort": 80}] } ] } } } } } }

interact_k8s_endpoint

Submits a POST request to a resource or subresource endpoint, primarily used for actions like remote execution.

Parameters:

• scope (required): Resource scope ("cluster" or "namespaced").
• api_group: API group identifier.
• api_version (required): API version identifier.
• resource_kind (required): Plural resource collection name.
• target_ns: Namespace (required for namespaced resources).
• entity_name (required): Name of the target object (e.g., Pod name).
• action_path: The subresource endpoint target (e.g., "exec").
• request_payload (required): The body content for the POST operation.
• request_options: Supplementary parameters for the POST request.

Example (Executing a command via Pod exec):

{ "name": "interact_k8s_endpoint", "arguments": { "scope": "namespaced", "api_group": "", "api_version": "v1", "resource_kind": "pods", "target_ns": "dev", "entity_name": "app-shell-01", "action_path": "exec", "request_payload": { "command": ["sh", "-c", "echo Hello from LLM agent"], "container": "main-app", "timeout": 45 } } }

Pod Execution Payload Directives:

• command: The shell instruction(s) to run, specified as a list of strings.
• container: Specifies the container within a multi-container Pod.
• timeout: Duration limit for execution in seconds (capped at 60s; default is 15s).

The response structure contains collected output streams (stdout, stderr) alongside any system error indications.

MCP Resource Mapping

K8S-MCP-INTERFACE exposes Kubernetes objects via standardized MCP URIs:

• Cluster-Scoped: k8s://cluster/{group}/{version}/{resource}/{name}
• Namespaced: k8s://namespace/{namespace}/{group}/{version}/{resource}/{name}

System Configuration Parameters

Communication Transport Layer

MKP supports two transport methodologies for MCP communication:

• SSE (Server-Sent Events): The established default transmission mechanism.
• Streaming HTTP: A unified transport layer accommodating standard HTTP replies and SSE feeds, advantageous for specific orchestration frameworks like ToolHive.

Configuration is managed via CLI flags or the MCP_TRANSPORT environment variable:

bash

Force Streaming HTTP transport

./build/mkp-server --transport=streaming-http

Controlling Resource Schema Advertising

By default, the server advertises the complete set of discoverable Kubernetes API resources to provide maximum context to consuming LLMs. For deployments in high-scale clusters, this introspection can consume valuable context tokens. Disable this advertising using the --serve-resources flag set to false:

bash

Launching without advertising API schemas

./build/mkp-server --serve-resources=false

Crucially, disabling schema advertising does not deactivate the explicit MCP tools (get_k8s_entity, scan_k8s_collection, etc.); they remain fully operational for direct cluster interaction.

Enabling Write/Mutation Permissions

By default, the service operates in a defensive, read-only mode, blocking tools that modify state (deploy_k8s_entity, etc.). To permit write operations, activate the --read-write directive:

bash

Activate full read/write capabilities

./build/mkp-server --read-write=true

Request Rate Governance

To ensure cluster stability when handling requests from autonomous agents, internal rate limiting is active by default (Token Bucket algorithm):

• Read Actions (scan_k8s_collection, get_k8s_entity): Capped at 120 transactions per minute per client session.
• Write Actions (deploy_k8s_entity, etc.): Capped at 30 transactions per minute per client session.
• Default Operations: Capped at 60 transactions per minute.

Rate control can be deactivated via the --enable-rate-limiting=false flag.

Integration with ToolHive Orchestrator

K8S-MCP-INTERFACE is designed for streamlined deployment via the ToolHive ecosystem.

ToolHive Execution (Recommended)

1. Ensure ToolHive CLI is installed and configured (thv client setup).

2. Execute the packaged Kubernetes client (aliased as 'k8s' in the registry), mounting local kubeconfig credentials:

   bash thv run --volume $HOME/.kube:/home/nonroot/.kube:ro k8s

Advanced Container Launch

For environments requiring explicit configuration:

bash

Specify SSE transport and run against the latest published image

thv run --name k8s-agent --transport sse --target-port 8080 --volume $HOME/.kube:/home/nonroot/.kube:ro ghcr.io/stackloklabs/mkp/server:latest

Contribution & Licensing

Contributions, bug reports, and feature proposals are highly encouraged via Issues. For direct engagement, join the community on the Stacklok Discord server in the #mcp-servers channel.

This software is distributed under the terms of the Apache License, Version 2.0 (see LICENSE file).