Advanced Fraud Detection MCP

Fraud detection and anomaly analysis for financial security — with AI agent-to-agent transaction protection.

Part of the Agentic System - a 24/7 autonomous AI framework with persistent memory.

Overview

An open-source Model Context Protocol (MCP) server for fraud detection using machine learning and behavioral analysis. This system combines behavioral biometrics, anomaly detection, network graph analysis, and AI agent behavioral fingerprinting for fraud prevention.

Key Features

Core Detection (Active by Default)

• Isolation Forest: Anomaly detection for real-time transaction screening
• Autoencoder Ensemble: PyTorch-based deep learning anomaly detection using reconstruction error scoring. Ensemble with Isolation Forest (configurable 60/40 weighting).
• Behavioral Biometrics: Keystroke dynamics (Isolation Forest), mouse movement patterns (One-Class SVM), touch screen patterns (LOF)
• Network Graph Analysis: NetworkX-based graph centrality metrics (degree, clustering coefficient, betweenness, closeness) for fraud ring detection
• 46-Feature Pipeline: Comprehensive feature engineering with cyclical encoding, z-scores, and velocity features

Agent-to-Agent Transaction Protection

• Traffic Classification: Automatic detection of AI agent vs human traffic (Stripe ACP, Visa TAP, Mastercard Agent Pay, Google AP2, PayPal, Coinbase, OpenAI, Anthropic, x402)
• Agent Identity Verification: API key format validation, JWT token expiry checks, JSON-backed agent registry
• Agent Behavioral Fingerprinting: Per-agent Isolation Forest baselines (8 features, max 1000 observations/agent)
• Mandate Compliance: Spending limits, merchant whitelists/blocklists, time windows, geographic restrictions
• Collusion Detection: Directed graph analysis for circular flows, temporal clustering, and volume anomalies
• Agent Reputation Scoring: Longitudinal trust from history, consistency, and collusion safety (weighted 40/25/25/10)

Defense Insider Threat Compliance

• 28 Behavioral Indicators from the NITTF Insider Threat Guide (EO 13587)
• SIEM Integration: CEF (ArcSight), LEEF (QRadar), Syslog RFC 5424 with MITRE ATT&CK enrichment
• Cleared Personnel Monitoring: SEAD 4/6 continuous evaluation, 13 adjudicative guidelines
• Compliance Dashboard: NITTF maturity scoring, KRIs, model drift detection

Optional (Requires Manual Invocation)

• XGBoost: Available via the train_models tool when training_pipeline.py dependencies are installed. Not part of the default detection path.
• SMOTE Resampling: Class balancing for imbalanced fraud datasets (via train_models)
• Optuna Hyperparameter Tuning: Automated hyperparameter optimization (via train_models)
• MLflow Tracking: Experiment tracking for training runs (via train_models)

Experimental (Disabled by Default)

• Graph Neural Network: models/gnn_fraud_detector.py exists but requires torch-geometric and is disabled (train_gnn=False). Not used in the default detection pipeline.

Explainability

• SHAP-based Explanations: Feature importance and decision reasoning with agent-specific context. Graceful fallback when SHAP is unavailable.

Architecture

Core Components (server.py)

1. TransactionAnalyzer — 46-feature extraction, Isolation Forest + Autoencoder ensemble scoring with configurable weights. Supports model persistence and hot-reload.

2. BehavioralBiometrics — Keystroke dynamics (Isolation Forest), mouse patterns (One-Class SVM), touch patterns (LOF). Extracts 10 statistical features per modality.

3. NetworkAnalyzer — Builds NetworkX graphs of entity connections. Calculates degree, clustering coefficient, betweenness/closeness centrality.

4. UserTransactionHistory — Thread-safe, bounded per-user transaction history for velocity analysis with LRU eviction.

Agent Protection Pipeline (server.py)

1. TrafficClassifier — Classifies transactions as human/agent/unknown. Recognizes 9 agent protocols.

2. AgentIdentityRegistry — Thread-safe JSON-backed registry tracking agent trust scores and transaction history.

3. AgentIdentityVerifier — Validates credentials via registry lookup, API key format, and JWT token expiry.

4. AgentBehavioralFingerprint — Per-agent Isolation Forest baselines (8 features, min 10 observations before activation).

5. MandateVerifier — Stateless mandate compliance: max_amount, daily_limit, allowed/blocked merchants, time windows.

6. CollusionDetector — Directed graph for circular flows, temporal clustering, volume anomalies with LRU eviction.

7. AgentReputationScorer — Longitudinal reputation: trust (40%), history (25%), behavioral consistency (25%), collusion safety (10%).

Risk Scoring

Human traffic: Transaction 50%, Behavioral 30%, Network 20%.
Agent traffic: Equal weighting across all available components.
Thresholds: CRITICAL >= 0.8, HIGH >= 0.6, MEDIUM >= 0.4, LOW < 0.4.

Technical Specifications

• Language: Python 3.10+
• ML Libraries: scikit-learn, PyTorch (autoencoder)
• Graph Processing: NetworkX
• API: FastMCP (Model Context Protocol)
• Testing: pytest (830+ tests, 88%+ coverage)

Installation

Quick Start

# Clone the repository
git clone https://github.com/marc-shade/fraud-detection-mcp
cd fraud-detection-mcp

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install core dependencies
pip install -r requirements.txt

# Install optional training/dev dependencies
pip install -r requirements-dev.txt      # Testing and linting
pip install -r requirements-optional.txt  # XGBoost, GNN, benchmarking

Claude Code Integration

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "fraud-detection-mcp": {
      "command": "/path/to/fraud-detection-mcp/venv/bin/python",
      "args": ["/path/to/fraud-detection-mcp/server.py"],
      "env": {
        "FRAUD_DETECT_MODEL_PATH": "/path/to/fraud-detection-mcp/models",
        "FRAUD_DETECT_LOG_LEVEL": "INFO"
      }
    }
  }
}

MCP Tools (24 total)

Core Fraud Detection (5 tools)

Agent-to-Agent Transaction Protection (6 tools)

Model Management & Operations (8 tools)

Defense Compliance (5 tools)

Example Usage

# Analyze a transaction
result = mcp_client.call("analyze_transaction", {
    "transaction_id": "txn_123",
    "amount": 5000.00,
    "merchant": "Electronics Store",
    "location": "New York, NY",
    "timestamp": "2025-09-26T14:30:00Z"
})

# Result includes risk score, confidence, and explanation
{
    "risk_score": 0.72,
    "risk_level": "HIGH",
    "confidence": 0.85,
    "is_anomaly": true,
    "details": {
        "isolation_forest_score": -0.3,
        "autoencoder_score": 0.8,
        "ensemble_score": 0.72
    }
}

Algorithm Details

Isolation Forest (Active)

• Purpose: Fast anomaly detection for real-time transaction screening
• Complexity: O(n log n), handles high-dimensional data
• Use Case: First-line defense, scores all transactions by default

Autoencoder (Active)

• Purpose: Deep learning anomaly detection via reconstruction error
• Architecture: PyTorch fully-connected autoencoder
• Use Case: Ensemble member with Isolation Forest for improved detection

Behavioral Biometrics (Active)

• Keystroke Dynamics: Timing patterns via Isolation Forest (5 dwell + 5 flight features)
• Mouse Biometrics: Movement patterns via One-Class SVM
• Touch Analytics: Screen interaction via Local Outlier Factor (LOF)

Network Graph Analysis (Active)

• Graph Centrality: Degree, clustering coefficient, betweenness, closeness centrality
• Fraud Ring Detection: Identifies suspicious clusters via graph metrics
• Implementation: NetworkX directed/undirected graphs

XGBoost (Optional — requires train_models)

• Purpose: Gradient boosting for supervised fraud classification
• Availability: Only active after training with labeled data via train_models tool
• Dependencies: Requires xgboost, imbalanced-learn, optuna (in requirements-optional.txt)

Graceful Degradation

The server starts even when optional dependencies are missing:

Security Notice

• Transport Security: The MCP server does not provide TLS. If exposed over a network, configure a reverse proxy with TLS termination.
• Authentication: The server does not implement authentication. Access control must be handled by the MCP client or network layer.
• Data at Rest: Transaction data and model files are stored unencrypted. Apply filesystem-level encryption if required by your security policy.
• Input Sanitization: When security_utils.py is available, inputs are sanitized against XSS/SQLi patterns and rate-limited.
• Dependencies: Review requirements.txt and pin versions for production deployments. Run bandit -r . -x ./tests for security scanning.

Known Limitations

• Models initialize with synthetic data: Default models have not been trained on real fraud data. Use train_models with your own labeled dataset for production accuracy.
• Performance is environment-dependent: No benchmark numbers are published because results vary significantly by hardware, data distribution, and model configuration. Run run_benchmark on your own infrastructure to measure.
• No continuous/adaptive learning: Model retraining is manual via the train_models tool. There is no online learning or automatic model refresh.
• No encryption at rest: The server does not encrypt stored data. This must be handled at the infrastructure level.
• No GDPR/PCI-DSS/SOX compliance: The server does not implement regulatory compliance controls. The defense compliance modules (insider threat, SIEM, cleared personnel) address federal insider threat standards, not financial regulatory compliance.

Defense Compliance Architecture

compliance/
  __init__.py                  # Package exports
  insider_threat.py            # EO 13587 / NITTF insider threat detection (28 indicators)
  siem_integration.py          # CEF/LEEF/Syslog event generation & correlation
  cleared_personnel.py         # SEAD 4/6 cleared personnel analytics
  dashboard_metrics.py         # NITTF maturity, KRIs, compliance posture

All compliance modules run locally with no external service dependencies, are thread-safe, and use graceful degradation.

Contributing

This is an open-source project. Contributions welcome for:

• New detection algorithms
• Performance optimizations
• Test coverage improvements
• Documentation

See CONTRIBUTING.md for guidelines.

License

MIT License - See LICENSE file for details

Part of the MCP Ecosystem

This server integrates with other MCP servers for comprehensive AGI capabilities:

See agentic-system-oss for the complete framework.