MCP Gateway — bRRAIn Docs

How bRRAIn governs outbound calls to integrations and external systems.

MCP Gateway

The MCP Gateway is the policed exit door from your bRRAIn to anywhere outside it. Every outbound call — to Slack, to GitHub, to a custom webhook, to your data warehouse, to an external LLM — passes through the Gateway. The Gateway enforces policy, signs requests where the destination expects it, and writes the audit trail.

What MCP means here

MCP stands for Multi-Channel Provisioning — the unified protocol bRRAIn uses to describe outbound channels. (It's an internal name; you'll also see "MCP" used in the broader AI community to refer to Model Context Protocol, which is a different concept. bRRAIn supports the broader MCP standard via its integrations layer; the MCP Gateway is the bRRAIn-specific governance layer that wraps it.)

What the Gateway does

  1. Routes — it knows where to send each call.
  2. Authenticates — it attaches the right credentials for the destination (OAuth bearer, API key, mTLS cert, HMAC signature).
  3. Authorizes — it checks the calling zone has permission to use the integration.
  4. Rate-limits — per-integration, per-zone, per-organization caps to keep you within vendor limits.
  5. Retries — vendor-aware retry with exponential backoff and jitter.
  6. Logs — every call's destination, timestamp, status code, and (optionally) request and response sizes.
  7. Redacts — strips secrets from any log output.

What goes through the Gateway

  • All outbound calls from extensions to integrations.
  • All outbound calls from orchestrations.
  • All outbound calls from the Handler when it uses tool-calling.
  • Webhook deliveries (outbound).
  • Notification deliveries (email, SMS, voice, Slack, etc.).

What doesn't go through the Gateway:

  • Vault reads and writes (these are internal to the pod).
  • Inter-zone messages on the platform SDK loopback.
  • System-zone telemetry to bRRAIn central monitoring (uses a dedicated channel).

Inbound counterpart

The Gateway also handles inbound webhooks from external systems. Inbound flow:

  1. The vendor calls a unique URL we provisioned for your organization.
  2. The Gateway verifies the HMAC signature using the per-integration signing secret.
  3. The Gateway dispatches the verified payload to the appropriate handler (a configured orchestration trigger, an extension's webhook endpoint, etc.).
  4. The dispatch is logged.

Unsigned or mis-signed inbound payloads are rejected with a clear error code that's visible in the integration's health pane.

Per-integration policy

Every integration carries a policy:

  • Which zones may call it.
  • Which actions may be taken (some integrations expose read-only and read-write modes).
  • Rate limits beyond the vendor's own.
  • Time-of-day allowed windows (e.g., never call HR system outside business hours).
  • Approval-gate requirements for specific actions (e.g., any DELETE call requires Sovereign approval).

You configure integration policies on Console → Integrations → [Integration] → Policy.

Approval gates

Some action classes are too sensitive to fire unattended. Configure an approval gate and the Gateway pauses the call:

  • An approval notification fires to the configured approvers.
  • The approver clicks Approve or Deny.
  • On Approve, the Gateway proceeds.
  • On Deny, the Gateway returns an error to the caller.

Common approval-gated actions:

  • Posting publicly on social media.
  • Sending bulk emails to lists above a threshold.
  • DELETE operations against production data.
  • Cross-region data writes.

Caching

The Gateway can cache vendor responses where the vendor allows:

  • Per-call TTL configurable.
  • Cache-bypass headers respected.
  • Per-zone cache namespaces (one zone's cached read isn't visible to another).

Caching reduces vendor cost and improves latency on repeat reads.

Observability

Per-integration call rate, latency, and error rate appear on the Observability dashboard. Per-call detail is in the audit log.

Failure handling

The Gateway distinguishes:

  • Vendor-down — vendor returned 5xx or timed out. Gateway retries per the configured policy.
  • Vendor-rejected — vendor returned 4xx. Gateway logs and propagates the error to the caller without retry.
  • Auth-failed — credentials are bad. Gateway logs, fires an integration-health alert, and propagates.
  • Policy-blocked — the call violates configured policy. Gateway logs and propagates a clear policy-violation error.

Why it matters

A common failure mode of unprotected automation: a script with a stale token, a bad parameter, or a bug calls a vendor a million times in a runaway loop. The Gateway's rate limits, retries, and circuit breakers stop that from being your problem.

Another common failure: a lateral-movement attacker who's compromised one extension uses it to call a vendor and exfiltrate data. The Gateway's per-zone, per-action, per-rate policy stops this from being trivial.

Where to next