Voraussetzungen
- Ein erreichbarer Novaplan AI Workspace mit indexierten Daten und öffentlicher HTTPS-Adresse. Die QM-Agenten laufen in einer entfernten Sandbox;
localhostIhres Laptops ist dort nicht erreichbar. - Ein bestehendes QM-Setup mit Zugriff auf die Agenten-Sandbox und einem eingerichteten Modell.
- Für jede Person ein eigenes Personal Access Token. Teilen Sie kein Token im Team.
sprite login), einen Modell-API-Schlüssel sowie Node.js 24 oder neuer und Docker. Ein Fly-Konto allein ersetzt den Sprites-Zugang nicht. Die Agenten laufen auf Sprites und können localhost Ihres Computers nicht erreichen. bun und ein eigener Quellcode-Build der MCP-CLI sind nicht nötig.
QM bei Bedarf einrichten
Überspringen Sie diesen Abschnitt, wenn QM bereits läuft. Das folgende Beispiel richtet QM ein; Novaplan AI wird dabei nicht bereitgestellt:target: docker startet die QM-Dienste lokal. Die Agenten-Sandboxes laufen weiterhin auf Fly Sprites. Hinterlegen Sie den Sandbox-Typ in qm.config.jsonc an beiden Stellen:
env.core.SANDBOX_BACKEND lädt QM den SPRITES_TOKEN für seinen Core. Steht sprites ausschließlich unter sandbox, kann qm check erfolgreich sein, während die Bereitstellung später scheitert. Prüfen Sie den Plan auf nicht weitergereichte .env-Schlüssel:
qm setup kann für übersprungene Werte leere Platzhalter in .env schreiben. Prüfen Sie vor einer Fehlersuche, ob ein später eingetragener Wert dadurch doppelt vorkommt. Der erste Start kann wegen großer Container-Downloads länger dauern.
CLI-Integration vorbereiten
Nach Freigabe durch Novaplan installieren Sie die geprüfte Version des dokumentierten Pakets und rufen die Einrichtungsroutine im QM-Verzeichnis auf:sandbox/Dockerfile, die dort nicht verwendet wird. Prüfen Sie vor dem Aufruf pipeshub --version. Wenn init-qm bereits mit 2.3.1 ausgeführt wurde, entfernen Sie die zurückgebliebene sandbox/Dockerfile, bevor Sie das Setup mit der freigegebenen Version erneut prüfen. Wiederholtes init-qm behält vorhandene Dateien bei.
Die Routine legt Dateien unter sandbox/tools/pipeshub/ an. Tragen Sie in sandbox/tools/pipeshub/tool.json für egress ausschließlich den von Novaplan bestätigten Hostnamen ein, etwa workspace.example.com, ohne https:// und ohne Pfad. Der Verzeichnisname ist eine funktionale Kennung des Pakets. Prüfen Sie danach die Konfiguration und laden Sie QM neu:
qm sandbox publish installiert den Befehl pipeshub nicht auf Fly Sprites. Die CLI wird dort bei der ersten Nutzung installiert; diese Installation bleibt auf der jeweiligen Sprite erhalten.
Persönliche Zugangsdaten in QM
Jede Person legt zwei persönliche Keychain-Einträge an. Für das gebündelte QM-Setup empfehlen wir diese Bezeichnungen:
Die QM-CLI in MCP-Paketversion 2.3.3 akzeptiert auch
PIPESHUB_MCP_TOKEN und PIPESHUB_MCP_URL; bei letzterer entfernt sie den /mcp-Pfad. Wenn Sie den Paste-Block aus der Token-Oberfläche verwenden, teilen Sie ihn in zwei persönliche Keychain-Einträge auf und tragen Sie den jeweiligen Variablennamen ausdrücklich ein. Geben Sie ein PAT niemals in einem Chat ein und speichern Sie es nicht in sandbox.secretEnv, weil dieser Bereich für die gesamte Organisation gelten kann. Bei einem gemeinsam genutzten Workspace muss jede Person mit ihrer eigenen Identität arbeiten.
Erstellen Sie das PAT unter Developer Settings → Personal Access Tokens → New token mit begrenzter Laufzeit und den für die Integration nötigen Scopes. Nicht ausgewählte Scopes können in der zugrunde liegenden Implementierung die vollständig konfigurierten MCP-Scopes freigeben. Der phpat_-Präfix gehört zum angezeigten Token und darf nicht entfernt werden. semantic:read betrifft den Suchverlauf, nicht die eigentliche Suche; für die CLI-Suche wird semantic:write verwendet.
Geben Sie für beide Keychain-Einträge den Variablennamen ausdrücklich ein. Ohne Variablennamen kann QM aus dem Service pipeshub zwar PIPESHUB_TOKEN ableiten, jedoch nicht PIPESHUB_BASE_URL. Die Workspace-Adresse sollte ebenfalls als persönlicher Keychain-Eintrag oder, nach organisatorischer Prüfung, als Team-Service-Credential mit Lieferung per env gespeichert werden. sandbox.env wird nicht an Sprites weitergereicht.
Erste Frage und Quellenprüfung
Bitten Sie den Agenten in einem neuen QM-Chat beispielsweise: „Was wissen wir über dieses Thema? Nenne die Quelle.“ Fehltpipeshub auf der Sprite, kann der Agent den Befehl einmalig installieren:
ask, search, get und sources. Ein direkter Aufruf von GET /api/v1/search fragt den Suchverlauf ab und ersetzt nicht die CLI-Suche. Falls die CLI keine Verbindung meldet, kann pipeshub auth connect-help die unterstützten Anmeldewege anzeigen; fügen Sie ein Token niemals in den Chat ein.
Wenn die CLI recordId oder webUrl zurückgibt, kann der Agent diese als Quellen anführen. Exit-Code 6 bei ask bedeutet, dass die Antwort keine Quellenobjekte enthält. Kennzeichnen Sie sie dann als unbelegt und nicht bestätigt; erfinden Sie keine Quellen.
Verbindung prüfen
Die vorhandene CLI bietet nach Freigabe beispielsweise diese Prüfungen:semantic:read verlangt, prüfen Sie, ob es versehentlich die API für den Suchverlauf statt der dokumentierten CLI-Suche verwendet; erweitern Sie den Token nicht allein aufgrund dieser Fehlermeldung.
Bei 401 prüfen Sie Ablauf, Widerruf und Scopes des persönlichen Tokens. Entfernen Sie den phpat_-Präfix nicht aufgrund einer Vermutung. Wenn der Agent die Workspace-Adresse nicht erreicht, prüfen Sie die QM-Sandbox und deren egress-Freigabe. Novaplan Support kann die Kompatibilität des Pakets und den bereitgestellten Endpunkt bestätigen.