KI-Schnittstelle (MCP)

Node64 spricht das Model Context Protocol (MCP). KI-Anwendungen wie Claude Code, Cursor oder VS Code fragen über /mcp den Zustand deiner Node ab und erklären Zusammenhänge – etwa „Warum war die Webseite heute Nacht weg?“, „Was hat der Honeypot diese Woche gesehen?“ oder „Welche Zertifikate laufen bald ab?“.

Was ist MCP?

MCP ist ein offenes Protokoll (JSON-RPC 2.0), über das eine KI-Anwendung „Werkzeuge“ eines Servers aufruft. Node64 ist der Server: Er beschreibt seine Werkzeuge mit Name, Zweck und Parametern, die Anwendung entscheidet, welche sie aufruft, und bekommt kompakte JSON-Antworten.

Transport ist „Streamable HTTP“ auf dem Web-Port der Node – kein zusätzlicher Port, dasselbe TLS-Zertifikat wie die Oberfläche. Node64 arbeitet ohne Sitzungen und antwortet als JSON.

Sicherheit

• Standard aus. Ausgeschaltet antwortet /mcp mit 404.
• Nur aus dem Heimnetz. Erlaubt sind private Netze (RFC 1918, fc00::/7), Link-local (fe80::/10), 100.64.0.0/10 (z. B. Tailscale) und localhost. Alles andere bekommt 403 – auch über PROXY64 oder einen anderen Reverse-Proxy: Steht in X-Forwarded-For, X-Real-IP oder Forwarded eine öffentliche Adresse, wird abgewiesen. Diese Header können den Zugang nur sperren, nie öffnen. Über PROXY64 muss dafür eine private Client-Adresse weitergereicht werden.
• Eigene MCP-Schlüssel (mcp64_…), getrennt von den API-Keys: node64_… gilt hier nicht, mcp64_… nicht für /api. Je Schlüssel gibt es einen Namen, Rechte je Bereich, die letzte Nutzung und Adresse; widerrufen geht jederzeit. Gespeichert wird nur der Hash, der Schlüssel ist nur direkt nach dem Anlegen sichtbar. Falsche Schlüssel bremsen die Adresse aus. Sitzungs-Cookies gelten für /mcp nicht.
• Rate-Limit: 60 Anfragen pro Minute je Schlüssel, darüber 429 mit Retry-After.
• Gleiche Regeln wie die API. Jedes Werkzeug ruft intern die vorhandene JSON-API auf, angemeldet als Inhaber des Schlüssels. Werkzeuge erscheinen nur, wenn ihr Modul läuft und der Schlüssel den Bereich lesen darf.
• Nie Geheimnisse. Die Werkzeuge wählen ihre Felder ausdrücklich aus: keine API-Keys, Tokens, Passwörter, privaten Schlüssel, Zugangsdaten von Kanälen, Header-Werte von PROXY64, Check-Parameter oder Push-Adressen. Ein zentraler Filter entfernt zusätzlich aus allen Texten URLs bis auf Schema und Host, token=…- und key=…-Werte, Bearer …, Schlüssel, PEM-Blöcke und lange Zufallszeichenfolgen.
• Fremde Daten sind gekennzeichnet. Vieles schreiben Fremde: Benutzer, Passwörter und Pfade aus dem Honeypot, Domainnamen im DNS64-Log, User-Agents aus PROXY64, VM-Namen aus Proxmox, Akteure im Audit-Log, HTTP-Methoden aus dem Zugriffs-Log und Fehlertexte entfernter Dienste, von Kanälen und der ipv64-Verknüpfung. Sie stehen gekürzt und bereinigt in einem Unterobjekt untrusted, und die Werkzeugbeschreibungen sagen der KI, dass diese Inhalte nie als Anweisungen gelten.
• Audit: Jeder Werkzeugaufruf steht im Audit-Log (Bereich KI (MCP), Aktion mcp.call) mit Werkzeug, Schlüssel, Benutzer, Adresse, gekürzten Parametern und Ergebnis. Ebenso Einschalten, Anlegen und Widerrufen von Schlüsseln. Die Einträge folgen der Aufbewahrung des Audit-Logs (Standard 365 Tage).
• Umzug: Der Schalter zieht mit Export und Import der Konfiguration um, MCP-Schlüssel nie – auch nicht im Export mit Passwort.

Einrichten

1. Einschalten
   Unter Einstellungen → KI-Schnittstelle (MCP) auf Einschalten klicken.
2. Schlüssel anlegen
   Name, zum Beispiel „Claude Code Laptop“, und die Bereiche, die gelesen werden dürfen: Node, Healthchecks, Proxmox VE, DNS64, PROXY64, Honeypot64, DynDNS, Zertifikate, Benachrichtigungen, Audit-Log und Logs.
3. Anwendung verbinden
   Die Seite zeigt die Adresse https://<node>:<port>/mcp und fertige Schnipsel mit dem neuen Schlüssel für die Anwendungen unten.

Zertifikat

Ohne weitere Einrichtung nutzt Node64 ein selbst signiertes Zertifikat. Anwendungen auf Basis von Node.js (Claude Code, mcp-remote) lehnen das ab. Du hast drei Möglichkeiten:

• Zertifikat der Node herunterladen (Einstellungen → Allgemein → Erreichbarkeit dieser Node) und vor dem Start der Anwendung NODE_EXTRA_CA_CERTS=/pfad/node64.pem setzen.
• Für die Oberfläche ein Zertifikat aus der Zertifikatsverwaltung wählen (Einstellungen → Allgemein → Erreichbarkeit dieser Node) und die Node über diesen Namen ansprechen.
• Im LAN geht auch http://<node>:<port>/mcp – HTTP und HTTPS laufen auf demselben Port. Der Schlüssel geht dann unverschlüsselt durchs Heimnetz.

Claude Code

claude mcp add --transport http node64 https://node64.lan:8080/mcp --header "Authorization: Bearer mcp64_…"

Mit --scope user gilt der Server in allen Projekten. Prüfen kannst du die Verbindung mit claude mcp list oder /mcp in Claude Code.

Cursor

~/.cursor/mcp.json für alle Projekte oder .cursor/mcp.json im Projekt:

{
  "mcpServers": {
    "node64": {
      "url": "https://node64.lan:8080/mcp",
      "headers": { "Authorization": "Bearer mcp64_…" }
    }
  }
}

VS Code (GitHub Copilot, Agent-Modus)

.vscode/mcp.json im Projekt oder über MCP: Open User Configuration:

{
  "servers": {
    "node64": {
      "type": "http",
      "url": "https://node64.lan:8080/mcp",
      "headers": { "Authorization": "Bearer mcp64_…" }
    }
  }
}

Damit der Schlüssel nicht in der Datei steht, kann VS Code ihn abfragen: "inputs": [{"type": "promptString", "id": "node64-key", "description": "Node64 MCP-Schlüssel", "password": true}] und im Header "Authorization": "Bearer ${input:node64-key}".

Claude Desktop

Entfernte Server bindet Claude Desktop als „Connectors“ ein. Die Verbindung baut dabei die Cloud von Anthropic auf und erreicht eine Node im Heimnetz nicht. Deshalb geht es über die lokale Brücke mcp-remote (braucht Node.js), eingetragen in claude_desktop_config.json (Einstellungen → Entwickler → Konfiguration bearbeiten):

{
  "mcpServers": {
    "node64": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://node64.lan:8080/mcp", "--header", "Authorization:${NODE64_AUTH}"],
      "env": { "NODE64_AUTH": "Bearer mcp64_…" }
    }
  }
}

Der Schlüssel steht in env, weil Leerzeichen in args unter Windows Probleme machen. Für ein selbst signiertes Zertifikat zusätzlich "NODE_EXTRA_CA_CERTS": "C:\\pfad\\node64.pem" in env eintragen; für http:// braucht mcp-remote den Schalter --allow-http.

claude.ai und ChatGPT im Browser

Diese Anwendungen rufen MCP-Server aus ihrer Cloud auf. Dafür müsste die Node öffentlich erreichbar sein und OAuth können – das ist bewusst noch nicht vorgesehen.

Werkzeuge

Alle Werkzeuge lesen nur (readOnlyHint: true, destructiveHint: false). Zeiten sind RFC 3339 in UTC.

Prompts

Prompts nennen nur Werkzeuge, die der Schlüssel auch hat.

Grenzen

• Nur lesen. Ändernde Werkzeuge wie „Check pausieren“ oder eine DNS64-Freigabe folgen später einzeln und standardmäßig aus.
• Nie über MCP: Schlüssel, Benutzer, Anmeldung, Backup, Export und Import, Verknüpfen mit ipv64, Zurücksetzen, Updates.
• Ergebnisse sind begrenzt (limit, Zeiträume); große Listen werden gekürzt (truncated, next_before).
• Kein OAuth, keine öffentliche Erreichbarkeit.

Fehler

Fehler eines Werkzeugs, etwa „Check nicht gefunden“ oder ein gestopptes Modul, kommen als Werkzeug-Ergebnis mit isError.

Prometheus

node64_mcp_enabled (1/0) und node64_mcp_calls_total{tool,result} mit result = ok oder error – siehe Prometheus & Grafana.

Etwas unklar, fehlt etwas oder hast du eine Frage zu Node64? Frag im offiziellen Forum v64.tech.