kMCP Documentation

kMCP is a development platform and control plane for the Model Context Protocol (MCP). It consists of three primary components designed to move MCP services from prototype to production:

• CLI: The primary development tool used to scaffold new MCP projects, manage tools, build container images, and run MCP servers locally for testing.
• Controller: A Kubernetes-native component that manages the lifecycle of MCP server deployments. It uses Custom Resource Definitions (CRDs) to treat MCP servers as native Kubernetes objects, allowing management via kubectl.
• Transport Adapter: A component that fronts the MCP server to provide external traffic routing. It supports multiple transport protocols (HTTP, WebSocket, SSE) without requiring changes to your application code.

kMCP is built around several key principles to simplify MCP connectivity:

• Rapid scaffolding: Supports FastMCP (Python) and MCP Go SDK.
• One-command deployment: Deploys to Kubernetes with pre-configured Transport Adapters.
• Consistent workflow: Provides a unified path from local development to production.
• Built-in transport support: Native support for HTTP, WebSocket, and Server-Sent Events (SSE).
• Kubernetes-native: Leverages Custom Resource Definitions (CRDs) for orchestration.
• Secrets management: Integrated with Kubernetes secrets for secure configuration.

You can install the kmcp CLI on your local machine using the provided installation script. This script downloads and configures the binary for your system.

To install, run:

curl -fsSL https://raw.githubusercontent.com/kagent-dev/kmcp/refs/heads/main/scripts/get-kmcp.sh | bash

After installation, verify it by checking the help menu:

kmcp --help

KMCP (Kubernetes MCP Server Controller) can be deployed to Kubernetes clusters using Helm.

Prerequisites

• Kubernetes 1.11.3+
• Helm 3.0+

Installation Steps

1. Add the Helm Repository

helm repo add kmcp https://charts.kagent.dev
helm repo update

2. Install the Chart

• Default installation:

helm install kmcp kmcp/kmcp

• Install in a specific namespace (creates the namespace if it doesn't exist):

helm install kmcp kmcp/kmcp --namespace kmcp-system --create-namespace

• Install with custom values:

helm install kmcp kmcp/kmcp --values values.yaml

# Add the repository
helm repo add kmcp https://charts.kagent.dev
helm repo update

# Install with default values
helm install kmcp kmcp/kmcp

To develop and test an MCP project on your local machine, follow these steps:

1. Build the KMCP CLI: Ensure you have the CLI binary available.

   make build-cli

2. Initialize a project: Create a new MCP project using the init command. For example, to create a Python-based project:

   dist/kmcp init python my-mcp-python

3. Run with MCP Inspector: Use the run command to start your project locally via the mcp inspector.

   dist/kmcp run --project-dir ./my-mcp-python/

Use standard Helm commands to manage the lifecycle of your KMCP installation.

To upgrade the chart:

helm upgrade kmcp kmcp/kmcp

To uninstall the chart:

helm uninstall kmcp

Note: Uninstalling will remove all associated Kubernetes resources and delete the release.

# Upgrade
helm upgrade kmcp kmcp/kmcp

# Uninstall
helm uninstall kmcp

If you are developing locally and want to build the CLI from source, use the make command. This will generate the binary in the dist/ directory.

1. Build the binary:

make build-cli

2. Run the generated binary:

dist/kmcp --help

The ToolConfig utility allows you to manage tool-specific settings using environment variables. Configuration keys follow a specific naming convention: TOOLNAME_KEY (where both the tool name and the key are converted to uppercase).

For example, if you have a tool named search and a configuration key api_key, you should set the environment variable SEARCH_API_KEY.

# Example: Setting configuration for a tool named 'mytool' with key 'endpoint'
export MYTOOL_ENDPOINT="https://api.example.com"

The Python framework uses a dynamic loading system via src/tools/__init__.py.

When a new tool is generated, the regenerateToolsInit process scans the src/tools directory for all .py files (excluding __init__.py). It then automatically constructs an __init__.py file that:

• Includes a header warning that the file is automatically generated.
• Imports each tool using the pattern from .<tool_name> import <tool_name>.
• Populates the __all__ list with the tool names.

Warning: Do not edit src/tools/__init__.py manually, as it will be overwritten whenever a new tool is generated.

The {{.ProjectName}} Python server uses DynamicMCPServer to automatically discover and load tools.

How it works

1. The server is initialized with a tools_dir (typically src/tools).
2. Calling server.load_tools() scans the directory.
3. Each tool file in the directory must contain a function decorated with @mcp.tool() to be registered and exposed via the MCP server.

from core.server import DynamicMCPServer

server = DynamicMCPServer(
    name="{{.ProjectName}}",
    tools_dir="src/tools"
)
server.load_tools()
server.run(transport_mode="stdio")

To add functionality to an MCPServer, you must implement a Tool object. Each tool must provide:

• A unique name.
• A description explaining what the tool does.
• An inputSchema (using McpSchema.JsonSchema) defining the expected arguments.
• An execute(Map<String, Object> args) method containing the business logic.
• (Optional) getAnnotations() to provide metadata like title, readOnlyHint, or destructiveHint to the MCP client.

When a tool is called, the execute method receives a map of arguments parsed from the incoming JSON request. The result of execute is converted to a string and returned to the client as a text content block.