Zum Inhalt springen
SupaCloud Docs
Farbschema wählenSprache wählen

Einen externen MCP-Koordinator anbinden

Ein externer Koordinator ist ein beliebiger MCP-Client, der SupaCloud von außen steuert — ein Scheduler, ein anderes Agentensystem oder die eigene Automatisierung. Er spricht mit dem externen MCP-Gateway (POST /api/mcp, ein Standard-MCP-Streamable-HTTP-Endpunkt) über ein Workspace-gebundenes API-Token und sieht dieselbe Tool-Fläche wie ein Koordinator-Agent in der App: Run- und Task-Reads, Backlog, Freigaben, Workflow-Trigger, Task anlegen/steuern/abbrechen und Einzelschritt-Reruns.

Der Tab „API-Tokens“ in den Einstellungen, mit den Scope-Kästchen des Erstellen-Formulars und der Liste bestehender Tokens nach Bezeichnung, Status und Fingerprint.Der Tab „API-Tokens“ in den Einstellungen, mit den Scope-Kästchen des Erstellen-Formulars und der Liste bestehender Tokens nach Bezeichnung, Status und Fingerprint.

  1. Token erstellen. Öffne Einstellungen → Anmeldedaten → API-Tokens (Owner oder Admin). Bezeichnung vergeben, Scopes wählen, erstellen:

    • mcp:read — die Lese-Ebene (Runs, Tasks, Backlog, Freigaben, Memories).
    • mcp:ops — die Steuer-Ebene (Workflows auslösen, Tasks anlegen/abbrechen/steuern, Freigaben entscheiden, fehlgeschlagene Schritte neu anstoßen, Zeitpläne verwalten).
    • management:read — optional, lesender Zugriff auf die klassische Management-API neben MCP.

    Der Token-Wert (scmt_…) wird genau einmal angezeigt — jetzt kopieren. Danach bleibt nur der Fingerprint sichtbar; ein Widerruf über den Fingerprint macht das Token sofort unbrauchbar.

  2. MCP-Client auf das Gateway zeigen. Als Streamable-HTTP-Server konfigurieren: URL https://<deine-instanz>/api/mcp, Header Authorization: Bearer <token>. initialize → tools/list zeigt genau die Tools, die die Scopes erreichen; alles andere antwortet mit einem JSON-RPC-method-not-found — die Deploy-Ebene ist extern nie erreichbar.

  3. Den Loop fahren. Typische Koordinator-Aufrufe:

    • run.list / run.get / run.events — Status, der Knoten-Baum und die Schritt-Timeline eines Laufs (jeder Workflow-Knoten schreibt started/completed/failed-Events, bei Fehlern mit stdout/stderr-Auszug).
    • task.create / task.intervene / task.cancel — Agenten-Tasks starten, steuern und stoppen. Budgets und Admin-Closeout-Regeln gelten exakt wie in der App.
    • approvals.list / approval.decide — alles Wartende sehen und pausierte Tool-Freigaben entscheiden. Ein Workflow-Human-Gate wird zwar gelistet, ist für einen Koordinator aber nie entscheidbar: approval.decide weist es als MCP-isError:true-Ergebnis bei HTTP 200 ab (die 403 ist nur die interne AppError::Forbidden-Klasse, nie der Wire-Status), denn genau dieses Gate existiert, um bis zur Entscheidung eines Menschen anzuhalten. Ein Koordinator kann also melden, dass ein Mensch gebraucht wird — mehr nicht.
    • backlog.list / backlog.get — die Einträge des autonomen Backlogs.
    • run.rerun_node — einen fehlgeschlagenen Workflow-Schritt neu ausführen; der Lauf setzt von allein fort, sobald der Schritt gelingt.

  4. Rate-Limits dimensionieren. Derselbe Einstellungs-Tab trägt die externen Limits des Workspace: Lesezugriffe pro Tool und Stunde (Vorgabe 50) und Ops-Aufrufe pro Token und Stunde (Vorgabe 30). Leere Felder behalten die Vorgaben; ein pollender Koordinator braucht meist mehr.

    Diese beiden Limits gelten pro Token — eine ausgelastete Integration nimmt einer anderen also nicht ihr Stundenkontingent weg. Darüber liegt jedoch eine workspace-weite Obergrenze von 100 Ops-Aufrufen pro Tag, die sich alle teilen: Ihre Koordinatoren und die In-App-Agenten schöpfen aus demselben Budget, und ein höherer Stundenwert am Token hebt sie nicht an. Diese Obergrenze ist bewusst nicht aus der Anwendung heraus setzbar; auf einer selbst gehosteten Instanz ändert der Betreiber sie über die Umgebungsvariable AGENT_MCP_WORKSPACE_OPS_DAILY_LIMIT.