Advanced Fraud Detection MCP

Detección de fraude y análisis de anomalías para la seguridad financiera: con protección de transacciones agente a agente mediante IA.

Parte del Agentic System, un framework de IA autónomo 24/7 con memoria persistente.

Descripción general

Un servidor de código abierto del Model Context Protocol (MCP) para la detección de fraude mediante aprendizaje automático y análisis de comportamiento. Este sistema combina biometría de comportamiento, detección de anomalías, análisis de grafos de red y huella conductual de agentes de IA para la prevención del fraude.

Related MCP server: Fraud Detection MCP

Características principales

Detección principal (activa por defecto)

• Isolation Forest: Detección de anomalías para la evaluación de transacciones en tiempo real

• Autoencoder Ensemble: Detección de anomalías de aprendizaje profundo basada en PyTorch mediante puntuación de error de reconstrucción. Ensemble con Isolation Forest (ponderación configurable 60/40).

• Biometría de comportamiento: Dinámica de tecleo (Isolation Forest), patrones de movimiento del ratón (One-Class SVM), patrones de pantalla táctil (LOF)

• Análisis de grafos de red: Métricas de centralidad de grafos basadas en NetworkX (grado, coeficiente de agrupamiento, intermediación, cercanía) para la detección de anillos de fraude

• Pipeline de 46 características: Ingeniería de características exhaustiva con codificación cíclica, puntuaciones z y características de velocidad

Protección de transacciones agente a agente

• Clasificación de tráfico: Detección automática de tráfico de agentes de IA frente a tráfico humano (Stripe ACP, Visa TAP, Mastercard Agent Pay, Google AP2, PayPal, Coinbase, OpenAI, Anthropic, x402)

• Verificación de identidad de agentes: Validación del formato de claves API, comprobación de caducidad de tokens JWT, registro de agentes respaldado por JSON

• Huella conductual de agentes: Líneas base de Isolation Forest por agente (8 características, máximo 1000 observaciones/agente)

• Cumplimiento de mandatos: Límites de gasto, listas blancas/negras de comercios, ventanas de tiempo, restricciones geográficas

• Detección de colusión: Análisis de grafos dirigidos para flujos circulares, agrupamiento temporal y anomalías de volumen

• Puntuación de reputación de agentes: Confianza longitudinal basada en el historial, la consistencia y la seguridad frente a colusión (ponderación 40/25/25/10)

Cumplimiento de defensa contra amenazas internas

• 28 indicadores de comportamiento de la Guía de Amenazas Internas del NITTF (EO 13587)

• Integración SIEM: CEF (ArcSight), LEEF (QRadar), Syslog RFC 5424 con enriquecimiento MITRE ATT&CK

• Supervisión de personal con habilitación de seguridad: Evaluación continua SEAD 4/6, 13 pautas de adjudicación

• Panel de cumplimiento: Puntuación de madurez NITTF, KRIs, detección de deriva de modelos

Opcional (requiere invocación manual)

• XGBoost: Disponible a través de la herramienta train_models cuando las dependencias de training_pipeline.py están instaladas. No forma parte de la ruta de detección predeterminada.

• Remuestreo SMOTE: Equilibrio de clases para conjuntos de datos de fraude desbalanceados (mediante train_models)

• Ajuste de hiperparámetros con Optuna: Optimización automatizada de hiperparámetros (mediante train_models)

• Seguimiento con MLflow: Registro de experimentos para ejecuciones de entrenamiento (mediante train_models)

Experimental (deshabilitado por defecto)

• Red neuronal de grafos: models/gnn_fraud_detector.py existe pero requiere torch-geometric y está deshabilitado (train_gnn=False). No se utiliza en el pipeline de detección predeterminado.

Explicabilidad

• Explicaciones basadas en SHAP: Importancia de las características y razonamiento de decisiones con contexto específico del agente. Degradación gradual cuando SHAP no está disponible.

Arquitectura

Componentes principales (server.py)

1. TransactionAnalyzer — Extracción de 46 características, puntuación de ensemble Isolation Forest + Autoencoder con pesos configurables. Soporta persistencia de modelos y recarga en caliente.

2. BehavioralBiometrics — Dinámica de tecleo (Isolation Forest), patrones de ratón (One-Class SVM), patrones táctiles (LOF). Extrae 10 características estadísticas por modalidad.

3. NetworkAnalyzer — Construye grafos NetworkX de conexiones entre entidades. Calcula grado, coeficiente de agrupamiento, centralidad de intermediación/cercanía.

4. UserTransactionHistory — Historial de transacciones por usuario acotado y seguro para subprocesos, para análisis de velocidad con expulsión LRU.

Pipeline de protección de agentes (server.py)

5. TrafficClassifier — Clasifica transacciones como humanas/de agente/desconocidas. Reconoce 9 protocolos de agentes.

6. AgentIdentityRegistry — Registro respaldado por JSON y seguro para subprocesos que realiza un seguimiento de las puntuaciones de confianza de los agentes y del historial de transacciones.

7. AgentIdentityVerifier — Valida credenciales mediante consulta al registro, formato de clave API y caducidad de tokens JWT.

8. AgentBehavioralFingerprint — Líneas base de Isolation Forest por agente (8 características, mínimo 10 observaciones antes de la activación).

9. MandateVerifier — Cumplimiento de mandatos sin estado: max_amount, daily_limit, comercios permitidos/bloqueados, ventanas de tiempo.

10. CollusionDetector — Grafo dirigido para flujos circulares, agrupamiento temporal, anomalías de volumen con expulsión LRU.

11. AgentReputationScorer — Reputación longitudinal: confianza (40%), historial (25%), consistencia de comportamiento (25%), seguridad frente a colusión (10%).

Puntuación de riesgo

Tráfico humano: Transacción 50%, Comportamiento 30%, Red 20%. Tráfico de agentes: Ponderación equitativa entre todos los componentes disponibles. Umbrales: CRITICAL >= 0.8, HIGH >= 0.6, MEDIUM >= 0.4, LOW < 0.4.

Especificaciones técnicas

• Lenguaje: Python 3.10+

• Librerías de ML: scikit-learn, PyTorch (autoencoder)

• Procesamiento de grafos: NetworkX

• API: FastMCP (Model Context Protocol)

• Pruebas: pytest (más de 830 pruebas, más del 88% de cobertura)

Instalación

Inicio rápido

# 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

Integración con Claude Code

Añade lo siguiente a la configuración de tu Claude Desktop:

{
  "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"
      }
    }
  }
}

Herramientas MCP (24 en total)

Detección de fraude principal (5 herramientas)

Protección de transacciones agente a agente (6 herramientas)

Gestión y operaciones de modelos (8 herramientas)

Cumplimiento de defensa (5 herramientas)

Ejemplo de uso

# 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
    }
}

Detalles del algoritmo

Isolation Forest (activo)

• Propósito: Detección rápida de anomalías para la evaluación de transacciones en tiempo real

• Complejidad: O(n log n), maneja datos de alta dimensionalidad

• Caso de uso: Primera línea de defensa, puntúa todas las transacciones por defecto

Autoencoder (activo)

• Propósito: Detección de anomalías mediante aprendizaje profundo a través del error de reconstrucción

• Arquitectura: Autoencoder totalmente conectado en PyTorch

• Caso de uso: Miembro del ensemble con Isolation Forest para una detección mejorada

Biometría de comportamiento (activa)

• Dinámica de tecleo: Patrones de temporización mediante Isolation Forest (5 características de pulsación + 5 de intervalo)

• Biometría de ratón: Patrones de movimiento mediante One-Class SVM

• Analítica táctil: Interacción con la pantalla mediante Local Outlier Factor (LOF)

Análisis de grafos de red (activo)

• Centralidad de grafos: Grado, coeficiente de agrupamiento, centralidad de intermediación y cercanía

• Detección de anillos de fraude: Identifica clústeres sospechosos mediante métricas de grafos

• Implementación: Grafos dirigidos/no dirigidos con NetworkX

XGBoost (opcional: requiere train_models)

• Propósito: Gradient boosting para clasificación supervisada de fraude

• Disponibilidad: Solo activo después del entrenamiento con datos etiquetados mediante la herramienta train_models

• Dependencias: Requiere xgboost, imbalanced-learn, optuna (en requirements-optional.txt)

Degradación gradual

El servidor se inicia incluso cuando faltan dependencias opcionales:

Aviso de Seguridad

• Seguridad del Transporte: El servidor MCP no proporciona TLS. Si se expone a través de una red, configure un proxy inverso con terminación TLS.

• Autenticación: El servidor no implementa autenticación. El control de acceso debe gestionarse mediante el cliente MCP o la capa de red.

• Datos en Reposo: Los datos de transacciones y los archivos de modelos se almacenan sin cifrar. Aplique cifrado a nivel de sistema de archivos si su política de seguridad lo requiere.

• Saneamiento de Entradas: Cuando security_utils.py está disponible, las entradas se sanean contra patrones XSS/SQLi y se limita su tasa.

• Dependencias: Revise requirements.txt y fije las versiones para entornos de producción. Ejecute bandit -r . -x ./tests para el escaneo de seguridad.

Limitaciones Conocidas

• Los modelos se inicializan con datos sintéticos: Los modelos predeterminados no han sido entrenados con datos reales de fraude. Use train_models con su propio conjunto de datos etiquetado para obtener precisión en producción.

• El rendimiento depende del entorno: No se publican cifras de referencia porque los resultados varían significativamente según el hardware, la distribución de datos y la configuración del modelo. Ejecute run_benchmark en su propia infraestructura para medirlo.

• Sin aprendizaje continuo ni adaptativo: El reentrenamiento de modelos es manual mediante la herramienta train_models. No hay aprendizaje en línea ni actualización automática.

• Sin cifrado en reposo: El servidor no cifra los datos almacenados. Esto debe gestionarse a nivel de infraestructura.

• Sin cumplimiento de GDPR/PCI-DSS/SOX: El servidor no implementa controles de cumplimiento normativo. Los módulos de cumplimiento de defensa (amenazas internas, SIEM, personal con autorización) abordan estándares federales de amenazas internas, no cumplimiento normativo financiero.

Arquitectura de Cumplimiento de Defensa

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

Todos los módulos de cumplimiento se ejecutan localmente sin dependencias de servicios externos, son seguros para subprocesos y utilizan degradación gradual.

Contribuciones

Este es un proyecto de código abierto. ¡Las contribuciones son bienvenidas!:

• Nuevos algoritmos de detección

• Optimizaciones de rendimiento

• Mejoras en la cobertura de pruebas

• Documentación

Consulte CONTRIBUTING.md para obtener las pautas.

Licencia

Licencia MIT: consulte el archivo LICENSE para obtener más detalles.

Parte del Ecosistema MCP

Este servidor se integra con otros servidores MCP para capacidades integrales de IAG:

Consulte agentic-system-oss para obtener el framework completo.