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

<img src="assets/bloodhound_avatar.png" alt="Fraud Detection Bloodhound" width="300" style="border-radius: 15px;" align="right">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)

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

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

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

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

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

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

11. 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)

Tool	Description
analyze_transaction	Transaction fraud analysis using 46-feature Isolation Forest + Autoencoder ensemble
detect_behavioral_anomaly	Behavioral biometrics anomaly detection (keystroke, mouse, touch)
assess_network_risk	Graph centrality-based fraud ring detection
generate_risk_score	Weighted composite risk score (agent-aware weighting)
explain_decision	SHAP-based explainable AI with agent-specific reasoning

Agent-to-Agent Transaction Protection (6 tools)

Tool	Description
classify_traffic_source	Detect human vs AI agent traffic (9 agent protocols)
verify_agent_identity	Validate agent credentials (API keys, JWT, registry)
analyze_agent_transaction	Full agent-aware pipeline (identity + fingerprint + mandate + transaction)
verify_transaction_mandate	Check transactions against agent spending mandates
detect_agent_collusion	Directed graph detection of coordinated agent behavior
score_agent_reputation	Longitudinal reputation from trust, history, consistency

Model Management & Operations (8 tools)

Tool	Description
train_models	ML training pipeline with SMOTE and optional Optuna tuning (requires optional deps)
get_model_status	Model source, configuration, and saved model paths
analyze_batch	Batch transaction analysis with prediction caching
get_inference_stats	Inference engine statistics and cache performance
generate_synthetic_dataset	Generate labeled fraud datasets (CSV/JSON) for evaluation
analyze_dataset	Analyze stored CSV/JSON datasets for fraud patterns
run_benchmark	Performance benchmark with throughput and latency percentiles
health_check	System health with model status, cache stats, resource usage

Defense Compliance (5 tools)

Tool	Description
assess_insider_threat	Insider threat assessment (28 NITTF behavioral indicators)
generate_siem_events	Export events in CEF/LEEF/Syslog with MITRE ATT&CK enrichment
evaluate_cleared_personnel	SEAD 4/6 cleared personnel analytics and CE checks
get_compliance_dashboard	NITTF maturity, KRIs, compliance posture, executive summary
generate_threat_referral	Formal case referral or personnel security action report

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:

Module	Flag	Required For
monitoring.py	MONITORING_AVAILABLE	Prometheus metrics, structured logging
training_pipeline.py	TRAINING_AVAILABLE	train_models tool
models/autoencoder.py	AUTOENCODER_AVAILABLE	Autoencoder ensemble member
explainability.py	EXPLAINABILITY_AVAILABLE	SHAP-based explanations
integration.py	SYNTHETIC_DATA_AVAILABLE	Synthetic dataset generation, benchmarks
security_utils.py	SECURITY_UTILS_AVAILABLE	Input sanitization, rate limiting

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:

Server	Purpose
enhanced-memory-mcp	4-tier persistent memory with semantic search
agent-runtime-mcp	Persistent task queues and goal decomposition
agi-mcp	Full AGI orchestration with 21 tools
cluster-execution-mcp	Distributed task routing across nodes
node-chat-mcp	Inter-node AI communication
ember-mcp	Production-only policy enforcement

See agentic-system-oss for the complete framework.