Aller au contenu

Documentation MCP Analyzer

Serveur Model Context Protocol basé sur HTTP pour la surveillance de la latence réseau et l'analyse intelligente. Le serveur MCP fonctionne en se connectant à l'API Latencetech déjà existante afin de communiquer avec la base de données Analyzer elle-même.

Fonctionnalités

Surveillance principale

  • Interroger la latence sur tous les protocoles de latence (TCP, UDP, HTTP, HTTPS, ICMP, TWAMP)
  • Analyse de la santé de la connectivité avec des KPI complets
  • Surveillance de la qualité du signal radio (RSSI, RSRP, RSRQ, SINR)
  • Prévision prédictive de la latence avec intervalles de confiance
  • Données de performance corrélées à la géolocalisation
  • Surveillance des métriques système (CPU, RAM, stockage, charge)
  • Mesures de débit et de qualité Lifbe

Analyse intelligente

  • Détection d'anomalies : Détecte les anomalies réseau sur tous les protocoles
  • Tendances de performance : Analyse les tendances de performance des agents par rapport aux références historiques
  • Alertes de dégradation : Identifie les agents montrant une dégradation des performances
  • Analyse de corrélation : Détecte les modèles entre agents indiquant des problèmes à l'échelle du réseau
  • Rapports de santé : Génère des rapports complets sur la santé du réseau avec des recommandations
  • Classements des agents : Classe les agents par métriques de performance et tendances

Configuration

Prérequis

Le serveur MCP nécessite que le port 12098 soit ouvert sur la machine.

Variables d'environnement

Définissez les valeurs directement dans docker-compose.yml :

environment:
  # REQUIS : Remplacez par votre clé API
  - API_KEY=your-api-key-here

  # REQUIS : Remplacez par une clé sécurisée qui sera utilisée pour créer des tokens
  - ADMIN_KEY=change-this-secure-admin-key

  # SERVER_HOST : Laissez vide pour la détection automatique de l'IP externe, 
  # OU définissez l'IP de votre VM (ex : 192.168.1.100)
  # OU définissez votre DNS (ex : demo.example.com)
  - SERVER_HOST=

  # ENABLE_HTTPS : Définir à 'false' UNIQUEMENT lors de l'utilisation d'une adresse DNS
  # Gardez-le à true si vous utilisez une adresse IP (par défaut)
  - ENABLE_HTTPS=true

  # ENABLE_OAUTH : Définir à 'false' pour désactiver les points de terminaison OAuth (Claude Web ne fonctionnera pas)
  # Gardez 'true' pour le support de Claude Web (par défaut : true)
  # Définir 'false' pour le support des tokens bearer uniquement
  # Si activé, toute personne ayant l'adresse MCP peut s'y connecter sans vérification
  - ENABLE_OAUTH=false

  # Optionnel
  - LOG_LEVEL=INFO
  - API_TIMEOUT=120
  - HTTP_PORT=12098
  - DEFAULT_CUSTOMER_ID=0
  - DEFAULT_AGENT_ID=1

Notes de configuration importantes :

  • API_KEY : Requis pour l'accès à l'API backend
  • ADMIN_KEY : Requis pour créer/gérer les tokens d'accès
  • Configuration HTTPS :
  • Pour Claude Desktop avec IP : Définir ENABLE_HTTPS=true pour les certificats auto-signés

  • Pour Claude Web : Vous devez utiliser un domaine avec SSL valide (voir Configuration SSL ci-dessous)

  • ENABLE_OAUTH :

  • ENABLE_OAUTH=true → Tous les 5 points de terminaison OAuth enregistrés, Claude Web peut se connecter
  • ENABLE_OAUTH=false → Points de terminaison OAuth non enregistrés, seuls les tokens bearer fonctionnent
  • Les points de terminaison de gestion des tokens (/admin/tokens/*) fonctionnent toujours indépendamment du paramètre OAuth

Les journaux afficheront :

INFO: OAuth endpoints enabled
# ou
INFO: OAuth endpoints disabled - bearer token only mode

Configuration SSL pour Claude Web

Claude Web nécessite un certificat SSL de confiance et ne peut pas utiliser de certificats auto-signés.

Sous-domaine avec Nginx + Let's Encrypt

  1. Ajouter un enregistrement DNS A pour un sous-domaine (ex : mcp.yourdomain.com → IP de votre serveur)

  2. Créer la configuration nginx (/etc/nginx/sites-available/mcp.yourdomain.com) :

server {
    server_name mcp.yourdomain.com;

    location / {
        proxy_pass          http://localhost:12098;
        proxy_set_header    Host $http_host;
        proxy_set_header    X-Real-IP $remote_addr;
        proxy_set_header    X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header    X-Forwarded-Proto $scheme;
        proxy_read_timeout  90;

        # Support pour les connexions longues
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }

    listen 80;
}
  1. Activer le site et obtenir le certificat SSL :
sudo ln -s /etc/nginx/sites-available/mcp.yourdomain.com /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
sudo certbot --nginx -d mcp.yourdomain.com
  1. Mettre à jour mcp-server.yml :
- ENABLE_HTTPS=false
  1. Redémarrer le conteneur :
docker compose down
docker compose up -d

Intégration client MCP

Claude Web (claude.ai)

Exigences : - Certificat SSL valide (les certificats auto-signés ne fonctionneront PAS) - Doit utiliser un sous-domaine avec Let's Encrypt ou une CA de confiance similaire - OAuth doit être activé (ENABLE_OAUTH=true)

Claude Web utilise automatiquement l'authentification OAuth 2.1 :

  1. Allez dans Paramètres Claude → Connecteurs
  2. Cliquez sur "Ajouter un connecteur personnalisé"
  3. Nom : Latency Monitoring
  4. URL du serveur MCP distant : https://mcp.yourdomain.com (doit utiliser SSL de confiance)
  5. Laissez les champs OAuth vides (le serveur gère l'enregistrement dynamique)
  6. Cliquez sur "Ajouter" - Claude lancera automatiquement le flux OAuth
  7. Approuvez l'autorisation (auto-approuvée par le serveur, pas de vérification réelle)
  8. Connexion établie avec token d'accès généré

Comment ça fonctionne : - Claude découvre les points de terminaison OAuth via .well-known/oauth-authorization-server - Le serveur auto-approuve l'autorisation et génère un token d'accès - Token automatiquement géré par Claude (pas de gestion manuelle de token nécessaire) - Le token expire après 30 jours et peut être renouvelé

Claude Desktop

Claude Desktop peut utiliser des certificats auto-signés avec une solution de contournement.

Claude Desktop nécessite le proxy mcp-remote avec token bearer :

1) Créer un token d'accès :

curl -k -X POST "https://localhost:12098/admin/tokens/create?name=claude-desktop" \
  -H "X-Admin-Key: your-admin-key-here"

Réponse :

{
  "token": "TOKEN-CREATED",
  "name": "claude-desktop"
}

2) Configurer Claude Desktop :

Pour les certificats auto-signés (adresse IP) :

{
  "mcpServers": {
    "latency-mcp": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://your.vm.ip.address:12098",
        "--header",
        "Authorization: Bearer ${AUTH_TOKEN}"
      ],
      "env": {
        "AUTH_TOKEN": "TOKEN-CREATED",
        "NODE_TLS_REJECT_UNAUTHORIZED": "0"
      }
    }
  }
}

Pour SSL de confiance (sous-domaine avec Let's Encrypt) :

{
  "mcpServers": {
    "latency-mcp": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.yourdomain.com",
        "--header",
        "Authorization: Bearer ${AUTH_TOKEN}"
      ],
      "env": {
        "AUTH_TOKEN": "TOKEN-CREATED"
      }
    }
  }
}

Note de sécurité : NODE_TLS_REJECT_UNAUTHORIZED=0 désactive la validation du certificat SSL et ne devrait être utilisé qu'en développement ou dans des environnements réseau de confiance. Pour la production, utilisez un sous-domaine avec Let's Encrypt.

3) Redémarrez Claude Desktop

Cursor

Cursor prend en charge les serveurs MCP distants via token bearer.

1) Créer un token d'accès :

curl -k -X POST "https://localhost:12098/admin/tokens/create?name=cursor" \
  -H "X-Admin-Key: your-admin-key-here"

2) Configurer Cursor dans .cursor/mcp.json (niveau projet) ou ~/.cursor/mcp.json (global) :

Pour SSL de confiance (sous-domaine avec Let's Encrypt) :

{
  "mcpServers": {
    "latency-mcp": {
      "url": "https://mcp.yourdomain.com",
      "headers": {
        "Authorization": "Bearer TOKEN-CREATED"
      }
    }
  }
}

Pour les certificats auto-signés (adresse IP) :

Utilisez le proxy mcp-remote :

{
  "mcpServers": {
    "latency-mcp": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://your.vm.ip.address:12098",
        "--header",
        "Authorization: Bearer ${AUTH_TOKEN}"
      ],
      "env": {
        "AUTH_TOKEN": "TOKEN-CREATED",
        "NODE_TLS_REJECT_UNAUTHORIZED": "0"
      }
    }
  }
}

3) Rechargez Cursor et vérifiez que le serveur apparaît dans Paramètres Cursor > MCP

Google Antigravity

Google Antigravity prend en charge les serveurs MCP distants via token bearer.

1) Créer un token d'accès :

curl -k -X POST "https://localhost:12098/admin/tokens/create?name=antigravity" \
  -H "X-Admin-Key: your-admin-key-here"

2) Configurer Antigravity dans ~/.gemini/config/mcp_config.json (global) ou .agents/mcp_config.json (workspace). Vous pouvez également ouvrir ce fichier depuis Agent panel > ... > MCP Servers > Manage MCP Servers > View raw config.

Important : Antigravity utilise serverUrl (et non url) pour les serveurs MCP basés sur HTTP distants.

Pour SSL de confiance (sous-domaine avec Let's Encrypt) :

{
  "mcpServers": {
    "latency-mcp": {
      "serverUrl": "https://mcp.yourdomain.com",
      "headers": {
        "Authorization": "Bearer TOKEN-CREATED"
      }
    }
  }
}

Pour les certificats auto-signés (adresse IP) :

Utilisez le proxy mcp-remote :

{
  "mcpServers": {
    "latency-mcp": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://your.vm.ip.address:12098",
        "--header",
        "Authorization: Bearer ${AUTH_TOKEN}"
      ],
      "env": {
        "AUTH_TOKEN": "TOKEN-CREATED",
        "NODE_TLS_REJECT_UNAUTHORIZED": "0"
      }
    }
  }
}

3) Redémarrez Antigravity ou actualisez les serveurs MCP depuis Settings > Customizations > Installed MCP Servers

Autres clients MCP

Pour tout client MCP prenant en charge les tokens bearer :

  1. Créer un token (voir section de gestion des tokens ci-dessous)
  2. Configurer le client pour envoyer l'en-tête Authorization: Bearer <token>
  3. Se connecter à l'URL de votre serveur

Gestion des tokens

Créer des tokens

Créer de nouveaux tokens d'accès pour les clients :

curl -k -X POST "https://localhost:12098/admin/tokens/create?name=my-client" \
  -H "X-Admin-Key: your-admin-key-here"

Réponse :

{
  "token": "xK9mP2nQ7vR4sT8wU1yZ5aB3cD6eF0gH",
  "name": "my-client"
}

Modifier la date d'expiration par défaut

Par défaut, les tokens expirent après 720 heures (1 mois), mais vous pouvez le modifier en utilisant le paramètre expires_hours :

curl -k -X POST "https://localhost:12098/admin/tokens/create?name=my-client&expires_hours=3600" \
  -H "X-Admin-Key: your-admin-key-here"

Lister les tokens

Afficher tous les tokens actifs :

curl -k -X GET "https://localhost:12098/admin/tokens/list" \
  -H "X-Admin-Key: your-admin-key-here"

Réponse :

{
  "xK9mP2nQ7vR4sT8wU1yZ5aB3cD6eF0gH": {
    "name": "my-client",
    "expires_at": "2025-11-02T10:30:00"
  }
}

Révoquer les tokens

Révoquer un token spécifique :

curl -k -X DELETE "https://localhost:12098/admin/tokens/xK9mP2nQ7vR4sT8wU1yZ5aB3cD6eF0gH" \
  -H "X-Admin-Key: your-admin-key-here"

Détails des tokens : - Les tokens expirent après 30 jours (720 heures) par défaut - Les tokens expirés sont automatiquement supprimés lors de la validation - Les tokens sont stockés dans /app/data/tokens.json (persistant via volume Docker) - Chaque token est lié à un nom descriptif pour une gestion facile

Notes de sécurité

  • Changez ADMIN_KEY de la valeur par défaut
  • Gardez votre API_KEY sécurisée
  • Le dossier data/ contient les tokens d'authentification - sauvegardez-le !
  • Définissez les permissions de fichiers appropriées :
chmod 700 data/
chmod 600 data/tokens.json
  • N'utilisez jamais NODE_TLS_REJECT_UNAUTHORIZED=0 en environnements de production
  • Pour les déploiements de production avec Claude Web, utilisez toujours des certificats SSL de confiance

Outils disponibles

Outils de surveillance principaux

Outil Description Paramètres requis
list_customer_networks Lister tous les réseaux clients disponibles Aucun
search_agents Trouver des agents pour un client customer_id (par défaut à 0)
query_latency Interroger la latence avec filtres de temps/protocole customer_id, agent_id, protocol + (time_range OU chosen_time)
get_connectivity_health Analyse complète de la connectivité customer_id, agent_id (tous deux par défaut à 0,1)
analyze_radio_conditions Analyse de la qualité du signal radio customer_id, agent_id + (time_range OU chosen_time)
get_system_metrics Métriques de performance système Aucun
get_forecast Analyse prédictive de la latence customer_id, agent_id (tous deux par défaut à 0,1)
get_geolocation_data Performance corrélée à la localisation customer_id, agent_id, time_range
get_lifbe_data Métriques de débit Lifbe customer_id, agent_id (tous deux par défaut à 0,1)
get_twamp_data Mesures du protocole TWAMP customer_id, agent_id (tous deux par défaut à 0,1)

Outils d'analyse intelligente

Outil Description Paramètres requis
get_anomalies Détecter les anomalies réseau sur tous les protocoles customer_id, agent_id (par défaut à 0,1)
analyze_performance_trends Comparer les performances actuelles vs de référence customer_id, agent_id (par défaut à 0,1)
get_degradation_alerts Identifier les agents en dégradation customer_id (par défaut à 0)
detect_correlation_patterns Trouver les problèmes de performance corrélés customer_id (par défaut à 0)
generate_health_report Analyse complète de la santé du réseau customer_id (par défaut à 0)
rank_agents_by_performance Classer les agents par métriques de performance customer_id (par défaut à 0)

Prompts disponibles

Les prompts sont des workflows guidés (skills) qui indiquent au modèle comment combiner les outils pour résoudre des problèmes spécifiques. Les clients qui prennent en charge les prompts MCP peuvent les invoquer directement.

Prompt Description
radio-signal-troubleshooting Diagnostique les problèmes de qualité du signal cellulaire en interprétant les métriques RSSI, RSRP, RSRQ et SINR. À utiliser lors de l'investigation de problèmes de connectivité ou de mauvaise qualité de signal.
multi-site-correlation Analyse les performances sur plusieurs agents pour distinguer les problèmes spécifiques à un site d'une dégradation à l'échelle du réseau. À utiliser lors de la comparaison d'agents ou de l'investigation de problèmes corrélés.
customer-health-reports Génère des rapports professionnels sur la santé du réseau avec des résumés exécutifs et des recommandations actionnables. À utiliser lors de la création de rapports quotidiens, hebdomadaires ou mensuels pour les parties prenantes.
latency-protocol-comparison Compare côte à côte les latences TCP, UDP, HTTP, HTTPS, ICMP et TWAMP pour isoler si un problème de performance est spécifique à un protocole ou à l'échelle du réseau.
predictive-capacity-planning Combine les données de prévision, les tendances et les classements d'agents pour identifier les agents approchant leurs limites de performance avant qu'ils ne deviennent des incidents.
incident-investigation Playbook étape par étape pour les incidents actifs : détermine le rayon d'impact, précise le timing et identifie la couche de cause racine (FAI vs radio vs équipement local).
geolocation-latency-analysis Corrélation de la latence avec la localisation physique pour identifier les clusters géographiques, l'impact de la distance à la tour, et si des agents proches partagent une cause racine.
throughput-quality-assessment Détermine si la lenteur est causée par une saturation de bande passante ou des problèmes de qualité de connexion (perte de paquets, gigue) à l'aide des données Lifbe et iPerf.

Points de terminaison API

Le serveur MCP expose ces points de terminaison HTTP :

  • GET / - Informations sur le serveur
  • GET /health - Vérification de santé
  • POST /mcp/initialize - Initialisation MCP
  • POST /mcp/resources/list - Lister les ressources
  • POST /mcp/resources/read - Lire le contenu de la ressource
  • POST /mcp/tools/list - Lister les outils disponibles
  • POST /mcp/tools/call - Exécuter un outil

Troubleshooting

Problèmes de certificat SSL

Claude Web : - Erreur : "certificat auto-signé" ou échecs de connexion - Solution : Claude Web nécessite des certificats SSL de confiance. Les certificats auto-signés ne fonctionneront PAS. Vous devez configurer un sous-domaine avec Let's Encrypt (voir section Configuration SSL ci-dessus)

Claude Desktop : - Erreur : Erreurs "certificat auto-signé" - Solution : Ajoutez NODE_TLS_REJECT_UNAUTHORIZED: "0" à la section env dans votre configuration Claude Desktop (voir configuration Claude Desktop ci-dessus) - Note : Ceci est uniquement pour le développement/test. Pour la production, utilisez des certificats SSL de confiance

Problèmes de connexion

  • Vérifiez si la clé API est correcte
  • Vérifiez si l'API LatencyTech est accessible
  • Pour Docker : utilisez host.docker.internal au lieu de localhost, ou utilisez network_mode: "host" dans mcp-server.yml
  • Vérifiez les paramètres du pare-feu pour le port 12098
  • Pour Claude Web : Assurez-vous que le DNS du sous-domaine est correctement configuré et pointe vers votre serveur
  • Pour les configurations nginx : Vérifiez que nginx fonctionne et est correctement configuré (sudo nginx -t)

Journalisation

  • Définissez LOG_LEVEL=DEBUG pour une journalisation détaillée des requêtes/réponses
  • Vérifiez les journaux du conteneur : docker logs <container_id>
  • Vérifiez les journaux nginx : sudo tail -f /var/log/nginx/error.log

Exemples de requêtes et tests

  • "Donne-moi un résumé de la latence pour l'agent 1."
  • "Montre-moi toutes les anomalies réseau détectées pour l'agent 1, au cours de la dernière heure. Concentre-toi sur le protocole TCP s'il y a des problèmes."
  • "Quels agents ont des avertissements de santé de connectivité ?"
  • "Génère une prévision pour la latence attendue de l'agent 2"
  • "Peux-tu analyser les tendances de performance pour l'agent 1 dans le client 0 au cours des 7 derniers jours ? Je veux voir s'il y a eu une dégradation par rapport à la référence."
  • "Génère un rapport complet quotidien sur la santé du réseau pour le client 0. Inclus des recommandations actionnables pour tous les problèmes que tu trouves."