Dokumentation des Analyzer-MCP

HTTP-basierter Model-Context-Protocol-Server zur Überwachung der Netzlatenz und für intelligente Analysen. Der MCP-Server verbindet sich mit der bereits vorhandenen LatenceTech-API, um mit der Datenbank des Analyzer selbst zu kommunizieren.

Funktionen

Kernüberwachung

Latenz über alle Latenzprotokolle abfragen (TCP, UDP, HTTP, HTTPS, ICMP, TWAMP)
Analyse des Konnektivitätszustands mit umfassenden KPIs
Überwachung der Funksignalqualität (RSSI, RSRP, RSRQ, SINR)
Vorausschauende Latenzprognose mit Konfidenzintervallen
Mit der Geolokalisierung korrelierte Leistungsdaten
Überwachung der Systemmetriken (CPU, RAM, Speicher, Last)
Durchsatz- und Qualitätsmessungen mit Lifbe
Zeitreihen des Paketverlusts (Upload, Download, gesamt)
Momentaufnahmen des iPerf-Durchsatzes TCP/UDP

Intelligente Analyse

Anomalieerkennung: Erkennt Netzwerkanomalien über alle Protokolle hinweg
Leistungstrends: Analysiert die Leistungstrends der Agents im Vergleich zu historischen Referenzwerten
Verschlechterungswarnungen: Identifiziert Agents mit nachlassender Leistung
Korrelationsanalyse: Erkennt Muster zwischen Agents, die auf netzweite Probleme hinweisen
Protokollspitzen-Ereignisse: Erkennt synchronisierte Latenzspitzen über mehrere Protokolle auf einem einzelnen Agent
Zustandsberichte: Erstellt umfassende Berichte zum Netzzustand mit Empfehlungen
Agent-Ranglisten: Ordnet Agents nach Leistungsmetriken und Trends

Konfiguration

Voraussetzungen

Der MCP-Server erfordert, dass Port 12098 auf der Maschine geöffnet ist.

Umgebungsvariablen

Legen Sie die Werte direkt in docker-compose.yml fest:

environment:
  # ERFORDERLICH: Durch Ihren API-Schlüssel ersetzen
  - API_KEY=your-api-key-here

  # ERFORDERLICH: Durch einen sicheren Schlüssel ersetzen, der zum Erstellen von Tokens verwendet wird
  - ADMIN_KEY=change-this-secure-admin-key

  # SERVER_HOST: Leer lassen für die automatische Erkennung der externen IP, 
  # ODER die IP Ihrer VM festlegen (z. B.: 192.168.1.100)
  # ODER Ihren DNS-Namen festlegen (z. B.: demo.example.com)
  - SERVER_HOST=

  # ENABLE_HTTPS: NUR bei Verwendung einer DNS-Adresse auf 'false' setzen
  # Bei Verwendung einer IP-Adresse auf true belassen (Standard)
  - ENABLE_HTTPS=true

  # ENABLE_OAUTH: Auf 'false' setzen, um die OAuth-Endpunkte zu deaktivieren (Claude Web funktioniert dann nicht)
  # 'true' beibehalten für die Unterstützung von Claude Web (Standard: true)
  # 'false' setzen für ausschließliche Unterstützung von Bearer-Tokens
  # Wenn aktiviert, kann sich jeder mit der MCP-Adresse ohne Prüfung verbinden
  - ENABLE_OAUTH=false

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

Wichtige Konfigurationshinweise:

API_KEY: Erforderlich für den Zugriff auf die Backend-API
ADMIN_KEY: Erforderlich zum Erstellen/Verwalten der Zugriffstokens
HTTPS-Konfiguration:
Für Claude Desktop mit IP: ENABLE_HTTPS=true für selbstsignierte Zertifikate setzen
Für Claude Web: Sie müssen eine Domain mit gültigem SSL verwenden (siehe SSL-Konfiguration unten)
ENABLE_OAUTH:
ENABLE_OAUTH=true → Alle 5 OAuth-Endpunkte registriert, Claude Web kann sich verbinden
ENABLE_OAUTH=false → OAuth-Endpunkte nicht registriert, nur Bearer-Tokens funktionieren
Die Endpunkte zur Tokenverwaltung (/admin/tokens/*) funktionieren immer, unabhängig von der OAuth-Einstellung

Die Protokolle zeigen:

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

SSL-Konfiguration für Claude Web

Claude Web erfordert ein vertrauenswürdiges SSL-Zertifikat und kann keine selbstsignierten Zertifikate verwenden.

Subdomain mit Nginx + Let's Encrypt

DNS-A-Eintrag für eine Subdomain hinzufügen (z. B.: mcp.yourdomain.com → IP Ihres Servers)
Nginx-Konfiguration erstellen (/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;

        # Unterstützung für lang andauernde Verbindungen
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }

    listen 80;
}

Site aktivieren und SSL-Zertifikat beziehen:

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

mcp-server.yml aktualisieren:

- ENABLE_HTTPS=false

Container neu starten:

docker compose down
docker compose up -d

Integration mit MCP-Clients

Claude Web (claude.ai)

Anforderungen: - Gültiges SSL-Zertifikat (selbstsignierte Zertifikate funktionieren NICHT) - Es muss eine Subdomain mit Let's Encrypt oder einer ähnlichen vertrauenswürdigen CA verwendet werden - OAuth muss aktiviert sein (ENABLE_OAUTH=true)

Claude Web verwendet automatisch die Authentifizierung nach OAuth 2.1:

Gehen Sie zu Claude-Einstellungen → Konnektoren
Klicken Sie auf "Benutzerdefinierten Konnektor hinzufügen"
Name: Latency Monitoring
URL des Remote-MCP-Servers: https://mcp.yourdomain.com (muss vertrauenswürdiges SSL verwenden)
Lassen Sie die OAuth-Felder leer (der Server übernimmt die dynamische Registrierung)
Klicken Sie auf "Hinzufügen" — Claude startet automatisch den OAuth-Ablauf
Genehmigen Sie die Autorisierung (vom Server automatisch genehmigt, keine echte Prüfung)
Verbindung mit erzeugtem Zugriffstoken hergestellt

Funktionsweise: - Claude ermittelt die OAuth-Endpunkte über .well-known/oauth-authorization-server - Der Server genehmigt die Autorisierung automatisch und erzeugt ein Zugriffstoken - Das Token wird automatisch von Claude verwaltet (keine manuelle Tokenverwaltung nötig) - Das Token läuft nach 30 Tagen ab und kann erneuert werden

Claude Desktop

Claude Desktop kann mit einer Umgehungslösung selbstsignierte Zertifikate verwenden.

Claude Desktop benötigt den Proxy mcp-remote mit Bearer-Token:

1) Zugriffstoken erstellen:

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

Antwort:

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

2) Claude Desktop konfigurieren:

Für selbstsignierte Zertifikate (IP-Adresse):

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

Für vertrauenswürdiges SSL (Subdomain mit 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"
      }
    }
  }
}

Sicherheitshinweis: NODE_TLS_REJECT_UNAUTHORIZED=0 deaktiviert die Prüfung des SSL-Zertifikats und sollte nur in der Entwicklung oder in vertrauenswürdigen Netzwerkumgebungen verwendet werden. Verwenden Sie für die Produktion eine Subdomain mit Let's Encrypt.

3) Starten Sie Claude Desktop neu

Cursor

Cursor unterstützt Remote-MCP-Server über Bearer-Token.

1) Zugriffstoken erstellen:

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

2) Cursor konfigurieren in .cursor/mcp.json (Projektebene) oder ~/.cursor/mcp.json (global):

Für vertrauenswürdiges SSL (Subdomain mit Let's Encrypt):

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

Für selbstsignierte Zertifikate (IP-Adresse):

Verwenden Sie den 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) Laden Sie Cursor neu und prüfen Sie, ob der Server unter Cursor-Einstellungen > MCP erscheint

Google Antigravity

Google Antigravity unterstützt Remote-MCP-Server über Bearer-Token.

1) Zugriffstoken erstellen:

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

2) Antigravity konfigurieren in ~/.gemini/config/mcp_config.json (global) oder .agents/mcp_config.json (Workspace). Sie können diese Datei auch über Agent panel > ... > MCP Servers > Manage MCP Servers > View raw config öffnen.

Wichtig: Antigravity verwendet für HTTP-basierte Remote-MCP-Server serverUrl (und nicht url).

Für vertrauenswürdiges SSL (Subdomain mit Let's Encrypt):

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

Für selbstsignierte Zertifikate (IP-Adresse):

Verwenden Sie den 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) Starten Sie Antigravity neu oder aktualisieren Sie die MCP-Server unter Settings > Customizations > Installed MCP Servers

Andere MCP-Clients

Für jeden MCP-Client, der Bearer-Tokens unterstützt:

Token erstellen (siehe Abschnitt zur Tokenverwaltung unten)
Client so konfigurieren, dass er den Header Authorization: Bearer <token> sendet
Mit der URL Ihres Servers verbinden

Tokenverwaltung

Tokens erstellen

Neue Zugriffstokens für Clients erstellen:

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

Antwort:

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

Standard-Ablaufdatum ändern

Standardmäßig laufen Tokens nach 720 Stunden (1 Monat) ab; Sie können dies mit dem Parameter expires_hours ändern:

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

Tokens auflisten

Alle aktiven Tokens anzeigen:

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

Antwort:

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

Tokens widerrufen

Ein bestimmtes Token widerrufen:

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

Details zu den Tokens: - Tokens laufen standardmäßig nach 30 Tagen (720 Stunden) ab - Abgelaufene Tokens werden bei der Validierung automatisch entfernt - Tokens werden in /app/data/tokens.json gespeichert (persistent über ein Docker-Volume) - Jedes Token ist zur einfachen Verwaltung mit einem beschreibenden Namen verknüpft

Sicherheitshinweise

Ändern Sie ADMIN_KEY gegenüber dem Standardwert
Halten Sie Ihren API_KEY geheim
Der Ordner data/ enthält die Authentifizierungstokens — sichern Sie ihn!
Legen Sie geeignete Dateiberechtigungen fest:

chmod 700 data/
chmod 600 data/tokens.json

Verwenden Sie NODE_TLS_REJECT_UNAUTHORIZED=0 niemals in Produktionsumgebungen
Verwenden Sie für Produktivbereitstellungen mit Claude Web immer vertrauenswürdige SSL-Zertifikate

Verfügbare Werkzeuge

Werkzeuge der Kernüberwachung

Werkzeug	Beschreibung	Erforderliche Parameter
`list_customer_networks`	Alle verfügbaren Kundennetze auflisten	Keine
`search_agents`	Agents eines Kunden finden	`customer_id` (Standard 0)
`query_latency`	Latenz mit Zeit-/Protokollfiltern abfragen	`customer_id`, `agent_id`, `protocol` + (`time_range` ODER `chosen_time`)
`get_connectivity_health`	Umfassende Konnektivitätsanalyse	`customer_id`, `agent_id` (beide Standard 0,1)
`analyze_radio_conditions`	Analyse der Funksignalqualität	`customer_id`, `agent_id` + (`time_range` ODER `chosen_time`)
`get_system_metrics`	Leistungsmetriken des Systems	Keine
`get_forecast`	Vorausschauende Latenzanalyse	`customer_id`, `agent_id` (beide Standard 0,1)
`get_geolocation_data`	Mit dem Standort korrelierte Leistung	`customer_id`, `agent_id`, `time_range`
`get_lifbe_data`	Lifbe-Durchsatzmetriken	`customer_id`, `agent_id` (beide Standard 0,1)
`get_twamp_data`	Messungen des TWAMP-Protokolls	`customer_id`, `agent_id` (beide Standard 0,1)
`query_packet_loss`	Zeitreihen des Paketverlusts	`customer_id`, `agent_id` + (`time_range` ODER `chosen_time`)
`get_iperf_throughput`	Letzte Momentaufnahme des iPerf-Durchsatzes	`customer_id`, `agent_id` (beide Standard 0,1)

Werkzeuge der intelligenten Analyse

Werkzeug	Beschreibung	Erforderliche Parameter
`get_anomalies`	Netzwerkanomalien über alle Protokolle erkennen	`customer_id`, `agent_id` (Standard 0,1)
`analyze_performance_trends`	Aktuelle Leistung mit dem Referenzwert vergleichen	`customer_id`, `agent_id` (Standard 0,1)
`get_degradation_alerts`	Agents mit nachlassender Leistung identifizieren	`customer_id` (Standard 0)
`detect_correlation_patterns`	Korrelierte Leistungsprobleme finden	`customer_id` (Standard 0)
`detect_protocol_spike_events`	Zeitfenster mit Latenzspitzen über mehrere Protokolle auf einem Agent finden	`customer_id`, `agent_id` + optional `time_range`, `protocols`, `min_protocols`, `spike_ratio`
`generate_health_report`	Umfassende Analyse des Netzzustands	`customer_id` (Standard 0)
`rank_agents_by_performance`	Agents nach Leistungsmetriken ordnen	`customer_id` (Standard 0)

Verfügbare Prompts

Prompts sind geführte Arbeitsabläufe (Skills), die dem Modell zeigen, wie es die Werkzeuge kombiniert, um bestimmte Probleme zu lösen. Clients, die MCP-Prompts unterstützen, können sie direkt aufrufen.

Prompt	Beschreibung
`radio-signal-troubleshooting`	Diagnostiziert Probleme mit der Mobilfunksignalqualität durch Auswertung der Metriken RSSI, RSRP, RSRQ und SINR. Bei der Untersuchung von Konnektivitätsproblemen oder schlechter Signalqualität verwenden.
`multi-site-correlation`	Analysiert die Leistung mehrerer Agents, um standortspezifische Probleme von einer netzweiten Verschlechterung zu unterscheiden. Beim Vergleich von Agents oder der Untersuchung korrelierter Probleme verwenden.
`customer-health-reports`	Erstellt professionelle Berichte zum Netzzustand mit Management-Zusammenfassungen und umsetzbaren Empfehlungen. Beim Erstellen täglicher, wöchentlicher oder monatlicher Berichte für Stakeholder verwenden.
`latency-protocol-comparison`	Vergleicht die Latenzen von TCP, UDP, HTTP, HTTPS, ICMP und TWAMP nebeneinander, um festzustellen, ob ein Leistungsproblem protokollspezifisch oder netzweit ist.
`predictive-capacity-planning`	Kombiniert Prognosedaten, Trends und Agent-Ranglisten, um Agents zu identifizieren, die sich ihren Leistungsgrenzen nähern, bevor daraus Störungen werden.
`incident-investigation`	Schritt-für-Schritt-Playbook für aktive Störungen: bestimmt den Auswirkungsradius, präzisiert den zeitlichen Ablauf und identifiziert die Ebene der Grundursache (ISP vs. Funk vs. lokale Ausrüstung).
`geolocation-latency-analysis`	Korreliert die Latenz mit dem physischen Standort, um geografische Cluster, den Einfluss der Entfernung zum Mast und gemeinsame Grundursachen benachbarter Agents zu erkennen.
`throughput-quality-assessment`	Ermittelt anhand der Lifbe- und iPerf-Daten, ob Langsamkeit durch Bandbreitensättigung oder durch Probleme der Verbindungsqualität (Paketverlust, Jitter) verursacht wird.

API-Endpunkte

Der MCP-Server stellt diese HTTP-Endpunkte bereit:

GET / - Serverinformationen
GET /health - Zustandsprüfung
POST /mcp/initialize - MCP-Initialisierung
POST /mcp/resources/list - Ressourcen auflisten
POST /mcp/resources/read - Inhalt einer Ressource lesen
POST /mcp/tools/list - Verfügbare Werkzeuge auflisten
POST /mcp/tools/call - Ein Werkzeug ausführen

Fehlerbehebung

Probleme mit SSL-Zertifikaten

Claude Web: - Fehler: "selbstsigniertes Zertifikat" oder Verbindungsfehler - Lösung: Claude Web erfordert vertrauenswürdige SSL-Zertifikate. Selbstsignierte Zertifikate funktionieren NICHT. Sie müssen eine Subdomain mit Let's Encrypt einrichten (siehe Abschnitt SSL-Konfiguration oben)

Claude Desktop: - Fehler: Fehler "selbstsigniertes Zertifikat" - Lösung: Fügen Sie NODE_TLS_REJECT_UNAUTHORIZED: "0" zum Abschnitt env Ihrer Claude-Desktop-Konfiguration hinzu (siehe Konfiguration von Claude Desktop oben) - Hinweis: Dies ist nur für Entwicklung/Tests gedacht. Verwenden Sie für die Produktion vertrauenswürdige SSL-Zertifikate

Verbindungsprobleme

Prüfen Sie, ob der API-Schlüssel korrekt ist
Prüfen Sie, ob die LatenceTech-API erreichbar ist
Für Docker: Verwenden Sie host.docker.internal statt localhost oder network_mode: "host" in mcp-server.yml
Prüfen Sie die Firewall-Einstellungen für Port 12098
Für Claude Web: Stellen Sie sicher, dass das DNS der Subdomain korrekt konfiguriert ist und auf Ihren Server zeigt
Für Nginx-Konfigurationen: Prüfen Sie, ob Nginx läuft und korrekt konfiguriert ist (sudo nginx -t)

Protokollierung

Setzen Sie LOG_LEVEL=DEBUG für eine detaillierte Protokollierung der Anfragen/Antworten
Prüfen Sie die Container-Protokolle: docker logs <container_id>
Prüfen Sie die Nginx-Protokolle: sudo tail -f /var/log/nginx/error.log

Beispielanfragen und Tests

"Gib mir eine Zusammenfassung der Latenz für Agent 1."
"Zeige mir alle für Agent 1 in der letzten Stunde erkannten Netzwerkanomalien. Konzentriere dich auf das TCP-Protokoll, falls es Probleme gibt."
"Welche Agents haben Warnungen zum Konnektivitätszustand?"
"Erstelle eine Prognose der erwarteten Latenz von Agent 2"
"Kannst du die Leistungstrends für Agent 1 bei Kunde 0 in den letzten 7 Tagen analysieren? Ich möchte sehen, ob es im Vergleich zum Referenzwert eine Verschlechterung gab."
"Erstelle einen umfassenden täglichen Bericht zum Netzzustand für Kunde 0. Füge umsetzbare Empfehlungen für alle gefundenen Probleme hinzu."