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`)

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

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)

`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 wird ein HTTP-403-Fehler (AppError::Forbidden) zurückgegeben. 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.