Gateway

The Gateway is the one internal MCP server that is the only path from any Runner to any internal system. Tools are authored once, are self-describing, and become auto-discoverable to every Runner. Every call flows through a single chokepoint — which is exactly what makes a unified audit log and a single policy enforcement point possible.

Status

Designed, not yet built. rba-hub-mcp is the seed — today it exposes the catalog read-only. It gets generalized into the tool-proxy and policy plane, living in a new service repo (e.g. rba-gateway), not in this one. See the Platform Roadmap for sequencing.

Why a Gateway at all

A Runner could, in principle, call internal APIs directly. We deliberately don’t allow that. Routing every tool call through one server buys four things a gateway-free design can’t:

1. One audit log. Every tool call → one append-only sink. “How many Runners touched Jira this week, and which?” has a single answer.
2. One policy enforcement point. Token scope, rate limits, and write-gating are enforced in one place, not re-implemented per Runner.
3. Tools authored once. A tool is described once and is discoverable to every Runner — no copy-paste integration per agent.
4. Credentials never reach the Runner. The Gateway holds the real credentials and injects them at the boundary; the Runner only ever sees the tool interface.

Responsibilities

Responsibility	Approach	Pattern source
Tool registry	Tools authored once, self-describing, auto-discoverable to all Runners	Stripe Toolshed (~500 tools)
Auto-generation	If RBA services expose OpenAPI specs, generate MCP tools from them	Uber IDL crawl (10,000+ services)
Identity & tokens	Integrate RBA’s IdP (Entra) → mint short-lived, audience-scoped, single-hop tokens per call	Uber STS (via OIDC, not SPIFFE)
Tiered gating	First-party tools auto-approved; third-party gated harder	Uber tiering
Write protection	Block mutable endpoints by default; rate-limit writes; explicit scope to mutate	Uber guardrails
Unified audit log	Every tool call → one append-only sink	The thing a gateway-free design can’t give

How Runners reference Gateway tools

A Runner’s allowedTools are scoped Gateway tool references, not raw API calls:

"allowedTools": ["gateway:jira.read", "gateway:git.read"]

The Gateway mints a token for exactly those scopes, for a single hop, with a short time-to-live — so a token issued for one Runner to call one service can’t be replayed against another. Read-only scopes (*.read, *.list, *.get) are the default; write scopes require an explicit grant and gate the Runner behind a security review before it can reach maturity: stable (see Runners).

How the catalog and Gateway connect

The Gateway owns the tool source of truth. This repo never duplicates it: the Gateway publishes a committed or cached tools-catalog.json that the site renders read-only. The build never blocks on a live service — if the Gateway is down, the catalog still builds from the last published snapshot.

Identity: OIDC, not a service mesh

We mint short-lived, audience-scoped, single-hop tokens through RBA’s existing IdP (Entra) over OIDC. We are not building SPIFFE/SPIRE — that’s for service-mesh scale RBA likely doesn’t have, and scoped OIDC tokens cover the requirement at this scale. The full attested actor chain travels in the token so every participant in a call is attributable, not just the immediate caller.