MCP Runtime Docs

Bootstrap commands

These are the shortest useful commands for getting the platform and one delivery path moving.

make deps && make build-runtime

./bin/mcp-runtime setup
./bin/mcp-runtime status

./bin/mcp-runtime registry push --image my-server:latest
./bin/mcp-runtime pipeline generate --dir .mcp --output manifests/
./bin/mcp-runtime pipeline deploy --dir manifests/

Command map

Group	What it covers	Important subcommands
`setup`	Install the platform stack, wire registry and ingress, deploy the operator, and optionally include sentinel.	`setup`, `--with-tls`, `--without-sentinel`
`cluster`	Initialize clusters, inspect health, configure kubeconfig and ingress, provision clusters, and manage cert-manager resources.	`init`, `status`, `config`, `provision`, `cert status`, `cert apply`, `cert wait`
`registry`	Inspect the internal registry, configure an external registry, and push images with direct or in-cluster modes.	`status`, `info`, `provision`, `push`
`server`	Manage MCPServer resources and related operator-facing actions.	`list`, `get`, `create`, `apply`, `export`, `patch`, `delete`, `logs`, `status`, `policy inspect`, `build image`
`access`	Manage `MCPAccessGrant` and `MCPAgentSession` resources that feed the gateway policy layer.	`grant list/get/apply/delete/disable/enable`, `session list/get/apply/delete/revoke/unrevoke`
`sentinel`	Inspect and operate the bundled analytics, gateway, and observability stack.	`status`, `events`, `logs`, `port-forward`, `restart`
`pipeline`	Generate MCPServer manifests from metadata and deploy those manifests into the cluster.	`generate`, `deploy`
`status`	Show overall platform status across cluster, registry, operator, MCP servers, and sentinel workloads.	`status`
`completion`	Generate shell completion scripts from the Cobra root command.	`completion bash`, `completion zsh`, `completion fish`

Setup and platform status

Install the stack

setup remains the broad install path for the runtime namespace, internal registry, operator, ingress wiring, and bundled sentinel stack unless you explicitly skip it.

mcp-runtime setup
mcp-runtime setup --with-tls
mcp-runtime setup --without-sentinel
mcp-runtime setup --test-mode

Read platform health

Use status for the aggregated platform view, then drop to the narrower trees when you need cluster, registry, or sentinel detail.

mcp-runtime status
mcp-runtime cluster status
mcp-runtime registry status
mcp-runtime sentinel status

Registry and image flow

Inspect and provision registry state

The registry tree covers both the bundled internal registry and external registry configuration for runtime images.

mcp-runtime registry status
mcp-runtime registry info
mcp-runtime registry provision --url registry.example.com
mcp-runtime registry provision --url registry.example.com --operator-image registry.example.com/mcp-runtime-operator:latest

Push images into the runtime path

registry push can use the default in-cluster helper or switch to direct local pushes when the environment already has access.

mcp-runtime registry push --image payments:v1
mcp-runtime registry push --image payments:v1 --mode direct
mcp-runtime registry push --image payments:v1 --name payments-api

Pipeline generation and deploy

Generate MCPServer manifests

pipeline generate turns metadata files into CRD manifests that the operator can reconcile.

mcp-runtime pipeline generate --dir .mcp --output manifests
mcp-runtime pipeline generate --file .mcp/payments.yaml --output manifests

Deploy generated manifests

pipeline deploy applies a directory of generated CRDs and can override namespace placement when needed.

mcp-runtime pipeline deploy --dir manifests
mcp-runtime pipeline deploy --dir manifests --namespace mcp-servers

Access grants and agent sessions

Grant operations

Use access grant to manage MCPAccessGrant resources for entitlement and admin-side enable or disable state.

mcp-runtime access grant list
mcp-runtime access grant get payments-admin --namespace mcp-servers
mcp-runtime access grant apply --file grant.yaml
mcp-runtime access grant disable payments-admin
mcp-runtime access grant enable payments-admin

Session operations

Use access session to inspect and mutate MCPAgentSession resources that carry consent, expiry, and revocation.

mcp-runtime access session list
mcp-runtime access session get ops-agent --namespace mcp-servers
mcp-runtime access session apply --file session.yaml
mcp-runtime access session revoke ops-agent
mcp-runtime access session unrevoke ops-agent

Server resource operations

Create, apply, and export

The server tree now supports both simple creation and full manifest workflows.

mcp-runtime server create payments --image repo/payments --tag latest
mcp-runtime server create payments --file server.yaml
mcp-runtime server apply --file server.yaml
mcp-runtime server export payments --file payments.yaml

Patch, inspect, and tail

Patch live resources, inspect policy, and check runtime state without leaving the CLI.

mcp-runtime server patch payments --patch '{"spec":{"imageTag":"v2"}}'
mcp-runtime server status --namespace mcp-servers
mcp-runtime server policy inspect payments
mcp-runtime server logs payments --follow

Build images

Image build helpers still live under server build; pushing remains under registry push.

mcp-runtime server build image payments --tag v1
mcp-runtime server build image payments --dockerfile Dockerfile
mcp-runtime registry push --image payments:v1

Sentinel operations

Status, events, and restarts

Use the sentinel tree to inspect stack health, recent Kubernetes events, and restart one workload or the full stack.

mcp-runtime sentinel status
mcp-runtime sentinel events
mcp-runtime sentinel restart gateway
mcp-runtime sentinel restart --all

Logs and local access

logs accepts sentinel component names, while port-forward provides shortcuts for common service endpoints.

mcp-runtime sentinel logs ingest --since 15m --follow
mcp-runtime sentinel logs grafana --tail 500
mcp-runtime sentinel port-forward ui
mcp-runtime sentinel port-forward api --port 18080

Known component keys

sentinel logs and sentinel restart understand clickhouse, zookeeper, kafka, ingest, api, processor, ui, gateway, prometheus, grafana, otel-collector, tempo, loki, and promtail. Port-forward shortcuts are currently built in for api, ui, prometheus, and grafana.

Cluster configuration and TLS

Initialize or re-target a cluster

Use cluster init for initial kubeconfig wiring and CRD plus namespace bootstrapping before the broader setup path.

mcp-runtime cluster init
mcp-runtime cluster init --kubeconfig ~/.kube/config --context dev

Cluster config and provision

cluster config covers kubeconfig, ingress, and provider-aware kubeconfig wiring, while cluster provision exposes local and cloud entry points.

mcp-runtime cluster config --ingress traefik
mcp-runtime cluster config --provider eks --name mcp-runtime --region us-west-1
mcp-runtime cluster provision --provider kind --nodes 3
mcp-runtime cluster provision --provider eks --name prod-mcp

Cert-manager helpers

The cluster cert subtree manages TLS prerequisites for the platform registry path.

mcp-runtime cluster cert status
mcp-runtime cluster cert apply
mcp-runtime cluster cert wait --timeout 10m

Provider status today

kind and eks have active CLI paths today. The gke and aks flags are present in the cluster commands, but their kubeconfig and provisioning helpers still return planned or not implemented paths in the current code.

Useful flags and behaviors

setup flags

--registry-type, --registry-storage, --ingress, --ingress-manifest, --force-ingress-install, --with-tls, --test-mode, --without-sentinel, and the operator override flags --operator-leader-elect, --operator-metrics-addr, and --operator-probe-addr.

global debug flag

Every command inherits --debug, which turns on structured error logging from the root command.

registry push modes

registry push defaults to in-cluster, which uses a helper pod, but can switch to direct when local Docker push is the right fit. It also accepts --registry, --name, and --namespace.

cluster provider wiring

cluster config can work with kubeconfig plus cloud provider inputs. --provider eks is implemented for kubeconfig updates today, while cluster provision has active paths for kind and eks; gke and aks are still planned.

server mutation workflows

server apply, server export, and server patch cover manifest-driven operations. server patch accepts inline --patch or a --patch-file with merge, json, or strategic modes.

pipeline input and output flags

pipeline generate accepts --dir, --file, and --output. pipeline deploy accepts --dir and --namespace when you need to override metadata placement.

access list scope

access grant list and access session list default to --all-namespaces. Add --namespace when you want a narrower operational view.

sentinel logs and port-forward

sentinel logs adds --follow, --previous, --tail, and --since. sentinel port-forward adds --port and --address.

server build image

server build image accepts --dockerfile, --metadata-file, --metadata-dir, --registry, --tag, and --context before you push with registry push.

shell completion and version

The Cobra root command also exposes completion bash, completion zsh, and completion fish, plus the inherited --version flag.

Common flows

Create a local cluster path

mcp-runtime cluster provision --provider kind --nodes 3
mcp-runtime setup

Push a server image

mcp-runtime server build image payments
mcp-runtime registry push --image payments:latest

Deploy from metadata

mcp-runtime pipeline generate --dir .mcp --output manifests
mcp-runtime pipeline deploy --dir manifests

Apply access and inspect policy

mcp-runtime access grant apply --file grant.yaml
mcp-runtime access session apply --file session.yaml
mcp-runtime server policy inspect payments

Open the sentinel UI locally

mcp-runtime sentinel status
mcp-runtime sentinel port-forward ui
mcp-runtime sentinel logs api --since 10m

Patch a running server

mcp-runtime server patch payments --patch '{"spec":{"imageTag":"v2"}}'
mcp-runtime server status
mcp-runtime status

Operator-first CLI

More than a thin wrapper

The CLI already owns install planning, registry and image handling, access resource operations, status aggregation, sentinel operations, and the bridge from metadata to cluster state. That is why the docs treat it as a primary product surface instead of a footnote.