Vigil Fraud Alert — API + MCP Server

Proximity-based card fraud detection for Vigil / Ebenova Solutions.

Turns the Vigil proximity engine into a callable REST API and MCP server with Claude-powered transaction analysis, risk scoring, and AML report generation.

Quick Start

cd vigil-fraud-alert-mcp
npm install
npm run build          # esbuild — fast, no memory issues
npm run start:http     # REST API + MCP on http://localhost:3000

Test it's running:

curl http://localhost:3000/
curl http://localhost:3000/api/v1/health

Claude Desktop Setup (stdio MCP)

Add to %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "vigil-fraud-alert": {
      "command": "node",
      "args": ["C:/projects/ProximityGuard/vigil-fraud-alert-mcp/dist/index.js"]
    }
  }
}

Restart Claude Desktop. You'll have 13 tools available instantly.

MCP Tools (13 total)

Core Authorization

| Tool | What it does | |------|-------------| | vigil_authorize | Run a transaction through the proximity engine → approve/decline | | vigil_get_card | Get card config + GPS freshness | | vigil_update_card_mode | Switch home / travel / lockdown | | vigil_update_gps | Push fresh GPS snapshot | | vigil_add_travel_plan | Add country + date range travel plan |

Transactions & Alerts

| Tool | What it does | |------|-------------| | vigil_list_transactions | Query decision history | | vigil_confirm_transaction | Record "was this you?" response | | vigil_list_alerts | List fraud alerts by status/severity | | vigil_update_alert | Advance alert through investigation workflow | | vigil_get_risk_profile | Live risk score 0–100 per card |

AI-Powered (Claude Haiku / Sonnet)

| Tool | What it does | |------|-------------| | vigil_analyze_transaction | AI risk analysis — factors, SMS copy, recommendation | | vigil_block_transaction | Emergency card lockdown + alert escalation | | vigil_generate_report | Full AML compliance report (Claude Sonnet) |

REST API

Core endpoints

POST   /api/v1/authorize                  # Proximity engine decision
GET    /api/v1/cards/:id                  # Card config + GPS age
PATCH  /api/v1/cards/:id/mode             # { mode: "home"|"travel"|"lockdown" }
POST   /api/v1/cards/:id/gps              # GPS snapshot update
POST   /api/v1/cards/:id/travel-plans     # Add travel plan
GET    /api/v1/transactions               # ?card_id=&approved=&limit=
POST   /api/v1/transactions/:id/confirm   # { confirmed: "yes"|"no" }
GET    /api/v1/alerts                     # ?card_id=&status=&severity=
PATCH  /api/v1/alerts/:id                 # { status, notes }
GET    /api/v1/cards/:id/risk             # Risk profile

AI endpoints (Anthropic-powered)

POST   /api/v1/fraud/analyze              # AI transaction analysis
GET    /api/v1/fraud/score/:card_id       # Risk score 0–100 + explanation
POST   /api/v1/fraud/report               # AML compliance report

Example: Authorize a transaction

curl -X POST http://localhost:3000/api/v1/authorize \
  -H "Content-Type: application/json" \
  -d '{
    "card_id": "card_01",
    "merchant_name": "Safeway",
    "merchant_city": "Calgary",
    "merchant_country": "CA",
    "merchant_network_id": "safeway_yyc_001",
    "merchant_mcc": "5411",
    "merchant_lat": 51.049,
    "merchant_lng": -114.08,
    "amount_cents": 4250,
    "currency": "cad"
  }'

Example: AI fraud analysis

curl -X POST http://localhost:3000/api/v1/fraud/analyze \
  -H "Content-Type: application/json" \
  -d '{ "transaction_id": "txn_002" }'

Example: AML report

curl -X POST http://localhost:3000/api/v1/fraud/report \
  -H "Content-Type: application/json" \
  -d '{ "card_id": "card_01", "period_start": "2026-03-01", "period_end": "2026-03-31" }'

Architecture

Stripe/Lithic webhook → POST /api/v1/authorize
                               ↓
                    Proximity Engine (issuer-agnostic)
                    decision-engine.ts / haversine
                               ↓
                    AuthorizationDecision
                    + auto-create FraudAlert
                               ↓
                    (async) POST /api/v1/fraud/analyze
                    → Claude Haiku: risk score, SMS copy
                               ↓
                    (async) Twilio SMS → user
                               ↓
                    User replies NO → vigil_block_transaction
                    → card.mode = lockdown
                    → Stripe card.update({ status: 'canceled' })

Demo Cards

| Card | Location | Mode | |------|----------|------| | card_01 | Calgary, CA | home (radius 50km) | | card_02 | Toronto→London | travel (GB plan active) | | card_03 | New York, US | lockdown |

What AI Does / Does Not Do

Does: Pattern analysis, human-readable risk explanations, SMS copy generation, AML report writing, anomaly reason generation.

Does not: Hold funds, make final block decisions, store card numbers (PCI). Final authority to block always rests with the user or human analyst. Stripe/Lithic hold the regulated licenses — Vigil is software-only.

Environment Variables

PORT=3000                  # HTTP port (default 3000)
TRANSPORT=http             # http or stdio (default stdio)
# Anthropic API key is handled by the platform (Claude.ai / Claude Desktop)
# In standalone deployment, set: ANTHROPIC_API_KEY=sk-ant-...

Part of Ebenova Solutions — Vigil LLC