Skip to content

Architecture

MCP Runtime is a Kubernetes-native platform for publishing, governing, and observing MCP servers. This page is the high-level map; deeper detail lives in the linked guides below.

Planes

flowchart TB
    subgraph clients [Clients]
        CLI[mcp-runtime CLI]
        UI[Platform dashboard]
        Agent[Agent adapters]
        MCP[MCP clients]
    end

    subgraph control [Control plane]
        API[Platform API]
        K8s[Kubernetes API]
        Op[MCPServer operator]
    end

    subgraph runtime [Runtime plane]
        Ing[Ingress / Traefik]
        GW[mcp-gateway sidecar]
        Srv[MCP server pods]
    end

    subgraph data [Data and policy]
        Grant[MCPAccessGrant]
        Session[MCPAgentSession]
        Reg[Container registry]
    end

    subgraph obs [Observability]
        Ingest[Sentinel ingest]
        CH[ClickHouse / Grafana]
    end

    CLI --> API
    CLI -. "admin --use-kube only" .-> K8s
    UI --> API
    Agent --> Ing
    MCP --> Ing
    API --> K8s
    K8s --> Op
    Op --> Srv
    Op --> Grant
    Op --> Session
    Ing --> GW --> Srv
    GW --> Grant
    GW --> Session
    CLI --> Reg
    API --> Reg
    GW --> Ingest --> CH
    API --> CH

What each layer owns

Layer Owns Read next
Runtime Bootstrap, setup, registry workflow, MCPServer reconciliation, grants/sessions, rollout Runtime
Sentinel Gateway sidecar policy enforcement, analytics ingest, dashboards Sentinel
Platform API Teams, identity, platform-backed deploy/push, adapter sessions API
Multi-team Namespace isolation, team RBAC, Traefik watch scope Multi-Team Isolation

Typical request path

  1. An MCP client (or agent adapter) calls https://mcp.<domain>/<server>/mcp.
  2. Ingress routes to the server pod; the mcp-gateway sidecar evaluates MCPAccessGrant + MCPAgentSession policy before forwarding to the app.
  3. Allowed tool calls emit analytics events through ingest → Kafka → processor → ClickHouse; Grafana surfaces usage and traces.

Local scaffolding commands (server init, access grant init, access session init) write manifests on the workstation only; they do not call the platform API or Kubernetes.

Control-plane changes (setup, auth login, server deploy, access grant apply, and admin-only access session apply) flow through the CLI or platform API into Kubernetes; the operator materializes Deployments, Services, Ingress, and policy ConfigMaps. Sessions for agent traffic are usually issued through POST /api/runtime/adapter/sessions; explicit session manifests are admin-only on the platform API. Admin-only --use-kube or kubectl apply bypasses platform auth and requires operator RBAC.

See Request Flows for allow/deny sequence diagrams, component-level paths, and E2E scenario mapping.

Deployment shapes

Shape When to use Guide
Kind + --test-mode Local contributor development Contributor Local Kind
k3s lab (HTTP registry) Single-node evaluation Deployment Targets - k3s lab
k3s / on-prem + bundled HTTPS Public domain with Let's Encrypt Deployment Targets, k3s Deployment Runbook
Managed Kubernetes + external registry EKS, GKE, AKS Deployment Targets - Managed Kubernetes