kmcp: Scaffold, Run and Deploy MCP Servers Without Hand-Rolling Kubernetes YAML

The gap kmcp targets: MCP prototypes that never reach production

Writing an MCP server is not the hard part. The README frames the problem as what happens after the prototype works: ad-hoc scaffolding, transport fragmentation across HTTP, WebSocket and SSE, and disconnected security and observability for agent-to-tool traffic. kmcp is aimed at the people who inherit that prototype. The README names three journeys: an AI/ML engineer packaging an existing prototype, a DevOps engineer building MCP infrastructure in Kubernetes, and a first-time developer building an MCP service prototype. Those are different jobs sharing one toolchain, which is the design bet here. The CLI covers the local half, the controller covers the cluster half, and the transport adapter sits between the MCP server and whatever is calling it. If you only ever run an MCP server on your laptop over stdio, most of this project is dead weight. The value shows up when more than one agent or team has to reach the same server and someone has to own its uptime.

Three components: CLI, controller, transport adapter

The architecture splits cleanly. The CLI is the development surface: it scaffolds new MCP projects, manages tools, builds container images and runs the server locally. The controller manages the lifecycle of MCP server deployments inside a Kubernetes cluster and, per the README, uses a Custom Resource Definition to define MCP servers as native Kubernetes objects so they can be managed with kubectl. The transport adapter fronts the MCP server and handles external traffic routing across multiple transport protocols without code changes to the server itself. That last piece is the interesting one. Transport support is a property of the deployment rather than the application, so an existing server does not need to be rewritten to speak a second protocol. The cost is an extra hop and an extra component in the request path, and the README does not describe how the adapter is configured or what happens when it cannot reach the backend. The repository layout backs the split: api/ holds the CRD types, cmd/ holds the manager entry point, pkg/ holds the CLI and shared logic, and helm/ and config/ hold deployment manifests. The Go module depends on sigs.k8s.io/controller-runtime and github.com/mark3labs/mcp-go, which is consistent with a controller-runtime operator that also embeds an MCP client or server library.

Install the kmcp CLI and scaffold your first server

The README gives a single install command that downloads and runs a shell script from the repository. It is a curl-to-bash install, so read the script first if that matters to your team; the README does not offer a package manager alternative or list checksums.

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

Confirm the binary is on your PATH by asking for help. The README shows a screenshot of the resulting help text rather than transcribing it, so the exact subcommand list is not in the README text; run the command and read what your build prints.

kmcp --help

From there the README points at three quickstart paths instead of inline instructions: your first MCP service prototype, packaging an existing prototype, and building MCP infrastructure in Kubernetes. Scaffolding support is stated for FastMCP (Python) and the MCP Go SDK, and the Go module confirms github.com/mark3labs/mcp-go v0.33.0 as a dependency. The deploy documentation is split into two options, one for deploying a server with npx or uvx and one for building and deploying a server, which maps to the packaging and infrastructure journeys. The README does not print the scaffold command, the generated directory tree, or the flags for building an image, so treat the docs site as the source of truth for those and do not guess at syntax.

What the controller does not solve for you

The controller makes MCP servers Kubernetes objects, and that is also the constraint. Everything it manages lives in a cluster, so a team without one gets a CLI and nothing else. The README does not document rollback behaviour, upgrade semantics for the CRD, or what happens to running MCP server pods when the CRD schema changes between releases. That matters because the release cadence is visible: v0.2.7 on 2026-03-04, v0.2.8 on 2026-03-30, and v0.3.0 on 2026-05-05. Three releases in roughly two months is a moving target for anyone pinning a CRD version. The last push to the repository was on 2026-06-16, so there has been no commit activity for about three months as of this writing; that is not abandonment, but it does mean the version you pin now is likely the version you run for a while. Secrets management is described as integrated with Kubernetes secrets, which is a reasonable default and also means your MCP server credentials follow the same RBAC and namespace boundaries as everything else in the cluster. If your MCP servers are personal tools that read local files, the CRD and adapter are overhead with no payoff.

kmcp against running MCP servers directly with npx or uvx

The README itself presents the alternative: deploy an MCP server with npx or uvx, listed as option 1 in the deployment docs, with building and deploying as option 2. Running via npx or uvx means the server is a process on a machine, started from a package registry, with no CRD, no controller and no adapter. It is the right answer for a single developer or a small team where the server is launched by the agent client itself. kmcp's difference is not that it runs the server better; it is that the server becomes a cluster object with a lifecycle, a routing layer and a place in your existing kubectl workflow. The trade is operational surface. With npx or uvx you manage a process and a version string. With kmcp you manage a controller deployment, a CRD, Helm charts under helm/, and the transport adapter, in exchange for multi-transport routing and Kubernetes-native secrets. Neither is strictly better. The decision is whether the MCP server has an owner who is already on call for the cluster.

Building and releasing from source

The repository ships a Makefile that encodes the build and release path. Version metadata is injected through ldflags into github.com/kagent-dev/kmcp/pkg/internal/version, covering Version, GitCommit and BuildDate, and VERSION falls back to git describe with a v0.0.1-<commit> default when no tag is reachable.

make docker-build

The Dockerfile builds the manager with CGO_ENABLED=0 for the target OS and architecture, then packages it on gcr.io/distroless/static:nonroot running as UID 65532. That is a small attack surface and no shell in the image, which also means you cannot exec in to debug; you get logs or nothing. The Makefile defaults DOCKER_REPO to kagent-dev/kmcp and DOCKER_REGISTRY to ghcr.io, and the Helm repository is set to oci://ghcr.io/kagent-dev, so the published artifacts are OCI-based. The controller image name defaults to controller with the version as tag. If you build your own, override DOCKER_REGISTRY and DOCKER_REPO rather than editing the Makefile, since VERSION is derived from git state and a dirty tree changes the tag. The Makefile also pins BUILDKIT_VERSION to v0.23.0 and names the builder kmcp-builder-v0.23.0, so local builds create a dedicated buildx builder on first run.

Licence and the cost of keeping up

kmcp is Apache-2.0, which permits commercial use, modification and redistribution with the usual notice and patent grant terms; this is not legal advice, so have counsel review if you are embedding it in a product. Practically, the licence means you can fork the controller if a CRD change breaks you, but a fork of a controller is a maintenance commitment most teams underestimate. The upgrade cost concentrates in two places. First, the CRD: adding fields is usually safe, changing or removing them is not, and the README does not describe a conversion strategy. Second, the transport adapter, which sits in the request path; the README does not document its failure behaviour when the backend MCP server is unreachable, so test that before you put it behind anything that matters. Pin a specific release tag rather than tracking main, and read the release notes for v0.3.0 before moving off v0.2.8.

Editorial conclusion

Adopt kmcp if your MCP servers are heading into a Kubernetes cluster and you want the scaffolding, the image build and the CRD lifecycle to come from one tool. Do not adopt it if your MCP servers only ever run on a laptop over stdio, because the controller and transport adapter add a cluster you do not need. Before committing, verify two things in your own environment: that the transport adapter can front the transports your existing server already speaks, and that the CRD schema in api/ covers the secret and routing fields you rely on. The Apache-2.0 licence means you can vendor the controller if you have to, but the CRD becomes your upgrade surface.

Frequently asked questions

Official sources

1. kagent-dev/kmcp on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases