Skip to content

runtime.md

Latest commit

 

History

History
166 lines (130 loc) · 7.14 KB

runtime.md

File metadata and controls

166 lines (130 loc) · 7.14 KB

Runtime

The runtime is the Kubernetes-native control plane for MCP servers. It owns the manager, registry, broker wiring, cluster bootstrap, ingress setup, operator reconciliation, deployment resources, rollout, and the access model that sits beside each server before requests reach the Sentinel request path.

Higher-level than ingress and service mesh. The runtime sits above lower-level networking infrastructure and models MCP-specific delivery, access, and rollout concerns. It is not a generic data plane for arbitrary cluster traffic.

What the runtime owns

Area Responsibility
Bootstrap cluster and setup initialize CRDs and namespaces, configure ingress, provision clusters, optionally wire cert-manager TLS.
Registry workflow Registry commands and setup wiring give teams a controlled place to publish and pull MCP server images.
Server delivery The operator reconciles MCPServer into Deployments, Services, and Ingress so each server lands at a stable route.
Access and consent Grants and sessions are separate resources so policy, trust ceilings, consent, expiry, and revocation stay outside deployment-only YAML.
Brokered rollout Servers can stay direct or run behind the proxy sidecar while rollout settings live on the same server resource.

Core resources

classDiagram
    class MCPServer {
      +image, imageTag
      +port, publicPathPrefix
      +ingressHost, ingressPath
      +tools[]
      +auth, policy, session
      +gateway.enabled
      +analytics.enabled
      +rollout
      +status
    }
    class MCPAccessGrant {
      +serverRef
      +subject (humanID, agentID)
      +maxTrust
      +toolRules[]
      +disabled
      +status
    }
    class MCPAgentSession {
      +serverRef
      +subject
      +consentedTrust
      +expiresAt
      +revoked
      +upstreamTokenSecretRef
      +status
    }
    MCPServer "1" o-- "many" MCPAccessGrant : referenced by
    MCPServer "1" o-- "many" MCPAgentSession : referenced by
    MCPAccessGrant "1" .. "1" MCPAgentSession : evaluated together
Loading

See the API reference for full field semantics.

Reconciliation outputs

For every MCPServer, the operator reconciles:

  • Deployment — image, replicas, resource requests/limits, env, image-pull secrets.
  • Service — ClusterIP exposing spec.servicePort → spec.port.
  • Ingress — routes spec.publicPathPrefix as /<prefix>/mcp, or explicit spec.ingressHost + spec.ingressPath, to the Service with per-class annotations (Traefik / NGINX / Istio).
  • Policy ConfigMap — rendered from the matching MCPAccessGrant + MCPAgentSession resources, consumed by the proxy sidecar when gateway.enabled.

MCPServer.status exposes:

  • phase — Pending → PartiallyReady → Ready.
  • message — human-readable progress.
  • conditions — standard Kubernetes condition slice.
  • Per-resource readiness booleans: deploymentReady, serviceReady, ingressReady, gatewayReady, policyReady.
  • ingressReady defaults to strict mode: the Ingress must publish status.loadBalancer.ingress[]. Set operator env MCP_INGRESS_READINESS_MODE=permissive for dev or NodePort-style ingress controllers that route traffic without publishing load-balancer status; permissive mode treats an Ingress with rules as ready.

Useful defaults

  • Servers default to /{server-name}/mcp; set spec.publicPathPrefix to choose the public path prefix explicitly.
  • Hostless path-based routing is supported through spec.publicPathPrefix; otherwise provide spec.ingressHost or configure the operator default host.
  • Container port defaults to 8088, service port to 80.
  • Gateway listens on 8091.
  • setup provisions the mcp-runtime and mcp-servers namespaces.
  • Default ingress class is traefik; override via spec.ingressClass.

Topology

flowchart TB
    Dev[Developer / CI] --> CLI[mcp-runtime CLI]
    CLI --> CRD[v1alpha1 surface<br/>MCPServer / MCPAccessGrant / MCPAgentSession]
    CRD --> Op[Operator + Registry + Ingress]
    Op --> K8s[Deployments / Services / Ingress]

    K8s -->|gateway disabled| Direct["/{server-name}/mcp → MCP server"]
    K8s -->|gateway enabled| Proxy[mcp-proxy sidecar]
    Proxy --> MCP[MCP server]
    Proxy --> Stack[Services Stack<br/>ingest / processor / API / UI / observability]
Loading

Install and delivery flow

flowchart LR
    A[01. Initialize cluster<br/>cluster init / setup] --> B[02. Configure ingress + registry]
    B --> C[03. Describe servers<br/>MCPServer YAML]
    C --> D[04. Publish + deploy images<br/>registry push, pipeline deploy]
    D --> E[05. Grant access<br/>access grant / session apply]
    E --> F[06. Observe<br/>status, sentinel, UI]
Loading
Step Commands
Initialize cluster cluster init, setup, bootstrap
Configure ingress + registry cluster config --ingress traefik, registry provision
Describe servers hand-written MCPServer YAML or metadata in .mcp/
Publish + deploy server build image, registry push, pipeline generate / deploy, server apply
Grant access access grant apply, access session apply
Observe status, sentinel status, sentinel port-forward ui

Traffic and enforcement model

Mode Behavior
Direct No gateway.enabled. Service points at the MCP server directly. Server is exposed at /{server-name}/mcp.
Gateway spec.gateway.enabled: true. Traffic flows through the proxy sidecar; identity, policy, audit, and telemetry happen in one place.
Trust evaluation Tool requiredTrust, grant maxTrust, and session consentedTrust combine to determine effective trust at tool-call time.

Gateway headers

These header names are defaults; override via spec.auth.{humanIDHeader,agentIDHeader,sessionIDHeader}.

X-MCP-Human-ID:    user-123
X-MCP-Agent-ID:    ops-agent
X-MCP-Agent-Session: sess-8f1b9d

Operator internals (high-level)

The operator is a single-controller controller-runtime manager:

  1. Watches MCPServer (and owns Deployment / Service / Ingress).
  2. On reconcile, fills defaults via setDefaults, persists spec changes if defaults were added.
  3. Resolves the image string (respecting imageTag, registryOverride, and PROVISIONED_REGISTRY_URL).
  4. Builds image-pull secrets, including auto-creating a docker-config secret from provisioned-registry env vars.
  5. Reconciles Deployment → Service → Ingress in order.
  6. Computes per-resource readiness, sets phase and conditions, writes status.

Source walkthroughs live under internals/cmd-operator.md.

Current scope

Implemented and stable enough to evaluate:

  • Deployment, routing, image pull, registry handling.
  • Grants, sessions, gateway policy generation.
  • Trust evaluation and audit-event flow.
  • Multi-ingress class support (Traefik, NGINX, Istio, generic).

Not yet:

  • Full OAuth 2.1 authorization server flows.
  • Multi-cluster federation.

Next

  • CLI — every command and flag.
  • API — full CRD reference with examples.
  • Sentinel — what happens after traffic enters the gateway.