Runtime architecture and control plane.
MCP Runtime is the Kubernetes control plane for internal MCP servers. It owns cluster bootstrap, registry and ingress setup, operator reconciliation, deployment resources, rollout, and the access model that sits beside each server.
What the runtime owns
cluster and setup initialize CRDs and namespaces, configure ingress, provision clusters, and optionally wire in cert-manager based TLS.
The operator reconciles MCPServer into Deployments, Services, and Ingress objects so each server lands at a stable route.
Grants and sessions are separate resources so policy, trust ceilings, consent, expiry, and revocation stay outside deployment-only YAML.
Servers can stay direct or run behind the proxy sidecar while rollout settings still live on the same server resource.
Core resources
Declares workload, image, route, resources, tool inventory, auth, policy, session, gateway, analytics, and rollout settings.
Maps a human or agent subject to a target server, applies an admin-side maximum trust ceiling, and sets per-tool rules.
Stores consented trust, expiry, revocation, and upstream token secret references for an active agent session.
Reconciliation outputs
The operator reconciles each MCPServer into a Deployment, Service, and Ingress so the server lands on a stable route and host combination.
MCPServer.status already tracks phase, message, conditions, and readiness for deployment, service, ingress, gateway, and generated policy data.
Servers default to /{server-name}/mcp, the gateway listens on 8091, and setup provisions the mcp-runtime and mcp-servers namespaces.
Runtime topology
This architecture block is carried forward from the README so the docs keep the full platform map.
Developer / CI
|
v
+----------------------+
| mcp-runtime CLI |
+----------+-----------+
|
v
+----------------------+
| v1alpha1 surface |
| MCPServer |
| MCPAccessGrant |
| MCPAgentSession |
+----------+-----------+
|
v
+----------------------+ +----------------------+
| Operator + Registry |------->| Deployments / |
| + Ingress | | Services / Ingress |
+----------+-----------+ +----------+-----------+
| |
| gateway enabled | direct or gateway path
v v
+----------------+ /{server-name}/mcp
| MCP proxy |---------------------> MCP server
| sidecar |
+--------+-------+
|
v
+------------------------------+
| mcp-sentinel |
| ingest | processor | API |
| UI | gateway | metrics |
+------------------------------+Install and delivery flow
Use cluster init or setup to install CRDs and ensure the mcp-runtime and mcp-servers namespaces exist.
Install or point at ingress, deploy the internal registry or provision an external one, and enable TLS if the environment needs it.
Define tools, auth headers, policy mode, session requirements, analytics emission, and rollout settings on MCPServer.
Build images, push them to the selected registry, generate manifests from metadata where needed, and apply them to the cluster.
Create grants and sessions, then use the status command and sentinel surfaces to inspect runtime health and audit decisions.
Traffic and enforcement model
Without gateway mode, the reconciled service points at the MCP server directly and the server is exposed at /{server-name}/mcp.
With spec.gateway.enabled, traffic moves through the proxy sidecar first so the runtime can evaluate policy and emit audit decisions.
Tool required trust, grant max trust, and session consented trust combine to determine the effective trust available at the moment of a tool call.
Gateway headers
These header defaults are used by the proxy unless the auth config overrides them.
X-MCP-Human-ID: user-123
X-MCP-Agent-ID: ops-agent
X-MCP-Agent-Session: sess-8f1b9dCurrent scope
Alpha, but already a real platform surface
Deployment, routing, grants, sessions, gateway policy, trust, and audit flow are implemented in the current repo. Sentinel supports bearer-token validation on API and ingest surfaces, but this is not a full OAuth 2.1 authorization server.