MCP-Tool-Oberfläche

Agenten kommunizieren mit der SupaCloud-Plattform über eine MCP-Registry, die in server/src/services/mcp/ definiert ist. Jedes Tool gehört genau einer Stufe an; die Stufe bestimmt, welcher Allowlist-Eintrag es freischaltet und welchen Rate-Limit-Bucket es verbraucht.

Stufen und Allowlist-Einträge

Stufe	Allowlist-Wildcard	Ebenfalls gewährt durch
Baseline	bedingungslos (immer aktiv)	`supacloud.*`, `supacloud.full`
Read	`supacloud.read.*`	`supacloud.full`, exakter Name
Ops	`supacloud.ops.*`	`supacloud.full`, exakter Name
`script.run`-Carve-out	`supacloud.script.run`	`supacloud.full`, exakter Name
Scaffold	`supacloud.scaffold.*`	`supacloud.full`, exakter Name
Deploy	`supacloud.deploy.*`	`supacloud.full`, exakter Name

supacloud.ops.* schließt script.run nicht ein. Skripte können zur Laufzeit an Workspace-Ressourcen und Secrets gebunden werden; daher erfordert der Carve-out eine bewusste zusätzliche Freigabe.

Ein Task ohne Profil (Workflow- oder Auto-Developer-Task ohne agent_profile_id) wird auf die read-only-Standardoberfläche aufgelöst (supacloud.read.*). Ops- und Deploy-Stufen bleiben fail-closed, solange kein explizites Agentenprofil sie freigibt (ADR 0033).

Jedes einzelne Tool kann außerdem durch seinen exakten Namen oder durch supacloud.<tool-name> gewährt werden.

Baseline-Tools (N+4, immer aktiv)

Werden jeder authentifizierten Agentensitzung bedingungslos gewährt.

Tool	Beschreibung
`delegate_subtask`	Begrenzte Arbeit an ein anderes Agentenprofil delegieren
`get_subtask_result`	Ergebnis eines delegierten Child-Tasks lesen
`cancel_subtask`	Einen delegierten Child-Task abbrechen
`memory.search`	Volltextsuche über Workspace- und Projekt-Memories
`memory.get`	Einen Memory per UUID lesen
`memory.list_recent`	Aktuelle Workspace- und Projekt-Memories auflisten
`memory.propose_review`	Einen ausstehenden Memory-Review-Vorschlag einreihen (keine sofortige Mutation)
`outcome.recent_for_profile`	Aktuelle Outcome-Telemetrie für das Agentenprofil dieses Tasks lesen

Read-Stufe — `supacloud.read.*`

Alle Tools sind read-only und auf den Workspace der Task-Sitzung beschränkt.

Workspace- und Plattform-Reads

Tool	Beschreibung
`workspace.info`	Aktive Workspace-Metadaten (Slug, Name, Mitgliederzahl, verbleibendes Budget, Plan-Stufe)
`projects.list`	Im Workspace sichtbare Projekte
`project.get`	Detail eines einzelnen Projekts
`tasks.list_active`	Laufende und wartende Tasks im Workspace
`tasks.get`	Detail eines einzelnen Tasks (Kosten, Dauer, letztes Ereignis)
`runners.status`	Runner-Verfügbarkeit und -Kapazität
`schedules.list`	Aktive Schedules im Workspace
`resources.list`	Konfigurierte Ressourcen — nur Art, Name und Status; keine Verbindungszeichenketten oder Secrets
`apps.list`	Apps mit Deployment-Status und öffentlicher URL
`app.get`	Detail einer einzelnen App
`workflows.list`	Definierte Workflows
`workflow.get`	Workflow-Detail inkl. Schritte (flach aus `workflow_nodes` + `workflow_edges`)
`app.migration.list`	Ausstehende und angewendete Migrationen einer App

Run-Beobachtung

Read-only-Tools für Runs, Boards und Ereignisse. Runs sind zuerst auf den Workspace beschränkt, sodass Detail und Ereignisse eines Runs niemals über Workspaces hinweg durchsickern.

Tool	Beschreibung
`run.list`	Aktuelle Top-Level-Runs jeder Art (agent/workflow/script/app) auflisten, neueste zuerst, mit optionaler Eingrenzung nach Status/Kind/Projekt/Task/App
`run.get`	Einen Run per ID lesen samt seines flach ausgegebenen Nachfahren-Run-Baums (Workflow-Knoten-Runs und Schleifen-Iterationen)
`run.events`	Das Ereignisprotokoll eines Runs lesen, paginiert per Sequenznummer (`after_sequence` / `limit` / `tail`). Seit #977 trägt das Protokoll eines Workflow-Runs zusätzlich eine Schritt-Zeitleiste je Knoten (`workflow_node_started` / `_waiting` / `_completed` / `_failed` / `_skipped`)
`approvals.list`	Die wartenden Entscheidungs-Gates des Workspace auflisten — pausierte Task-Gates (`filter: "tool"`, Prompt redigiert) und Workflow-Human-Gates (`filter: "workflow"`)
`backlog.list`	Backlog-Einträge auflisten, optional nach Projekt und Zustand eingegrenzt
`backlog.get`	Einen Backlog-Eintrag mit seinen Vorläufen und der Routing-Entscheidung lesen

Quell-Reads (W7-3)

Tool	Beschreibung
`app.files.list`	App-Quelldateien auflisten
`app.files.get`	Eine App-Quelldatei lesen (Inhalt auf 64 KiB begrenzt)
`script.get`	Eine Skript-Definition lesen
`script.list`	Skripte im Workspace auflisten
`app.builds.list`	Build-Verlauf einer App auflisten

Issue-Reads (ADR 0033)

Aufgelöst aus project.issue_tracker ?? project.git_provider — deckt alle sechs Quellen ab (GitHub, GitLab, Bitbucket, Forgejo, Linear, Notion).

Tool	Beschreibung
`issue.get`	Einen einzelnen Issue per ID lesen
`issue.list`	Offene Issues des Projekts dieses Tasks auflisten

Conversation-Reads (#596)

Provider-agnostische Support-Konversationen (Chatwoot / Intercom). Adressiert über einen expliziten Workspace-resource-Namen (den Support-Kanal) — kein projekt-level Binding. Ebenfalls über supacloud.conversation.* gewährt.

Tool	Beschreibung
`conversation.get`	Eine einzelne Konversation per ID aus einer Workspace-Ressource lesen
`conversation.list`	Offene Konversationen einer Workspace-Ressource auflisten

Dokumentations- und Vertrags-Reads (#844)

Die einzigen Tools, die weder die Datenbank noch eine Mandanten-Ressource lesen. Sie liefern den instanzweiten, eingecheckten Dokumentationskorpus (docs/user, docs/admin, docs/developer und den deutschen Spiegel docs/de) sowie die vier drift-geprüften Maschinenverträge — damit ein Agent nachschlagen kann, wie eine Oberfläche sich verhält, statt zu raten.

Tool	Beschreibung
`docs.search`	Stichwortsuche über die Produktdokumentation. Jeder Suchbegriff muss in Pfad, Titel oder Text einer Seite vorkommen; Treffer werden nach Termhäufigkeit sortiert und tragen den Pfad für `docs.get`. Optional `lang` (`en`/`de`) und `limit` (Standard 10, max. 50)
`docs.get`	Eine Seite über ihren korpus-relativen `.md`/`.mdx`-Pfad lesen (z. B. `user/how-to/approve-agent-actions.mdx`). Das YAML-Frontmatter wird entfernt, der Text bei 64 KiB gekappt. `lang: "de"` löst den deutschen Spiegel des Pfades auf, sofern vorhanden
`spec.get`	Einen eingecheckten Vertrag über `name` lesen: `openapi_public`, `workflow_schema`, `mcp_catalog` oder `command_catalog`. Ein grosses Dokument lässt sich mit einem RFC-6901-`pointer` (z. B. `/paths`) eingrenzen; der gerenderte Text wird bei 64 KiB gekappt und eine gekappte Antwort listet die Kind-`keys` des gewählten Knotens zum Weiternavigieren
`models.list`	Der Modellkatalog dieser Instanz: Anbieter, exakte Modell-ID, Kontextfenster, Preise je Million Token, Eingabemodalitäten, Werkzeugaufruf- und Reasoning-Unterstützung. Filtern mit `provider` (exakte ID) oder `query` (Teilstring über ID und Anzeigename, Gross-/Kleinschreibung egal — so wird aus „Gemini Flash 3.7” die ID, die ein Lauf braucht). `limit` steht auf 50, kappt bei 200, und `total_matches` nennt die Trefferzahl vor dem Schnitt

models.list beantwortet, welche Modelle es gibt — nicht, für welche dieser Workspace eine Anmeldung besitzt. Es ist instanzweites Referenzmaterial und trägt keine Workspace-Information. Ebenso wenig trägt es die Harness-Fähigkeiten pro Modell (Effort-Leiter, Fast-Mode, Subagenten), die die Modell-Auswahl anzeigt; die stammen aus einer separaten Fähigkeitstabelle.

spec.get legt docs/openapi/management.json bewusst nicht offen: die Management-Spezifikation ist die M2M-Control-Plane-Oberfläche und kein Agenten-Referenzmaterial — sie freizugeben würde die Agentenoberfläche verbreitern und braucht eine ausdrückliche Owner-Entscheidung.

Da sie keine Mandantendaten tragen und keinen Task-Kontext brauchen, sind alle drei auch über das externe MCP-Gateway (ADR 0054) mit einem mcp:read-Token erreichbar.

Ops-Stufe — `supacloud.ops.*`

Schreib-Tools; 10 Aufrufe pro Task. supacloud.ops.* schließt script.run nicht ein.

Tool	Beschreibung
`workflow.trigger`	Einen Workflow-Run starten
`schedule.create`	Einen neuen Schedule anlegen
`schedule.update`	Einen bestehenden Schedule aktualisieren
`schedule.pause`	Einen Schedule pausieren
`schedule.resume`	Einen pausierten Schedule fortsetzen
`repo_sync.trigger`	Einen Repo-Sync-Push oder -Pull auslösen
`issue.comment`	Einen Kommentar zu einem Issue posten (beliebiger der sechs Provider)
`issue.transition`	Einen Issue in einen neuen Zustand überführen
`pr.create`	Einen Pull Request anlegen (nur Git-Forge)
`conversation.reply`	Eine kundensichtbare Antwort (oder `private`-Notiz) in eine Konversation posten (#596; idempotency-keyed)
`conversation.assign`	Eine Konversation einem Agenten zuweisen (#596)
`conversation.resolve`	Eine Konversation auflösen (schließen) (#596; idempotency-keyed)
`conversation.handoff`	Eine Konversation an ein anderes Team übergeben (#596)
`task.create`	Eine Task in einem Projekt dieses Workspace anlegen und starten (#977; die Budget- und die Admin-Closeout-Klemme im Service-Floor greifen)
`task.cancel`	Eine laufende Task dieses Workspace abbrechen (#977)
`task.intervene`	Eine Zwischenmeldung in eine laufende Task senden (#977; mit SYSTEM-Herkunft und `[coordinator]`-Präfix zugestellt)
`approval.decide`	Ein wartendes Gate entscheiden (#977). Nur Task-Gates der Klasse `question` — `tool`-, `visual`- und `tier_change`-Gates sowie jedes Workflow-Human-Gate werden abgewiesen: sie existieren, um einen MENSCHEN in die Schleife zu holen, also darf keine Maschine sie beantworten (die #858-Invariante)
`run.rerun_node`	Einen fehlgeschlagenen oder abgebrochenen Workflow-Knoten der obersten Ebene neu ausführen und den fehlgeschlagenen Child-Run ablösen (#977; nur Stop-Policy-Knoten, nie ein `loop`-Rahmen)
`permission.grant`	Eine gescopte Werkzeug-Berechtigung erteilen (#581-A)
`permission.revoke`	Eine gescopte Werkzeug-Berechtigung widerrufen (#581-A)

`script.run`-Carve-out — `supacloud.script.run`

Tool	Beschreibung
`script.run`	Ein Workspace-Skript ausführen

Wird auf den Ops-Rate-Limit-Bucket angerechnet (10/Task). Ein optionales script_allowlist-Array im Agentenprofil schränkt zusätzlich ein, welche Skripte (per Slug) aufgerufen werden dürfen.

Scaffold-Stufe — `supacloud.scaffold.*`

Vorschlags- und Task-Spawn-Tools. Vorschläge erstellen eine ausstehende proposals-Zeile zur menschlichen Überprüfung, ohne dauerhaften Zustand zu verändern; Task-Spawn-Tools starten einen Follow-up-Agenten-Task für ein App- oder Skript-Scaffold.

Tool	Beschreibung
`scaffold.script.propose`	Ein neues oder aktualisiertes Skript vorschlagen
`scaffold.app.propose`	Eine neue App vorschlagen
`scaffold.app.file_upsert.propose`	Einen App-Datei-Upsert vorschlagen
`scaffold.workflow.propose`	Einen neuen Workflow vorschlagen
`task.create_for_app_scaffold`	Einen Follow-up-Agenten-Task für ein App-Scaffold starten
`task.create_for_script_scaffold`	Einen Follow-up-Agenten-Task für ein Skript-Scaffold starten

Deploy-Stufe — `supacloud.deploy.*`

Deployment-Lifecycle-Tools; 5 Aufrufe pro Task. supacloud.ops.* schließt Deploy-Tools nicht ein.

Zusätzlich zur Allowlist-Freigabe muss der aufgelöste Task-Akteur die Workspace-Berechtigung Owner oder Admin besitzen — dieselbe Prüfung, die der Deployment-Service für HTTP-Anfragen anwendet.

app.deploy und app.migration.apply erfordern das zweistufige Bestätigungsprotokoll (siehe unten).

Tool	Beschreibung
`app.deploy`	Eine App auf ihrer öffentlichen Route deployen
`app.undeploy`	Eine App von ihrer öffentlichen Route entfernen
`app.pause`	Eine App in den Wartungsmodus versetzen
`app.resume`	Eine pausierte App fortsetzen
`app.migration.apply`	Ausstehende App-Migrationen anwenden

Rate-Limits

Task-bezogene Obergrenzen

Stufe	Standard	Konfigurations-Env-Var
Baseline + Read	50 / Task	`AGENT_MCP_TOOL_RATE_LIMIT`
Ops (inkl. `script.run`)	10 / Task	—
Scaffold	10 / Task	—
Deploy	5 / Task	—

Workspace- und Profil-Obergrenzen

Task-bezogene Limits werden zuerst geprüft; nur wenn ein Aufruf innerhalb des Task-Budgets liegt, wird die Reservierung der täglichen Workspace- bzw. stündlichen Profil-Obergrenze versucht (der Task-Slot wird zurückgebucht, wenn die Workspace-/Profil-Reservierung danach scheitert). Zähler werden aus audit_events abgeleitet und überstehen Neustarts.

Geltungsbereich	Stufe	Standard	Konfigurations-Env-Var
Workspace / Tag	Ops	100 Aufrufe	`AGENT_MCP_WORKSPACE_OPS_DAILY_LIMIT`
Workspace / Tag	Deploy	20 Aufrufe	`AGENT_MCP_WORKSPACE_DEPLOY_DAILY_LIMIT`
Workspace / Tag	Scaffold-Vorschläge	10 Aufrufe	`AGENT_MCP_WORKSPACE_PROPOSAL_DAILY_LIMIT`
Workspace / Tag	Scaffold-Task-Spawns	3 Aufrufe	`AGENT_MCP_WORKSPACE_TASK_SPAWN_DAILY_LIMIT`
Profil / Stunde	Ops	30 Aufrufe	`AGENT_MCP_PROFILE_OPS_HOURLY_LIMIT`
Profil / Stunde	Deploy	10 Aufrufe	`AGENT_MCP_PROFILE_DEPLOY_HOURLY_LIMIT`
Profil / Stunde	Scaffold-Vorschläge	10 Aufrufe	`AGENT_MCP_PROFILE_PROPOSAL_HOURLY_LIMIT`
Profil / Stunde	Scaffold-Task-Spawns	3 Aufrufe	`AGENT_MCP_PROFILE_TASK_SPAWN_HOURLY_LIMIT`

Bei erschöpftem Rate-Limit erfolgt eine klassifizierte JSON-RPC-Ablehnung (HTTP 200 + ein JSON-RPC-error, dessen data.code rate_limited oder cap_exceeded ist und dessen data.retryable true ist; #1174), kein HTTP 403. Die Task-bezogene Meldung nennt den Tool-Namen (Rate limit exceeded for tool '<tool>'); die täglichen Workspace- und stündlichen Profil-Meldungen nennen die Stufe und geben ein <used>/<limit>-Verhältnis an (Workspace daily limit reached for this MCP tool tier (<used>/<limit>) / Profile hourly limit reached for this MCP tool tier (<used>/<limit>)).

Deploy-Bestätigungsprotokoll

app.deploy und app.migration.apply verwenden eine zustandslose zweistufige Bestätigung, um versehentliche Deploys und veraltete Wiederholungsversuche zu verhindern.

Schritt 1 — Zusammenfassung anfordern. Das Tool ohne confirmation_token aufrufen. Der Server gibt confirmation_required: true, eine changes_summary und einen confirmation_token zurück (HMAC-SHA256, signiert mit SUPACLOUD_MCP_CONFIRMATION_SECRET, enthält den Eingabe-Hash und eine 5-Minuten-Ablaufzeit).

Schritt 2 — Bestätigen. Das Tool erneut mit denselben Eingaben und dem confirmation_token aufrufen. Der Server prüft die Signatur, die Ablaufzeit und ob der Eingabe-Hash mit den aktuellen Argumenten übereinstimmt. Ein idempotency_key ist erforderlich, wenn confirmation_token vorhanden ist.

Der HMAC-Schlüssel ist ein serverseitiges Secret, das über SUPACLOUD_MCP_CONFIRMATION_SECRET gesetzt wird (mindestens 32 Bytes). Wenn nicht gesetzt, schlagen bestätigte Deploy- und Migration-Apply-Aufrufe fail-closed. Der Schlüssel wird niemals aus Task-, Benutzer-, Workspace- oder Profil-Credentials abgeleitet.

Idempotenz-Schlüssel für bestätigte Aufrufe werden in mcp_idempotency_keys gespeichert (auf task_id + tool_name + key beschränkt) und 24 Stunden nach Erreichen des Endzustands des übergeordneten Tasks bereinigt.

Sicherheitseigenschaften

Keine Secret-Offenlegung. resources.list gibt nur Art, Name und Status zurück — niemals Verbindungszeichenketten, Passwörter oder Tokens.
Kein Credential-Zugriff. Agenten können Workspace-Credentials nicht über MCP lesen oder ändern.
Workspace-Isolation. Alle Abfragen sind auf den Workspace des Tasks beschränkt.
Audit-Trail. Jeder Tool-Aufruf erzeugt eine audit_events-Zeile mit Task-Korrelations-ID, Tool-Name, Status und Fehlerklasse.