Zum Hauptinhalt springen

19. MCP-Server (AI-Assistenten-Anbindung)

Der MCP(Model Context Protocol)-Server ist die Schnittstelle, die es AI-Assistenten wie Claude ermöglicht, Vor-Ort-Daten der Platform in natürlicher Sprache abzufragen und zu diagnostizieren. Der Assistent kann Tag-Werte lesen, Alarm-Kontexte sammeln, Asset-Hierarchien durchsuchen und bis hin zur Bestätigung (Ack) von Alarmen durchführen.

Dies ist kein Ersatz für die REST API — dieselbe V5-Service-Schicht wird innerhalb derselben JVM aufgerufen, und Authentifizierung, Audit sowie Rate-Limiting nutzen exakt die Mechanismen aus /api/v5/*.

ElementWert
EndpunktPOST https://<server>/api/v5/mcp
ÜbertragungStreamable HTTP, stateless — sicher bei Neustarts, da keine Sitzungen erstellt werden
SpezifikationMCP 2025-11-25 Stable
Bereitstellung32 Tools · 7 Ressourcen · 3 Prompts · Autovervollständigung · Fortschrittsanzeige · Elicitation

Anbindung​

Schritt 1 — api_key ausstellen​

MCP verfügt über kein eigenes Authentifizierungssystem und verwendet direkt den V5 API-Schlüssel. Dieser wird gegen den vom Administrator ausgestellten api_token ausgetauscht.

curl -s -X POST "https://<server>/api/v5/auth" \
  -H "Content-Type: application/json; charset=UTF-8" \
  -d '{"token":"<api_token>"}'
# 200: { "data": { "api_key": "..." }, "meta": { "status": "OK" }, "errors": null }
Ein Erfolg wird nicht durch «HTTP 200» bestimmt

Ein Erfolg liegt nur vor, wenn meta.status den Wert OK hat und data.api_key nicht leer ist. Zudem bedeutet 503 nicht, dass die Anmeldedaten falsch sind — es bedeutet, dass der Token-Speicher nicht erreicht wurde und somit keine Entscheidung getroffen werden konnte. Eine Tabelle zur Fehlerbehebung je nach Antwort findet sich unter Erste Schritte §1.8.

Die Token-Rolle muss ADMIN oder API sein

MCP sendet alle Anfragen, einschließlich Lesezugriffe, als POST. Der V5-Filter erlaubt POST, PUT, DELETE und PATCH nur für Rollen mit ADMIN/API, weshalb bei einer USER-Rolle selbst Lese-Tools mit 403 abgelehnt werden. Auch wenn die Nutzung als schreibgeschützt geplant ist, stellen Sie den Token als ADMIN/API aus.

Schritt 2 — Im Client registrieren​

# Claude Code
claude mcp add --transport http plantpulse "https://<server>/api/v5/mcp" \
  --header "X-API-Key: <api_key>"
// Claude Desktop — .mcp.json
{
  "mcpServers": {
    "plantpulse": {
      "type": "http",
      "url": "https://<server>/api/v5/mcp",
      "headers": { "X-API-Key": "<api_key>" }
    }
  }
}

Anstelle von X-API-Key kann auch Authorization: Bearer <api_key> verwendet werden. Bei einem Authentifizierungsfehler erfolgt die Antwort mit 401 und dem Header WWW-Authenticate: Bearer.

Browser-basierte Clients erfordern eine Origin-Registrierung

Um DNS-Rebinding zu verhindern, wird der Origin-Header gegen eine Whitelist geprüft. Native Clients wie Claude Desktop oder Claude Code, die keinen Origin senden, sind immer zulässig. Browser-basierte Clients müssen jedoch in AI_MCP_ALLOWED_ORIGINS registriert werden. Da der Standardwert leer ist, werden alle nicht registrierten Clients mit 403 abgelehnt.

32 Tools​

Es gibt 31 Lese-Tools und 1 Schreib-Tool(acknowledge_alarm). Tools zum Löschen, Steuern oder Ändern von Einstellungen sind aus Designgründen nicht vorhanden.

ToolFunktionPflichtargumente
search_entitiesSuche nach Domänenobjekten via Name, ID oder Beschreibung (Name → ID). Wird zuerst aufgerufen, wenn die ID fehltquery
list_latest_tag_valuesAktueller Tag-Werttag_ids
get_tag_historyZeitreihen-Historie eines Tagstag_id, from
get_asset_snapshotSnapshot aller Tags einer Anlageasset_id
list_alarmsAlarm-Liste—
acknowledge_alarmAlarm bestätigen — Grund(comment) ist Pflicht und wird im Audit protokolliertalarm_seq, comment
get_alarm_contextAlarmursache-Diagnosepaketalarm_seq
list_alarm_suppressionsVerborgene Alarme (verborgen, unterdrückt, ausgenommen)—
get_alarm_performanceAlarm-Systemleistung — gleiche Werte wie GET /alarm/performancescope_type, scope_id
get_edge_statusStatus eines einzelnen Edge-Gatewaysedge_id
list_edge_statusListe der Edge-Gateways—
get_edge_connection_historyEdge-Health-Historie (Tagesintervalle)edge_id, date
list_opc_connectionsListe der OPC-Erfassungsverbindungen—
get_asset_treeBaum der Anlagenhierarchieasset_id
get_asset_by_externalSuche nach Hierarchieknoten via MES/EAM-Nummerexternal_system, external_id
get_site_overviewSite-Ontologie Überblicksite_id
trace_asset_relationsBeziehungsverfolgung — Upstream/Downstream-Auswirkungenentity_id
query_knowledge_graphOntologie SPARQL-Abfragesparql
list_asset_documentsAnlagenzugehörige Dokumenteasset_id
get_asset_timelineTimeline von Anlagenereignissenasset_id
list_work_ordersListe der Workorder—
get_work_order_kpiWorkorder Details + KPIorder_id
get_work_order_by_externalWorkorder-Suche via MES/ERP-Nummerexternal_system, external_id
get_asset_kpiZusammenfassung der Anlagen-KPIs über Zeitraum (Status, Alarm, OEE)asset_id, from
get_asset_scheduleAnlagen-/Site-Kalender (Schicht, Stillstand, Feiertag)asset_id
list_maintenance_ordersInstandhaltungsauftrag (Ruf, Reparatur, Teil, ISO-Code)scope_id
get_maintenance_summaryInstandhaltungszusammenfassung (Baugruppe, Fehlermodus, Warte-/Reparaturzeit, Wiederholung)scope_id
get_maintenance_order_by_externalInstandhaltungsauftrag-Suche via CMMS-Nummerexternal_system, external_id
get_connection_healthHealth-Rollup der Anlagenhierarchie—
get_current_timeAktuelle Serverzeit—
get_eql_referenceEQL-Referenz für Konsoleneingabe (Syntax, Event-Typen, Funktionen, Beispiele)surface
validate_eqlEQL-Kompilierungsprüfung (ohne Deployment)surface, eql

Die Schlüssel für Instandhaltungszeilen entsprechen den V5 Instandhaltungsaufträgen — maintenance_order_id(String), maintenance_kind_code, status_code, failure_record_seq, maintenance_plan_id(String), failure_mode_code, maintainable_item_code. Da maintenance_order_id entweder MAINTENANCE_ORDER_000001 oder eine numerische Zeichenfolge alter Zeilen("12") ist, behandeln Sie diese nicht als Zahl.

Die Schweregradswerte sind ERROR, WARN, INFO

Die in den Bildschirmbezeichnungen von get_connection_health sichtbaren Werte critical/major/minor sind Anzeige-Buckets. Für Filter in list_alarms(severity=) müssen die Kanonischen Werte verwendet werden.

7 Ressourcen​

Dies sind schreibgeschützte Kanäle, über die der Assistent «prüfen kann, was vorhanden ist», bevor er Tools aufruft.

pp://sites, pp://ontology/{site_id}, pp://assets/{site_id}/tree, pp://uns/{site_id}, pp://catalog/{store}/tables, pp://catalog/{store}/{table}/schema, pp://domain-graph

{store} erlaubt nur metastore, eventstore und analytics.

3 Prompts​

NameVerfahren
diagnose-assetAsset-Störungsdiagnose — Alarm → Kontext → Tag-Historie → Verbindung → Downstream-Auswirkung → Ursachenkandidaten
shift-briefingSchicht-Briefing — Health → Alarm → Order/KPI → Übergabezusammenfassung
alarm-triageAlarm-Klassifizierung — Liste → Priorität → Empfehlung → (bei Genehmigung) Bestätigung

Konfiguration — AI_MCP_* von pp.mm_config​

Dies ist keine Konfigurationsdatei

Die maßgebliche Quelle ist die PostgreSQL-Tabelle pp.mm_config. plantpulse-ai.properties wurde entfernt und der Lesezugriff darauf aufgehoben — siehe Property Reference.

SchlüsselStandardwertBedeutung
AI_MCP_ENABLEDtrueWenn false, gibt /api/v5/mcp einen 404 aus
AI_MCP_ALLOWED_ORIGINS(leer)Origin-Whitelist für Browser-Clients (kommagetrennt)
AI_MCP_TREE_MAX_NODES2000Obergrenze der Antwortknoten im Baum
AI_MCP_TREE_DEFAULT_DEPTH2Standardtiefe für get_asset_tree
AI_MCP_TREE_MAX_NODE_TAGS100Anzahl der Tags pro Knoten
AI_MCP_TREE_ONTOLOGY_MAX_CHARS200000Zeichenobergrenze für Ontologie-Antworten
AI_MCP_TREE_ONTOLOGY_DEFAULT_DEPTH3Standardtiefe für trace_asset_relations
AI_MCP_TREE_ONTOLOGY_MAX_TAGS500Budget für Tag-Zeilen in der gesamten Ontologie-Antwort

Es gibt nur einen Weg, die Werte zu ändern — über den Konfigurationsbildschirm(/config/index) oder durch Bearbeiten von pp.mm_config. Da MCP den Cache bei jeder Anfrage liest, ist kein Neustart erforderlich.

🔴 Die Umgebungsvariable PP_AI_MCP_* bewirkt nichts

Dies gilt unabhängig davon, ob es der erste Bootvorgang ist oder nicht. Der Seeder, der Umgebungsvariablen in Tabellen übertrug, sowie die ${PP_AI_*}-Substitutionsschicht wurden am 18.09.2026 entfernt. Eingaben werden nun stillschweigend ignoriert, ohne einen Fehler zu melden. Dies führt oft zu dem schwer diagnostizierbaren Problem, dass Einstellungen trotz Konfiguration nicht greifen. Fehlende Schlüssel werden mit den Standardwerten der obigen Tabelle belegt.

Audit und Sicherheit​

  • Authentifizierung, Rate-Limiting und Audit erfolgen über die bestehende /api/v5/*-Filterkette.
  • acknowledge_alarm hinterlässt ein eigenes Audit (Akteur MCP). Wenn eine Begründung fehlt, wird der Assistent aufgefordert, diese nachzuliefern; bei Clients ohne diese Funktion wird «Begründung erforderlich» ausgegeben.
  • Ausschluss von allgemeinen Änderungs-Audit-Hooks: Da alle Aufrufe, einschließlich Lesezugriffe, als POST erfolgen, würden Hooks jeden Aufruf fälschlicherweise als Änderung protokollieren.
  • Kein Token-Weiterleitungspfad: Da die Service-Schicht derselben JVM direkt aufgerufen wird, gibt es keinen Weg, empfangene Anmeldedaten an andere Systeme weiterzuleiten.

Erste Schritte · Gesamte Liste der Endpunkte · Asset Service