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

vigil-fraud-alert-mcp