kmcp - Kubernetes controller for MCP servers

If you've prototyped an MCP server in Python or Go and then tried to deploy it as a real Kubernetes workload, you've probably written the same boilerplate three times: a Dockerfile, a Deployment YAML, a Service, an Ingress or Route, plus the transport-protocol fragmentation between HTTP, WebSocket, and SSE depending on which client connects. kMCP is the toolkit and Kubernetes operator that turns that boilerplate into one command and one CRD.

The framing in the README is honest: prototyping MCP services is fast; production adoption introduces ad-hoc scaffolding, transport fragmentation, and the disconnected-context problem of consistently enforcing security, observability, and governance for agent-to-tool communication. kMCP exists to make that path one workflow instead of three teams reinventing it.

The three components

kMCP = CLI + Controller + Transport Adapter

• CLI - your primary local-development tool. Scaffolds projects, manages tools, builds container images, runs servers locally for testing.
• Controller - Kubernetes operator. Defines MCP servers as native Kubernetes objects via CRD, so you manage them with kubectl commands you already know.
• Transport Adapter - sits in front of your MCP server. Provides external traffic routing and multi-protocol support (HTTP, WebSocket, SSE) without you writing protocol code.

The CRD is the integration point. Your MCP server becomes a kind: MCPServer object in the cluster - same lifecycle, same RBAC, same observability tooling as anything else you run on Kubernetes.

Quick start

Install the CLI:

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

The CLI scaffolds new projects against either FastMCP (Python) or the MCP Go SDK, depending on which language you want. From there, the workflow stays consistent from local dev to production - the same project layout you tested with kmcp run is what gets built and deployed via kmcp build and the Kubernetes controller.

What's in the box

The README's six core principles are the right summary:

• Rapid scaffolding with FastMCP (Python) and MCP Go SDK templates.
• One-command deployment to Kubernetes with pre-configured Transport Adapters.
• Consistent workflow from local development to production - same shape end to end.
• Built-in transport support for HTTP, WebSocket, and Server-Sent Events. No client-specific code paths.
• Kubernetes-native via CRDs - manage with kubectl, observe with whatever your cluster already runs.
• Secrets management integrated with Kubernetes secrets.

The transport flexibility is the underrated piece. Different MCP clients prefer different transports (Claude Desktop is happiest over stdio for local servers and HTTP/SSE for remote; some clients use WebSocket). Without an adapter you maintain three code paths or pick one and exclude clients. The adapter handles all three from the same backend.

Three quickstart journeys

The README points at three personas with distinct entry points:

• Building your first MCP service prototype - the CLI with kmcp init and kmcp run. Local-first, no cluster needed.
• AI/ML engineer packaging an existing prototype - npx/uvx deployment path. Useful when you have an MCP server that already works and just want it running somewhere.
• DevOps engineer building MCP infrastructure in Kubernetes - the controller path. Build a container image, write the CRD, kubectl apply.

The progression is intentional. You can start with one persona and grow into the next without changing the project structure.

Where this fits in the MCP landscape

The MCP ecosystem has multiple tools that sound similar from a distance:

• mcpm.sh is a package manager and registry - search, install, manage MCP servers across local clients (Claude Desktop, Cursor, Cline, etc.). Not in the data path at runtime.
• Lunar MCPX is a runtime aggregator - puts multiple existing MCP servers behind one gateway with namespace isolation. Operates between the agent and the servers.
• kMCP is the build-and-deploy toolkit - takes your code, makes it a production-grade MCP server running on Kubernetes. Operates before an MCP server exists.

You can use them together. Build with kMCP, deploy to Kubernetes, aggregate fronting traffic via Lunar or another gateway, distribute installation instructions via mcpm.sh.

When to reach for it

• You're building an MCP server in Python (FastMCP) or Go and want a clean local-to-prod path.
• Your platform team already runs Kubernetes and wants MCP servers to look like every other workload.
• You need transport flexibility (HTTP + WebSocket + SSE) without writing the dispatch yourself.
• You're trying to standardise how multiple internal MCP servers get built and deployed.

When not to

• You're running a single MCP server locally for personal use. The CLI helps; the Kubernetes story is overkill.
• You're not on Kubernetes and don't plan to be. The controller is the centre of gravity here.
• You need an MCP gateway / aggregator. That's a different tool (Lunar, ThinkWatch).

Trade-offs

Apache 2.0 licensed, Kubernetes-native by design. Built by the kagent team - the same project that has been doing the cloud-native AI infrastructure work alongside CNCF.

The Kubernetes assumption is real and binary. If you're already in the cloud-native ecosystem, the value is high - the CRD, the operator, the secrets integration all compose with what you already run. If you're not, kMCP isn't the on-ramp; you'd be picking up Kubernetes for the sake of one MCP server, which is the wrong shape.

The transport adapter is a layer in front of your server. That's almost always what you want, but worth knowing because it adds one hop in the request path. For low-latency local-development workloads, you can skip it; for production, it's the right default.

The docs at kagent.dev/docs/kmcp go deeper than the README - the workflow architecture document linked from the repo (devel/architecture/workflow.md) is the right read if you're evaluating whether kMCP fits your specific deploy story.