MCP Runtime API
Current v1alpha1 resource and gateway reference
Website GitHub
API

API reference for runtime, policy, and analytics.

The control plane is split between deployment config on MCPServer, access grants on MCPAccessGrant, consent or session state on MCPAgentSession, and audit events emitted through mcp-sentinel.

Core resources

MCPServer

Runtime deployment spec plus gateway, auth, policy, session, tool inventory, rollout, and analytics settings.

MCPAccessGrant

Who can use which server, for which tools, and with what admin-side maximum trust level.

MCPAgentSession

Server-side consented trust, expiry, revocation, and upstream token references per agent session.

MCPServer surface

Workload and routing

Image, imageTag, registryOverride, replicas, port, servicePort, ingressPath, ingressHost, ingressClass, and ingress annotations live directly on MCPServer.

Resources and environment

CPU and memory requests or limits, literal env vars, secret-backed env vars, and image pull secrets are part of the same resource.

Policy and identity

Tool inventory, auth mode, policy mode, session requirements, and gateway config define how a server is reached and governed.

Analytics and rollout

Analytics emission config and rollout strategy stay with the server resource so runtime, gateway, and release behavior can ship together.

Advanced delivery knobs

useProvisionedRegistry, imagePullSecrets, gateway.stripPrefix, session.upstreamTokenHeader, analytics.apiKeySecretRef, rollout.maxUnavailable, and rollout.maxSurge are also part of the current type.

Enums and semantics

Auth modes

none, header, and oauth exist on the type. The working path today is header-based identity extraction.

Policy modes

allow-list enforces explicit policy. observe keeps the decision path visible without the same deny posture.

Trust levels

low, medium, and high are used on tools, grants, and sessions. Effective trust is the minimum of grant and session trust.

Rollout strategies

RollingUpdate, Recreate, and Canary are available on spec.rollout.

MCPServer example

Use spec.gateway.enabled to put a transparent proxy in front of the server route, spec.tools to declare tool inventory, and spec.analytics.enabled to emit audit events.

apiVersion: mcpruntime.org/v1alpha1
kind: MCPServer
metadata:
  name: payments
  namespace: mcp-servers
spec:
  image: registry.example.com/payments-mcp
  port: 8088
  ingressHost: mcp.example.com
  ingressPath: /payments/mcp
  gateway:
    enabled: true
  auth:
    mode: header
    humanIDHeader: X-MCP-Human-ID
    agentIDHeader: X-MCP-Agent-ID
    sessionIDHeader: X-MCP-Agent-Session
  policy:
    mode: allow-list
    defaultDecision: deny
    enforceOn: call_tool
    policyVersion: v1
  session:
    required: true
    store: kubernetes
    headerName: X-MCP-Agent-Session
    maxLifetime: 24h
    idleTimeout: 1h
  tools:
    - name: list_invoices
      requiredTrust: low
    - name: refund_invoice
      requiredTrust: high
  analytics:
    enabled: true
    ingestURL: http://mcp-sentinel-ingest.mcp-sentinel.svc.cluster.local:8081/events
  rollout:
    strategy: Canary
    canaryReplicas: 1

Grants and sessions

MCPAccessGrant.spec.disabled and MCPAgentSession.spec.revoked are the current hard switches for turning off access without deleting the underlying object history.

MCPAccessGrant

apiVersion: mcpruntime.org/v1alpha1
kind: MCPAccessGrant
metadata:
  name: payments-ops-agent
  namespace: mcp-servers
spec:
  serverRef:
    name: payments
  subject:
    humanID: user-123
    agentID: ops-agent
  maxTrust: high
  policyVersion: v1
  toolRules:
    - name: list_invoices
      decision: allow
      requiredTrust: low
    - name: refund_invoice
      decision: allow
      requiredTrust: high

MCPAgentSession

apiVersion: mcpruntime.org/v1alpha1
kind: MCPAgentSession
metadata:
  name: sess-8f1b9d
  namespace: mcp-servers
spec:
  serverRef:
    name: payments
  subject:
    humanID: user-123
    agentID: ops-agent
  consentedTrust: medium
  expiresAt: "2026-03-26T12:00:00Z"
  upstreamTokenSecretRef:
    name: payments-upstream-token
    key: access-token

Status and validation rules

MCPServer status

phase, message, Kubernetes conditions, and readiness booleans for deployment, service, ingress, gateway, and policy generation are part of the status surface.

Grant and session status

Both MCPAccessGrant and MCPAgentSession expose phase, message, and conditions so the operator can reflect observed access state back to users.

Validation rules in code

analytics.enabled requires gateway.enabled, gateway.port must differ from spec.port, and canary rollouts require a positive canaryReplicas value that stays below total replicas.

Security and auth

Implemented today

spec.auth can model oauth, but the practical path today is header-based identity extraction at the gateway plus optional bearer-token validation against JWKS, issuer, and audience on mcp-sentinel services.

Not implemented yet

There is no /authorize, /token, /.well-known/oauth-authorization-server, PKCE flow, or Dynamic Client Registration endpoint in this release.

Practical model

Use the gateway for human, agent, and session identity; use MCPAccessGrant and MCPAgentSession for trust and revocation; and use OIDC-issued bearer tokens only where mcp-sentinel services validate them.

Gateway flow and headers

Enforcement point

Authorization is evaluated at call_tool or tools/call, not at discovery time.

Allow-list first

Missing grants or missing tool rules deny by default unless the policy explicitly overrides the default decision.

Audit on allow and deny

The gateway emits decision, reason, trust levels, human, agent, session, server, cluster, and namespace fields.

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

mcp-sentinel API

The bundled analytics stack exposes a read API over the ClickHouse-backed event stream.

GET /api/events?limit=100
GET /api/stats
GET /api/sources
GET /api/event-types
GET /api/events/filter?server=payments&decision=deny&agent_id=ops-agent&limit=50
Filter fields

source, event_type, server, namespace, cluster, human_id, agent_id, session_id, decision, tool_name.

Audit payload fields

decision, reason, policy_version, required_trust, admin_trust, consented_trust, effective_trust.

Transport fields

method, path, status, latency_ms, bytes_in, bytes_out, rpc_method.

Setup integration

Bundled by default

mcp-runtime setup builds the runtime operator image, the gateway proxy image, the analytics service images, and deploys the bundled analytics stack by default. Use --without-sentinel if you only want the runtime or operator footprint.