Control plane vs data plane

MCP Gateway is split into two planes with different jobs and different trust boundaries. Understanding the split explains almost every other concept in these docs.

The control plane owns durable configuration and approvals; the data plane enforces the approved configuration on every request and reports audit back.

Control plane — :8080

The control plane is the system of record. It owns the MCP server registry, the API source registry, policy authoring and versions, approval workflows, credential bindings, audit configuration, identity/RBAC, and session metadata. It serves the REST admin API that the console and gatewayctl call.

Nothing the control plane stores takes effect on live traffic until it is compiled into a runtime projection and handed to the data plane.

Data plane — :8081

The data plane is the hot path. On every request it authenticates the caller, resolves agent context, filters discovery through policy, schema‑validates tool calls, evaluates policy, brokers a credential without exposing secret material, and routes to either a registered MCP server or the API‑to‑MCP adapter. It exposes a narrow surface: a runtime projection read, runtime audit, and the MCP invocation endpoints.

Approved MCP upstreams use one of three explicit transports — streamable_http, legacy_sse, or stdio (trusted self‑hosted only) — chosen from the projection, never inferred from a URL.

How state flows between the planes

• Configuration projection (control → data). Approved registry records, policy, and credential metadata are compiled into a versioned projection (projectionVersion, active/desired versions, reload state) and pushed to data planes. Hot reload means an approval takes effect without a restart.
• Runtime audit (data → control). Each data plane reports metadata‑only runtime audit events back — policy decision, policy version, projection version, upstream transport, latency/status, and a safe error category. No raw arguments or secrets ever cross this boundary.

Tenant and environment are gateway scope

Tenant and environment describe the gateway’s execution boundary (data plane, region, cluster, private‑route context) — not upstream capabilities. A self‑hosted gateway starts with one configured tenant and a default environment (commonly tenant_local / prod). After boundary parsing, tenant and environment_id are explicit in registry records, policy context, credential resolution, sessions, and audit events. The control plane exposes the resolved scope at GET /v1/control-plane/scope.

Tip

This separation is why an emergency revocation is fast and safe: the control plane records the decision and re‑projects, and every data plane enforces it on the next request — without trusting the data plane to hold authority of its own.

See it illustrated See the two planes and the projection / audit flows illustrated.