MCP Gateway Spec · v0.1 · draft

A governed surface for insurance agents.

Auth. IR pinning. Decision replay. Multi-carrier composition. Joule-metered audit. The wire between policy admins.

Gateway primitives

IR types

2PC

Composition mode

LLMs in the control plane

Read v0.1 spec InsuranceOS

What it is

Three properties. One gateway.

Governed surface

Auth, RBAC, rate limits, audit, observability, human-in-loop hooks. Agents request operations; the gateway approves or rejects. Inference advises; the gateway is the control plane.

IR-pinned sessions

Every session pins to specific rate-plan, coverage-form, appetite, claim-event, and submission IR versions. Carrier API contracts drift; pinned sessions don't.

Multi-carrier composition

Place risk across N carriers as a single atomic operation. 2-phase commit where supported, saga where not. One consolidated audit trail with per-carrier sub-traces.

Operations

Eight primary primitives.

carrier.compose.atomic

(steps[]) → ComposedTrace

Multi-carrier transaction. All-or-nothing across N carrier gateways. 2-phase commit where supported, saga where not.

Artifact: ComposedTrace with per-carrier sub-traces

ir.pin

(contract_id, version) → SessionPin

Pin agent session to specific rate-plan / coverage-form / appetite / claim-event / submission IR versions. Required for replayability.

Artifact: Session pin record

decision.replay

(trace_id) → ReplayedDecision

Reproduce a prior decision byte-for-byte against current IR. Regulatory exam primitive; adverse-action defense; drift detection.

Artifact: Replayed decision + drift report

appetite.match

(risk_ir) → {carrier, program, confidence, basis}

Deterministic appetite query with attributed basis. Inference fallback only when explicitly authorized.

Artifact: Match list with per-result basis

form.assemble

(coverage_form_ir, schedule) → PolicyForm

Deterministic form assembly from coverage-form-IR. Replaces free-generation of policy documents.

Artifact: Signed policy form + assembly trace

rate.diff

(plan_v1, plan_v2) → FilingDelta

Filing-grade diff between rate plans. Per-state regulatory impact flags. Factor, territory, ILF, base-rate deltas.

Artifact: FilingDelta with state-by-state impact

claim_event.append

(claim_id, event_ir) → AppendReceipt

Append-only Merkle ledger. FNOL → reserve → payment → subrogation → close. Reinsurance bordereaux are byproducts.

Artifact: Append receipt with prev-event hash

hitl.require

(op, threshold_policy_id) → HITLPolicy

First-class human-approval primitive, separate from auth. Threshold policies versioned; approvals signed.

Artifact: HITL policy attachment + approval log

IR Primitives

Five typed contracts.

All IR types are semver + content-hashed. Pinned at session start. Drift detected and surfaced.

rate-plan-IR

Factors, territory tables, base rates, ILFs, min/max premiums, by-state effective dates, filing IDs, prior-version pointer.

coverage-form-IR

Coverage parts, exclusions, conditions, definitions, endorsements. ISO/AAIS forms by edition. Schedule-binding rules.

claim-event-IR

Event type, timestamp, actor, monetary delta, reserve delta, document refs, signed prev-event hash (Merkle).

appetite-IR

Class codes (NAICS / SIC / ISO GL), state in/out, hazard limits, premium bounds, expiring-carrier rules, exception predicates.

submission-IR

ACORD-aligned canonical form. Source-of-truth field provenance per attribute. Carrier-specific required-field tables.

Audit Trail

One record per operation.

Every gateway operation produces a signed audit record. The joules field on every model call is non-optional: operations are energy-metered.

{
  "trace_id": "...",
  "parent_trace_id": "...",
  "ts_start": "...", "ts_end": "...",
  "actor": { "principal_id": "...", "role": "...", "on_behalf_of": "..." },
  "operation": { "name": "...", "version": "..." },
  "ir_pins": [{ "kind": "...", "id": "...", "version": "...", "hash": "..." }],
  "inputs":   { "schema_version": "...", "hash": "...", "redacted_payload_ref": "..." },
  "rule_evaluations": [{ "rule_id": "...", "version": "...", "result": "...", "basis": "..." }],
  "model_calls":     [{ "provider": "...", "model_id": "...", "prompt_hash": "...", "response_hash": "...", "tokens": 0, "joules": 0 }],
  "decision":        { "outcome": "...", "confidence": 0.0, "basis": "deterministic | inference | hybrid" },
  "hitl":            { "required": true, "approver": "...", "approval_ts": "...", "policy_id": "...", "policy_version": "..." },
  "outputs":         { "schema_version": "...", "hash": "...", "artifact_refs": [] },
  "prev_event_hash": "...",
  "signature":       "..."
}

Composition

N carriers. One atomic operation.

Composition session

Server-side state holding: pinned IR set, target carrier-gateway list, 2PC coordinator, compensation registry. Output: one consolidated trace with per-carrier sub-traces.

prepare(op) → reservation_id
commit(reservation_id) | abort(reservation_id)

Saga fallback

Carriers without 2PC are downgraded to best-effort with saga + declared compensation functions per op. The session emits a saga trace with applied compensations on partial failure.

idempotency keys per step
retry with exponential backoff per per-carrier policy
compensation log signed and replayable

Status

v0.1 — draft.

Spec text is CC-BY-4.0. Reference code is Apache-2.0. v1.0 ships when at least one carrier-core adapter and one MGA-side client implement five of the eight primary operations against pinned IR with signed audit.

Maintained by

InsuranceOS

Substrate

Joule Cloud · ais.transaction.science

Companion specs

ais.insuranceos.science · ops.insuranceos.science