Skip to content
MCP Gateway

Runtime Architecture

Concepts

Runtime Architecture

Section titled “Runtime Architecture”

Enterprise MCP Gateway splits durable governance from runtime execution. The control plane owns source registration, approval, policy metadata, credential binding metadata, audit configuration, and session metadata. The data plane executes discovery and calls against approved projections, with policy, credential, routing, session, and audit checks on the hot path.

Audience

Section titled “Audience”
  • Architects placing product state in the control plane or data plane.
  • Operators reviewing managed or self-hosted topology.
  • Security reviewers checking where identity, policy, credentials, sessions, and audit happen.

What is this?

Section titled “What is this?”

This page explains the runtime model from docs/ARCHITECTURE.md. The gateway is not a proxy that forwards arbitrary URLs. It consumes approved MCP server snapshots and selected API operation mappings. Those projections tell the data plane what can be exposed, how to route it, what policy and credential modes apply, and what metadata must be audited.

When do I use it?

Section titled “When do I use it?”

Use this page before changing service boundaries, debugging a stale runtime projection, explaining tenant and environment scope, or deciding whether a new capability belongs in V1.

What happens?

Section titled “What happens?”

Runtime flow:

  1. A client connects through an approved client surface.
  2. The gateway authenticates user, service, or workload identity and resolves agent context.
  3. Discovery is filtered through Cedar policy. Unauthorized tools are hidden.
  4. Tool calls are schema-validated and policy-evaluated.
  5. The credential broker resolves an allowed credential mode without returning secret material to the caller.
  6. The backend router sends calls to a registered MCP server or to the API-to-MCP adapter for an approved generated tool.
  7. Registered MCP server transports are limited to streamable_http, legacy_sse, or approved self-hosted stdio adapter profiles.
  8. The session router maintains client session IDs, backend session IDs where needed, affinity, reconnect, drain, terminate, and revoke behavior.
  9. Audit records authentication, policy decision, policy version, credential mode, projection version, upstream transport, session lifecycle, API adapter behavior, admin changes, and revocation metadata.

Tenant and environment are gateway scope. After request or config boundary parsing, tenant and environment IDs are explicit in registry records, policy context, credentials, sessions, audit, and route decisions.

What can go wrong?

Section titled “What can go wrong?”
  • A data plane may have a stale or missing projection, so discovery or calls must fail closed or show safe stale/error state.
  • A caller may not carry tenant, environment, actor, agent, or client-surface context.
  • A registered MCP transport may be outside the approved set.
  • A stdio adapter can only be a trusted local or self-hosted profile with argv arrays and safe refs. It is not arbitrary shell execution.
  • API-to-MCP calls fail before upstream when selection, approval, host, method, schema, credential, timeout, or size checks fail.
  • Optional systems such as ClickHouse, NATS, Kafka, Redpanda, Terraform modules, and Kubernetes operator behavior are not V1 defaults.

Source truth

Section titled “Source truth”

Next

Section titled “Next”

Type set in Geist, Source Serif 4, and Departure Mono.