Dashboard Builder MCP-Server

Ermöglicht einem KI-Client, Ihre Datensätze zu entdecken und Dashboards in Dashboard Builder zu erstellen.

Er kommuniziert mit der Next.js-App über HTTP als gewöhnlicher API-Client, sodass jede Berechtigungsprüfung, Abhängigkeitsrichtlinie und Validierungsregel in der App weiterhin gilt. An der Hauptanwendung ändert sich nichts.

Sie können ihn auf zwei Arten ausführen:

Gehostet ist die normale Bereitstellung und wird in diesem Dokument behandelt. Der lokale Modus dient der Entwicklung des Servers selbst oder für eine benutzerspezifische Identität und wird in DEVELOPMENT.md beschrieben.

Für Benutzer: Verbindung zu einem gehosteten Server

Sie benötigen zwei Dinge von demjenigen, der ihn bereitgestellt hat: die URL und Ihren Gate-Schlüssel. Nichts zu klonen, keine Dateien, auf die Sie zeigen müssen, keine .env.

Fügen Sie dies zu claude_desktop_config.json (Claude Desktop) oder .mcp.json (Claude Code) hinzu:

{
  "mcpServers": {
    "dashboard-builder": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://mcp.yourcompany.com/mcp",
        "--header", "Authorization: Bearer YOUR_KEY_HERE",
        "--header", "X-Dashboard-Username: you",
        "--header", "X-Dashboard-Password: your-dashboard-password"
      ]
    }
  }
}

mcpServers ist ein Top-Level-Schlüssel, ein Geschwister von preferences – nicht darin verschachtelt. Beenden Sie Claude Desktop über das System-Tray und öffnen Sie es erneut; das Schließen des Fensters reicht nicht aus.

Mit den beiden X-Dashboard-*-Headern meldet sich der Server bei der ersten Verwendung automatisch als Sie an und erneut, wann immer die Sitzung abläuft – sonst ist nichts weiter zu tun, und jeder Aufruf handelt als Sie: Ihre Berechtigungen, Ihr Audit-Trail. Der Kompromiss ist, dass Ihr Dashboard-Passwort in dieser Konfigurationsdatei liegt und mit jeder Anfrage (über HTTPS) übertragen wird. Wenn das Passwort Zeichen außerhalb von ASCII enthält, verwenden Sie stattdessen die curl-Bindung unten – HTTP-Header übertragen diese nicht zuverlässig.

Alternative: Einmal mit curl binden, das Passwort aus der Konfiguration heraushalten

Lassen Sie die beiden X-Dashboard-*-Header weg und binden Sie stattdessen Ihren Schlüssel einmal – das Passwort wird für diesen einzelnen Login verwendet und nirgendwo gespeichert; der Server behält nur die resultierenden Sitzungstokens, genau wie ein Browser Cookies behält:

curl -X POST https://mcp.yourcompany.com/auth/bind \
  -H "Authorization: Bearer YOUR_KEY_HERE" \
  -H "content-type: application/json" \
  -d '{"username":"you","password":"your-dashboard-password"}'

Der Unterschied zur Header-Route: Wenn die Sitzungskette schließlich abläuft, führen Sie diesen Befehl erneut aus, während die Header automatisch neu binden. DELETE /auth/bind mit demselben Authorization-Header meldet den Schlüssel in beiden Fällen ab.

Alice's Claude ──[gate key]──> MCP server ──[Alice's session cookies]──> Dashboard API
                     ^                                ^
              client config              bound via credential headers or
                                         POST /auth/bind; refreshed
                                         automatically after that

Wenn ein Schlüssel nie gebunden wurde, schlagen Tool-Aufrufe mit einem Fehler fehl, der den Bindungsschritt erklärt – oder, wenn der Server mit einem Legacy-Dienstkonto konfiguriert ist, fallen sie auf diese gemeinsame Identität zurück.

mcp-remote ist eine kleine Brücke, die lokal läuft und an den Server weiterleitet, daher muss Node auf dem Rechner des Benutzers installiert sein. Um selbst das zu vermeiden, akzeptiert Claude Desktops Einstellungen → Connectors → Benutzerdefinierten Connector hinzufügen eine URL direkt ohne lokale Komponente – dieser Pfad erwartet OAuth anstelle eines statischen Schlüssels, und die Verfügbarkeit variiert je nach Desktop-Version.

Bereitstellung des Servers

server.js ist die Startdatei. Sie lauscht auf PORT wie ein Next.js-server.js und setzt ein API-Schlüssel-Gate vor jede MCP-Anfrage, sodass nicht authentifizierte Aufrufer abgewiesen werden, bevor etwas das Dashboard-System erreicht.

Endpunkte: POST /mcp (geschützt), POST /auth/bind und DELETE /auth/bind (geschützt – bindet oder entbindet die Dashboard-Identität des aufrufenden Schlüssels) und GET /health (offen, für den Plattform-Health-Check). Alles andere gibt 404 zurück.

Umgebungsvariablen

Erforderlich – der Server startet ohne diese nicht

Generieren Sie Schlüssel mit openssl rand -hex 24. Das Label vor dem Doppelpunkt erscheint in Logs und Rate-Limit-Buckets; das Geheimnis selbst wird nie protokolliert. Entziehen Sie einer Person den Zugriff, indem Sie ihren Eintrag entfernen und neu starten – und löschen Sie ihre Sitzungsdatei unter ~/.dashboard-mcp/sessions/, um auch die gebundene Identität zu entfernen.

Jeder Schlüssel wird dann von seinem Inhaber über POST /auth/bind an ein Dashboard-Konto gebunden – siehe Benutzerabschnitt oben. Keine Dashboard-Anmeldedaten liegen in der Umgebung des Servers.

Optionaler Legacy-Fallback – ein gemeinsames Dienstkonto

Wenn gesetzt, handeln nicht gebundene Schlüssel als dieses gemeinsame Konto, anstatt zu fehlschlagen – ebenso wie ein Schlüssel, dessen Bindung abgelaufen ist, bis er neu gebunden wird. Nützlich während der Migration; für neue Bereitstellungen weglassen, damit jeder Aufrufer seine eigene Identität hat.

Stark empfohlen

Lassen Sie DASHBOARD_MCP_PERSIST_SESSION auf dem Standardwert (true): Bindungen werden als eine Datei pro Schlüssel gespeichert und überleben Neustarts. Wenn Sie es auf false setzen, bleiben Bindungen nur im Speicher, sodass jeder Neustart – und jeder Worker in einem Multi-Worker-Host – eine eigene Neubindung benötigt.

MCP_ALLOWED_HOSTS und MCP_ALLOWED_ORIGINS sind optional – der Server läuft ohne sie, und das API-Schlüssel-Gate gilt weiterhin. Das Setzen einer der beiden aktiviert den DNS-Rebinding-Schutz des Transports. Lassen Sie beide ungesetzt, und das Startprotokoll sagt dies ausdrücklich.

Optional

Weitere Tuning-Variablen – Sitzungsdateipfad, Anforderungs-Timeout, Antwortbegrenzungen und die Überschreibung der Dashboard-Kind-ID – sind inline in .env.example dokumentiert, das nach Modus organisiert ist und jede Variable auflistet, die der Server liest.

Hinweis zu mehreren Workern

Bindungen sind eine Datei pro Schlüssel, und ein Worker, dessen In-Memory-Token von einem anderen Worker rotiert wurde, erholt sich, indem er diese Datei erneut liest, die der gewinnende Worker bereits aktualisiert hat. Das Fehlerfenster besteht darin, dass zwei Worker dasselbe Token gleichzeitig aktualisieren; der Verlierer erholt sich beim nächsten Versuch, und im schlimmsten Fall muss der Schlüssel neu gebunden werden. Der MCP-Transport selbst ist zustandslos, sodass Anfragen auf jedem Worker landen können.

Plesk-Einrichtung

Fügen Sie zu den Zusätzlichen nginx-Direktiven der Domain hinzu:

proxy_buffering off;
proxy_read_timeout 300s;

MCP antwortet als Server-Sent Events, und nginx puffert standardmäßig proxierte Antworten. Ohne proxy_buffering off scheinen Anfragen zu hängen, anstatt fehlzuschlagen, was eine verwirrende Art ist, einen Nachmittag zu verlieren.

Halten Sie den Node-Port von der öffentlichen Firewall fern. Plesks nginx proxyt zu ihm und setzt X-Forwarded-For, was die protokollierten Client-IPs vertrauenswürdig macht.

Zugriff versus Identität

Der Gate-Schlüssel kontrolliert den Zugriff; die Identität stammt aus der Bindung. Der Schlüssel bringt einen Aufrufer am Gate vorbei, und die an diesen Schlüssel gebundene Sitzung entscheidet, was das Dashboard sieht – ihre Berechtigungen, ihren Audit-Trail. Die beiden sind bewusst getrennt: Das Rotieren des Geheimnisses eines Schlüssels verwirft seine Bindung (die Sitzung wird unter dem Digest des Schlüssels abgelegt), und das Entziehen eines Schlüssels entfernt den Zugriff, ohne das Konto zu berühren.

Die Bindung funktioniert wie ein Browser-Login. POST /auth/bind führt das echte /api/auth/login der App einmal aus, das Passwort wird nach dem Austausch verworfen, und nur die rotierende Refresh-Token-Sitzung wird aufbewahrt – eine Datei pro Schlüssel, Modus 0600. Da die App das Refresh-Token bei jeder Verwendung rotiert, stirbt eine durchgesickerte Sitzungsdatei schnell; da das Passwort nie gespeichert wird, gibt es nichts Langlebiges, das durchsickern könnte. Der Kompromiss: Wenn eine Refresh-Kette abläuft oder bricht, bindet dieser Schlüssel mit einem curl neu.

Eine stabile, pro Anfrage gültige Anmeldeinformation (ApiKey im Hauptsystem oder OAuth) würde sogar diese Neubindung überflüssig machen, erfordert aber Änderungen in der Hauptanwendung. Dieses Design benötigt bewusst keine.

Lokale Entwicklung oder Ausführung

Das Ausführen des Servers auf Ihrem eigenen Rechner – für die Entwicklung oder für eine benutzerspezifische Identität ohne Hosting – ist separat in DEVELOPMENT.md dokumentiert.

Tools

Designhinweise

Kontextdisziplin. Die gesamte Tool-Oberfläche umfasst etwa 3,6 KB – 13 Beschreibungen plus die Server-Anweisungen –, sodass sie kostengünstig geladen bleiben kann. Antworten sind kompakter Text statt rohem JSON, und jede Liste ist mit einem expliziten Hinweis darauf versehen, was weggelassen wurde. get_dashboard lässt Widget-Konfigurationen bewusst aus; wenn du eine Konfiguration benötigst, fragst du gezielt nach einem Widget anhand seiner ID.

Progressive Offenlegung. Eine Diagrammkonfiguration hat ungefähr 59 Felder. Das in eine Tool-Beschreibung aufzunehmen würde den Kontext des Clients bei jeder Anfrage dominieren, daher stellt describe_widget_kind den Vertrag stattdessen bei Bedarf bereit: Feldnamen, Typen, Hinweise, ein minimal funktionierendes Beispiel und – der nützliche Teil – eine echte Konfiguration, die aus einem vorhandenen Widget dieser Art in deinem eigenen Workspace stammt. Eine Form zu übernehmen, die bereits gerendert wird, ist besser, als eine aus Feldnamen zu erfinden.

Der Server übernimmt die Geometrie. Modelle sind bei 2D-Packing unzuverlässig. add_widget nimmt einen size-Hinweis (small, medium, large, full) und findet selbst die erste freie, nicht überlappende Zelle auf dem 12-Spalten-Raster. arrange_dashboard im Modus auto packt ein gesamtes Dashboard neu.

Vor der API scheitern, nicht danach. Widget-Konfigurationen werden von der App als undurchsichtiges JSON gespeichert, sodass ein falsch geschriebener Schlüssel ein leeres Widget statt eines Fehlers erzeugt. add_widget validiert die Konfiguration zuerst gegen den Vertrag der Art – erforderliche Schlüssel, gültige Aggregationsnamen, field vorhanden, wenn die Aggregation eines benötigt – und gibt eine spezifische Liste dessen zurück, was fehlt.

Widgets entsprechen dem, was die UI erstellen würde. Die Palette der App bestückt jedes neue Widget mit dem defaultConfig der Art aus der Registrierung (config === undefined ? def.defaultConfig : config). add_widget spiegelt das wider: Die Standardwerte der Art werden unter das gelegt, was der Aufrufer liefert, sodass ein von MCP erstelltes Diagramm dieselbe paginationMode- und maxPoints-Basis hat wie ein manuell erstelltes, statt einer spärlichen Konfiguration, auf die der Renderer zurückfallen müsste. Das zusammengeführte Objekt ist es, das validiert wird.

Zusammenführen statt erneut senden. PATCH /widgets/:id ersetzt das Konfigurationsobjekt vollständig. update_widget führt standardmäßig deine Schlüssel mit der vorhandenen Konfiguration zusammen, sodass das Ändern einer Einstellung nicht bedeutet, alles erneut zu senden.

Beim Start standardmäßig sicher. Der HTTP-Server weigert sich, ohne mindestens einen MCP_API_KEYS-Eintrag zu starten, und lehnt Schlüssel unter 24 Zeichen ab. Ein unauthentifizierter MCP-Endpunkt sollte nie versehentlich möglich sein. Schlüssel werden als SHA-256-Digests mit timingSafeEqual verglichen, und nur Bezeichnungen werden protokolliert.

Bekannte Grenzen

• Der Katalog der Widget-Arten ist eine Kopie. src/catalog/widget-kinds.ts spiegelt src/features/dashboard/widgets/registry.ts – einschließlich des defaultConfig jeder Art – und die Konfigurationsschnittstellen pro Art. Die Registrierung der App ist eine Client-Komponente und importiert React, kann also hier nicht importiert werden. Wenn eine Widget-Art ein Feld hinzubekommt oder sich ein defaultConfig-Wert ändert, aktualisiere auch den Katalog, sonst weichen MCP-erstellte Widgets von UI-erstellten ab.

• Die Katalogabdeckung ist hoch, aber nicht vollständig. Dokumentierte vs. tatsächliche Konfigurationsfelder: table 18/21, stat 22/25, chart 39/59, select 9/12, text 16/17. Was weggelassen wird, sind größtenteils kosmetische Varianten (Kreis-/Linien-/Balkendiagramm-Stiloptionen, Überschreibungen der rechten Achse) und veraltete Interaktionsschlüssel, die durch highlightBindings ersetzt wurden. Das Live-Beispiel, das describe_widget_kind zurückgibt, ist dafür die Referenz. Felder sind in Kern / Anzeige / Interaktion gruppiert, damit der Datenvertrag zuerst gelesen wird.

• Bindings laufen mit der Aktualisierungskette ab. Die Sitzung eines Schlüssels dauert so lange, wie die App ihr rotierendes Aktualisierungstoken am Leben hält. Wenn es abläuft, schlagen Aufrufe mit einem Fehler fehl, der die Behebung nennt, und der Inhaber des Schlüssels bindet sich mit einem einzigen curl neu. Eine nie ablaufende Identität erfordert, dass ApiKey in src/lib/api-guard.ts im Hauptsystem verdrahtet wird, was nicht geschehen ist.

• Schreibvorgänge erfolgen direkt. Die App hat einen Arbeitsablauf für Änderungsentwürfe und Genehmigungen (ChangeDraft, ApprovalRequest). Diese Tools schreiben direkt mit den Berechtigungen des angemeldeten Kontos. Wenn KI-erstellte Dashboards vor der Veröffentlichung überprüft werden sollen, leite die Schreib-Tools stattdessen über /api/change-drafts und halte die Berechtigungen des Kontos schreibgeschützt.