Macaly Cloud MCP-Server - Macaly Documentation

Macaly Cloud ist ein MCP-Server, der Macaly zur Infrastruktur hinter deinem eigenen KI-Coding-Agenten macht. Dein Agent schreibt jede Zeile Code; Macaly liefert das Git-Repository, die Cloud-Sandbox, Datenbank und Plattformfunktionen, den Build, die teilbare Vorschau und das Produktions-Hosting auf macaly.app. Auf deinem Rechner entsteht nichts, und Macalys eigener Agent läuft nie. Die App liegt ab der ersten Datei in deinem Macaly-Workspace - du kannst sie jederzeit im Macaly-Editor öffnen und dort weiterbauen.

Was du brauchst

Du brauchst einen MCP-Client, der Remote-Server über Streamable HTTP unterstützt - Claude (claude.ai, Desktop, Cowork), Claude Code, ChatGPT, Cursor, Grok Bot oder Codex.

Client verbinden

Claude, ChatGPT, Cursor und Grok Bot installieren Macaly Cloud aus ihren offiziellen Verzeichnissen. In Macaly findest du unter Einstellungen → Verbindungen für jeden von ihnen eine Karte mit denselben Schritten und einem Link zum Eintrag. Andere Clients fügen den Server unter dieser Adresse hinzu:

https://www.macaly.com/api/cloud/mcp

In beiden Fällen öffnet dein Client ein Browserfenster, in dem du dich bei Macaly anmeldest und den Zugriff freigibst (OAuth). Es gibt keine Schlüssel zum Kopieren.

Öffne den Macaly-Cloud-Eintrag im Claude-Connector-Verzeichnis. Er funktioniert in claude.ai, in der Desktop-App und auf dem Handy.
Klicke auf Connect.
Melde dich bei Macaly an und gib den Zugriff im Fenster frei, das sich öffnet.

Führe im Terminal aus:

claude mcp add macaly-cloud --transport http https://www.macaly.com/api/cloud/mcp

Starte dann Claude Code und melde dich mit /mcp bei Macaly an.

Öffne das Macaly-Cloud-Plugin im Cursor Marketplace und füge es hinzu. Du kannst auch /add-plugin macaly-code im Cursor-Chat ausführen.
Wenn Cursor deinen Browser öffnet, melde dich bei Macaly an und gib den Zugriff frei.

Führe im Terminal aus:

codex mcp add macaly-cloud --url https://www.macaly.com/api/cloud/mcp
codex mcp login macaly-cloud

Stattdessen einen API-Key verwenden

Du kannst dich statt mit OAuth auch mit einem Macaly-API-Key authentifizieren - praktisch für Headless-Agenten und Automatisierung. Übergib den Key als Bearer-Token:

{
  "mcpServers": {
    "macaly-cloud": {
      "url": "https://www.macaly.com/api/cloud/mcp",
      "headers": {
        "Authorization": "Bearer macaly_your_api_key_here"
      }
    }
  }
}

API-Keys gelten für genau einen Workspace, deshalb ermitteln Tools mit teamId diesen automatisch.

Eine App von Anfang bis Ende bauen

App erstellen

Dein Agent ruft create_app mit einem Namen auf. Zurück kommen eine chatId und das Projekt-Briefing. Die App wird leer angelegt - kein Start-Prompt, kein KI-Build.

Code schreiben

write_file schreibt eine ganze Datei, und edit_file ersetzt exakten Text in einer bestehenden Datei, sodass bei einer kleinen Änderung an einer großen Datei nicht die ganze Datei erneut gesendet wird. Jeder write_file-, edit_file- und delete_file-Aufruf ist ein atomarer Git-Commit mit eigenem Eintrag in der App-Historie. Der erste Schreibvorgang in einem kalten Workspace dauert ~20-30 Sekunden länger, während die Sandbox hochfährt.

Plattformfunktionen ergänzen

Für Datenbank, Zahlungen, KI, Medien oder Suche liest der Agent die Anleitung mit skill_info und führt ihre Befehle mit bash aus - die Sandbox hält die Zugangsdaten, die die Anleitungen brauchen, bereits bereit.

Typecheck

Nach dem letzten Schreibvorgang führt der Agent bash ".sandbox/check-errors --strict" aus - das findet Typ-, Style- und Server-Fehler in einem Durchgang, endet mit einer Zusammenfassung des Ergebnisses und bricht mit einem Fehler ab, wenn TypeScript oder CSS fehlschlägt. Schlägt etwas fehl, liefert get_logs die echte Ausgabe.

Vorschau

Die Vorschau wird ein paar Sekunden nach dem letzten Schreibvorgang automatisch neu gebaut. Sobald sie erfolgreich ist, gibt preview_app die Live-URL zum Öffnen oder Teilen zurück. Mit path öffnet der Link direkt eine Unterseite, zum Beispiel /pricing. Der Agent ruft preview_app am Ende jedes Durchlaufs auf, der die App geändert hat, auch wenn ein früherer Link noch gültig ist - dieser Aufruf teilt Macaly mit, dass der Durchlauf beendet ist.

Veröffentlichen

Wenn du ausdrücklich live gehen willst, ruft der Agent publish_app auf und fragt get_deployment mit der zurückgegebenen deploymentId ab, bis der Status READY lautet. Danach gibt er dir liveUrl, die Adresse der Version, die live ist. connect_domain hängt eine eigene Domain an oder benennt die Macaly-Subdomain um.

Verfügbare Tools

Macaly Cloud stellt 20 Tools bereit.

Workspaces & Apps

Tool	Was es tut
`list_teams`	Listet die Workspaces auf, in denen du bauen kannst
`create_app`	Erstellt eine neue, leere App auf dem Standard-Stack und liefert ihr Briefing
`list_projects`	Listet die Apps eines Workspaces auf, zuletzt aktualisierte zuerst, mit Suche und Paginierung. Angepinnte Apps erscheinen auf der ersten Seite
`get_project`	Statusübersicht: Build-Status der Vorschau, Vorschau-URL, der neueste Veröffentlichungsstatus und `liveUrl`, das Briefing und wer gerade an der App arbeitet
`get_messages`	Liest den Chat-Verlauf der App - was angefragt und was schon gebaut wurde - bevor Änderungen anstehen
`duplicate_app`	Dupliziert eine App samt Historie in eine neue

Code

Tool	Was es tut
`list_files`	Listet die Quelldateien der App auf
`read_file`	Liest eine Datei anhand ihres Pfads oder mit `startLine` und `endLine` nur einen Zeilenbereich daraus
`write_file`	Schreibt eine Datei vollständig und committet sie sofort
`edit_file`	Ersetzt exakten Text in einer bestehenden Datei und committet sie sofort - bis zu 20 Ersetzungen pro Aufruf, entweder alle oder keine
`delete_file`	Löscht eine Datei und committet die Löschung sofort
`bash`	Führt einen Shell-Befehl in der Sandbox der App aus - Installationen, CLIs, Skill-Skripte und den Typecheck `.sandbox/check-errors --strict`. Ein Befehl darf bis zu 32.000 Zeichen lang sein und bis zu 240 Sekunden laufen

Medien

Tool	Was es tut
`upload_file`	Fügt eine Datei zur Medienbibliothek der App hinzu und liefert ihre permanente öffentliche URL (bis 1 GB). Die Datei kommt von einer öffentlich erreichbaren URL oder über einen fertigen `curl`-Befehl von deinem Computer oder aus der Sandbox der App
`list_media`	Listet die Dateien in der Medienbibliothek der App mit ihren öffentlichen URLs auf und liefert einen Link, unter dem du eine lokale Datei ablegen kannst

Kein Tool nimmt rohe Dateibytes entgegen. Für eine Datei auf deinem Computer liefert upload_file einen curl-Befehl, den dein Agent in deiner eigenen Shell ausführt. Für eine Datei, die der Agent in der Sandbox erstellt hat, führt er den Befehl in der Sandbox aus. Hat dein Agent keine Shell, zieh die Datei über den Link aus list_media in die Medienbibliothek.

Lege generierte oder heruntergeladene Bilder, Audio- und Videodateien nicht im public/-Ordner der App ab. Jeder Vorschau-Build lädt public/ erneut hoch, daher verlangsamen viele oder große Dateien den Build und können ihn fehlschlagen lassen. Lade Medien mit upload_file hoch und verwende die zurückgegebene URL.

Funktionen & Diagnose

Tool	Was es tut
`skill_info`	Liest die Anleitung zu einer Plattformfunktion, mit ausführbaren Befehlen und den anzuwendenden Codemustern
`get_logs`	Holt Build-, Dev-Server- oder Deployment-Logs
`preview_app`	Gibt einen drei Stunden gültigen Vorschaulink zum Teilen zurück, optional für eine Unterseite

Veröffentlichen

Tool	Was es tut
`publish_app`	Veröffentlicht die App unter ihrer `macaly.app`-URL
`get_deployment`	Prüft den neuesten Veröffentlichungsversuch (oder einen bestimmten per `deploymentId`), `liveUrl` und verbundene Domains
`connect_domain`	Verbindet eine eigene Domain oder benennt die Macaly-Subdomain um

Cloud-Aktionen

Cloud-Aktionen sind das, was dein externer Agent über Macaly Cloud tut. Der Plan Kostenlos enthält 100 Cloud-Aktionen pro Monat. Bezahlte Pläne haben kein monatliches Limit für Cloud-Aktionen. Diese Aktionen zählen:

Eine App erstellen oder duplizieren (create_app, duplicate_app)
Dateien schreiben, bearbeiten oder löschen (write_file, edit_file, delete_file)
Befehle ausführen (bash)
Dateien hochladen (upload_file)
Veröffentlichen (publish_app)
Eine Domain verbinden (connect_domain)

Dateien lesen (read_file), Auflisten und Vorschauen (preview_app) sind kostenlos. Der Chat mit Macalys eigenem Agenten in der App verbraucht keine Cloud-Aktionen. Das Kontingent im Plan Kostenlos gilt für den gesamten Workspace, wird am 1. jedes Monats (UTC) zurückgesetzt und wird nicht übertragen. Ist es aufgebraucht, werden weitere zählende Aktionen abgelehnt, mit dem Datum der Zurücksetzung und einem Link zu Abrechnung. Lesezugriffe, bereits live geschaltete Apps und der Chat mit Macaly in der App funktionieren weiter. Abrechnung und Einstellungen → Nutzung & Limits zeigen, wie viele Cloud-Aktionen du bereits genutzt hast. Siehe Nutzung & Limits.

Zusammenspiel mit dem Macaly-Editor

Eine über Macaly Cloud gebaute App ist eine ganz normale Macaly-App. Du kannst sie im Editor öffnen, die Versionshistorie ansehen, zurückrollen oder mit Macalys eigenem Agenten weitermachen.

Jede Änderung wird festgehalten. Zu jedem Schreibvorgang gehört eine kurze Erklärung deines Agenten, die in der Chat-Historie als Karte mit dem Namen des Clients erscheint - so hat Macalys Agent den Kontext, wenn du dort weiterarbeitest. Wenn ein Durchlauf mit mehreren Änderungen endet, fasst seine Karte zusammen, was sich geändert hat.
Du kannst zurückgehen. Klicke auf einer Karte auf Vorherige Version wiederherstellen, um die App auf den Stand nach diesem Durchlauf zurückzusetzen. Dabei wird alles danach aus dem Chat entfernt. Duplizieren kopiert diese Version in ein neues Projekt.
Eine Karte pro Durchlauf. Macaly sieht deine Nachrichten an deinen Agenten nicht, nur seine Tool-Aufrufe. Ein Durchlauf endet, wenn dein Agent dir die App mit preview_app oder publish_app übergibt. Lässt er diesen Aufruf aus, können mehrere deiner Anfragen in einer Karte landen.
Immer nur ein Agent. Während dein externer Agent arbeitet, ist der Chat gesperrt: Macalys Agent startet keinen Durchlauf, und das Eingabefeld zeigt dir, wer die App gerade hat. Die Sperre löst sich einige Minuten nach dem letzten Schreibvorgang von selbst - oder sobald dein Agent dir die Vorschau zeigt.
Die Vorschau wartet auf die fertige App. Builds mitten im Durchlauf werden zurückgehalten, sodass das Vorschaufenster die App zeigt, die du bereits hattest, bis der Durchlauf endet.

Beispiel-Prompts

Bau mir eine App auf Macaly: eine Landingpage für ein
Kaffee-Abo mit Hero, Preisen und E-Mail-Anmeldeformular.

Füge meiner Kaffee-App auf Macaly einen Dark-Mode-Schalter hinzu,
mach einen Typecheck und gib mir den Vorschaulink.

Richte für meine Kaffee-App eine Datenbank ein und speichere
die E-Mail-Anmeldungen darin.

Veröffentliche die Kaffee-App und verbinde die Domain coffee.example.com.

Fehlerbehebung

Das Anmeldefenster erscheint nicht

Stelle sicher, dass dein Client Remote-MCP-Server mit OAuth unterstützt und dass du die vollständige URL inklusive /api/cloud/mcp eingetragen hast.

Ein Schreibvorgang liefert CHAT_CLAIMED_BY_AGENT oder CHAT_CLAIMED_BY_EDITOR

Jemand anderes hat die App: Macalys eigener Agent ist mitten in einem Durchlauf, oder ein anderer externer Editor hat kürzlich geschrieben. Warte und versuche es erneut - die Sperre löst sich einige Minuten nach der letzten Aktivität von selbst.

Der Vorschau-Build schlägt mit einem Upload-Timeout fehl

Die Build-Ausgabe ist zu groß oder enthält zu viele Dateien, meist Medien in public/. get_logs mit log_type: "build" zeigt Anzahl und Größe der Dateien. Verschiebe die Medien mit upload_file aus public/, verwende die zurückgegebenen URLs und lass die Vorschau neu bauen.

Die Vorschau-URL zeigt noch nichts

Vorschauen werden aus einem fertigen Build ausgeliefert. Prüfe previewBuildStatus mit get_project und lies bei einem Fehlschlag get_logs mit log_type: "build".

Eine Aktion wird abgelehnt, weil meine Cloud-Aktionen aufgebraucht sind

Der Plan Kostenlos enthält 100 Cloud-Aktionen pro Monat. Die Ablehnung nennt das Datum der Zurücksetzung (der 1. des Monats, UTC) und enthält einen Link zu Abrechnung. Lesezugriffe und Vorschauen funktionieren weiter. Wechsle zu Starter oder Pro, um das monatliche Limit aufzuheben.

Ein Tool liefert FORBIDDEN

Entweder ist Macaly Cloud im betroffenen Workspace deaktiviert, oder die Aktion braucht eine Planfunktion, die du nicht hast - etwa das Veröffentlichen auf einer eigenen Domain.

Immer noch nicht weiter? Melde dich über den Chat in Macaly oder wirf einen Blick in die FAQ.

​Was du brauchst

​Client verbinden

​Stattdessen einen API-Key verwenden

​Eine App von Anfang bis Ende bauen

​Verfügbare Tools

​Workspaces & Apps

​Code

​Medien

​Funktionen & Diagnose

​Veröffentlichen

​Cloud-Aktionen

​Zusammenspiel mit dem Macaly-Editor

​Beispiel-Prompts

​Fehlerbehebung

Was du brauchst

Client verbinden

Stattdessen einen API-Key verwenden

Eine App von Anfang bis Ende bauen

Verfügbare Tools

Workspaces & Apps

Code

Medien

Funktionen & Diagnose

Veröffentlichen

Cloud-Aktionen

Zusammenspiel mit dem Macaly-Editor

Beispiel-Prompts

Fehlerbehebung