Regulated MCP Insurance Reference Architecture

Deterministic Quoting Architecture & Enterprise Delivery Kit for European Insurance

An open-source reference implementation demonstrating how a European residential insurer exposes a deterministic, non-binding home-insurance quote funnel through Model Context Protocol (MCP) using @waniwani/sdk/mcp with server-owned validation, pure pricing rules, mandatory consent gating, and tamper-evident auditability.

Overview

Conversational interfaces are increasingly being evaluated for multi-step transactional workflows such as financial services and insurance quotation.

The primary engineering challenge is not extracting parameters from natural language. The primary challenge is preserving deterministic business authority around validation, underwriting eligibility, actuarial pricing, GDPR consent gating, state transitions, and auditability when the user interacts through a conversational assistant.

This repository provides an open-source reference implementation of that architecture. A typed Waniwani flow manages the resumable conversation, while deterministic TypeScript services own business validation, underwriting eligibility, rule-versioned pricing, persistence, and audit logging.

┌─────────────────────────┐       ┌────────────────────────────────────────────────────────┐
│  Conversational Layer   │       │               Deterministic Server Core                │
│  (MCP Client / LLM)     │ ────> │  • Strict Zod Schemas & Postcode Regex Validation      │
│  • Field extraction     │       │  • Pure-Function Pricing Formulas (Versioned Rules)   │
│  • Natural language UI  │       │  • Mandatory Consent Gate & Disclosure Attachment     │
│  • Clarification loops  │       │  • Append-Only SHA-256 Cryptographic Audit Chain      │
└─────────────────────────┘       └────────────────────────────────────────────────────────┘

The repository supports an instant, zero-credential local mode for development as well as PostgreSQL-backed and containerized deployment paths.

Related MCP server: @getplexa/mcp

Architecture & State Flow

flowchart LR
    subgraph Conversational Interface
        Client[MCP Client / User Assistant]
    end

    subgraph Northstar MCP Server
        Sanitizer[Input Sanitizer & Regex Guard]
        Flow[Waniwani Compiled Flow<br/>get_home_insurance_quote]
        Store[(Session Store: Memory / PostgreSQL)]
    end

    subgraph Deterministic Core
        Rules[Actuarial Pricing Engine v1/v2]
        Eligibility[Underwriting Eligibility Evaluator]
        ConsentGuard[Mandatory Consent Gate]
        Audit[Append-Only SHA-256 Audit Store]
    end

    Client -->|MCP Tool Calls / Interrupts| Flow
    Flow --> Sanitizer
    Flow <--> Store
    Flow --> Eligibility
    Flow --> ConsentGuard
    ConsentGuard --> Rules
    Flow --> Audit

Core Design Principles

1. Server Authority: The conversational model is strictly an extraction and rendering interface. The compiled server owns state transitions, required fields, validation, eligibility, pricing calculations, rule versions, consent gating, and audit logging.

2. Actuarial Determinism: Premiums are calculated via pure functions in compiled TypeScript (packages/rules/src/pricing.ts). AI outputs can never directly set or alter premiums, multipliers, taxes, or eligibility outcomes.

3. Explicit Consent Gating: Quote calculation is strictly blocked until explicit data processing consent is recorded ([CONSENT_REQUIRED]).

4. Tamper-Evident Auditability: Every lifecycle event appends a SHA-256 hash chaining back to session genesis (packages/audit/src/audit-store.ts).

5. Idempotency & Replay Safety: Quote calculations and adjustments accept idempotency keys and return cached quotes with audit tracking (request.replayed). Conflicting payloads on the same key are safely rejected.

6. Zero-Credential Local Run: The entire workflow runs locally out-of-the-box with zero external API keys or cloud dependencies.

Features & Capabilities

• Resumable Conversational Funnel: Genuine @waniwani/sdk/mcp state graph (createFlow, interrupt, START, END) compiled and registered as one primary MCP tool (get_home_insurance_quote).

• Multi-Country European Addressing: Regex-validated postcode formats for France (FR), Spain (ES), Portugal (PT), Germany (DE), and Italy (IT) with conversational re-asking on invalid formatting.

• Underwriting Eligibility & Referrals: Evaluates risk combinations (e.g. claims $\ge 4$, large villas $>250\text{ m}^2$) and emits explicit machine-readable reason codes.

• State Correction & Tiered Invalidation Loops: Altering previously confirmed structural risk parameters automatically invalidates active quotes and resets consent.

• Dynamic Quote Adjustment: Modify coverage tiers (essential, comfort, premium) and deductibles (€150 to €1000) on active quotes with idempotency protection.

• Official MCP Streamable HTTP Transport: Direct StreamableHTTPServerTransport integration supporting stateful sessions, /health, and /ready probes.

• Dual Persistence Adapters: Pluggable in-memory TTL store and real PostgreSQL adapter with parameterized SQL, schema migrations, and optimistic concurrency control.

• GDPR Right to Erasure: Multi-table scrubbing removing contact emails from quote_sessions and quote_history while preserving cryptographic audit validity.

Quickstart

Prerequisites

• Node.js v20.x or later

• npm v10.x or later (Docker optional for containerized PostgreSQL)

Installation & Run

# 1. Install dependencies (idempotent, local)
npm run setup

# 2. Run the full interactive demonstration
npm run demo

# 3. Run all unit, protocol, property, and integration tests
npm test

# 4. Run the 24-scenario automated evaluation benchmark
npm run eval

# 5. Execute all quality gates
npm run release-check

Example Quotation Workflow

[User]      "Hi, I need home insurance for my apartment in Paris (75008)."
[Assistant] Invokes tool: get_home_insurance_quote
[Server]    -> Interrupt: missing structural risk details (construction period, floor area, claims).

[User]      "It was built in 2010, 75 sqm, primary residence, 0 claims in past 5 years."
[Assistant] Resumes get_home_insurance_quote with risk factors
[Server]    -> Evaluates Eligibility: ELIGIBLE (Reason: RISK_CRITERIA_MET). Rule version: northstar-home-eu-v1.
            -> Interrupt: Select coverage tier and deductible.

[User]      "I'd like the Comfort tier with a €300 deductible."
[Assistant] Resumes get_home_insurance_quote
[Server]    -> Interrupt: Customer must confirm declared summary parameters.

[User]      "I confirm all details are correct."
[Assistant] Resumes get_home_insurance_quote with parametersConfirmed: true
[Server]    -> Interrupt: Explicit GDPR consent required (consent_v1_2026).

[User]      "I consent to data processing for this quotation."
[Assistant] Resumes get_home_insurance_quote with hasConsented: true
[Server]    -> QUOTE ISSUED (ID: 90484678-f868...)
               Base Annual: €180.00 | Property Multiplier: x0.9 | Deductible Discount: -€25.00
               Net Annual:  €137.00 | Tax (18%): +€24.66
               TOTAL:       €161.66 / year (€13.47 / month)
               Fingerprint: 36d5b534f844c6e43243398f3fb42436c251712183d3e0036f239a7bc168d56a (SHA-256)
               Status:      Active (Non-binding indicative)

Repository Structure

├── apps/
│   ├── mcp-server/              # Waniwani compiled flow + MCP server (Stdio / Streamable HTTP)
│   └── pricing-service/         # Fastify microservice (/health, /ready, /calculate)
├── packages/
│   ├── domain/                  # Zod validation schemas, error taxonomy, state machine
│   ├── rules/                   # Actuarial pricing engine, versioned rules (v1, v2), eligibility
│   ├── persistence/             # SessionStore (InMemory with TTL & PostgreSQL)
│   ├── audit/                   # Append-only audit store with SHA-256 hash chaining & redactor
│   └── security/                # Input sanitization, prompt injection detection, data catalog
├── docs/
│   ├── architecture/            # STRIDE threat model, Hosted vs VPC blueprints, Data Flow
│   ├── decisions/               # Architecture Decision Records (ADRs)
│   ├── demo/                    # Interactive demo scripts and technical walkthroughs
│   ├── enterprise-delivery/     # Discovery questionnaire, RTM, RACI, UAT, and Go-Live plans
│   ├── guides/                  # Technical deep dives and architecture failure mode guides
│   ├── operations/              # Operational runbook, migrations, and audit verification
│   ├── procurement/             # 35-question security questionnaire, DPIA template, data catalog
│   ├── IMPLEMENTATION.md        # Technical implementation summary
│   ├── RELEASE_VALIDATION.md    # Release verification record
│   └── VERIFICATION_MATRIX.md   # Requirement-to-test traceability matrix
├── tests/                       # Unit, protocol, integration, property (fast-check), and adversarial tests
├── scripts/
│   ├── demo-flow.ts             # Interactive demonstration runner
│   ├── run-eval.ts              # 24-scenario automated evaluation benchmark
│   ├── verify-audit.ts          # Cryptographic audit hash chain verification CLI
│   ├── migrate.ts               # Database schema migration runner
│   └── anonymize-session.ts     # Right-to-erasure / session anonymization utility
├── Makefile                     # Canonical developer command interface
├── docker-compose.yml           # Local multi-container deployment stack
└── .github/workflows/ci.yml     # Automated CI verification pipeline

Testing & Verification

All architectural guarantees and invariants are verified via automated tests and reproducible evaluation benchmarks:

Detailed requirement-to-test traceability is documented in docs/VERIFICATION_MATRIX.md.

Deployment Modes

1. Local Stdio Mode (Default)

Used by MCP desktop clients (e.g. Claude Desktop, IDE extensions). Sessions and audit trails are stored in-memory with automatic TTL cleanup.

npm run dev

2. Streamable HTTP Network Mode

Exposes standard MCP endpoints over HTTP using StreamableHTTPServerTransport with JSON-RPC streaming, /health, and /ready probes.

MCP_TRANSPORT=http PORT=3000 npm run dev

3. Docker Compose Stack (PostgreSQL + MCP Server + Pricing Service)

Runs the full multi-service architecture locally with durable PostgreSQL storage and database migrations.

docker compose up --build

Enterprise Delivery & Security Documentation

The repository includes enterprise documentation templates and blueprints designed for regulated technical reviews:

• Technical Implementation Summary

• Requirements & Verification Matrix

• Release Validation Record

• Architecture Decision Records (ADRs)

• Enterprise Delivery Pack (Discovery, RTM, RACI, UAT, Go-Live, Rollback)

• Enterprise Security & Procurement Library (35-Question Questionnaire, DPIA, Shared Responsibility)

• STRIDE Threat Model

• Operations Runbook

• Technical Deep Dive Guide

• Demo Walkthrough Guide

Security & Privacy

• Data Minimization: No personal data (e.g. email) is collected or processed until the explicit quotation delivery step.

• Cryptographic Auditability: All state transitions and calculations append to an immutable, hash-chained audit log.

• Automated PII Redaction: Structured log metadata masks email addresses and authentication tokens before hashing or logging.

• Right to Erasure: Session anonymization utility scrubs PII across sessions and quote history tables while preserving audit chain integrity.

• Prompt Injection Defense: Input sanitizers validate formats and reject instruction injection attempts in address and metadata fields.

Known Limitations

1. Synthetic Reference Insurer: Northstar Home Insurance EU is a synthetic reference model for demonstration and educational purposes.

2. Non-Binding Quotations: Generated quotes are indicative estimates and do not bind formal underwriting policies or collect financial payment.

3. Illustrative Actuarial Factors: Pricing formulas and risk multipliers in packages/rules/src/v1.ts are demonstration values and do not represent proprietary actuarial tables.

Non-Affiliation Statement & License

This repository is an independent open-source reference implementation built with public MIT-licensed packages (@waniwani/sdk, @modelcontextprotocol/sdk). It is not affiliated with, endorsed by, or sponsored by Waniwani AI, Anthropic, or any commercial insurer.

Licensed under the MIT License.