> ## Documentation Index
> Fetch the complete documentation index at: https://www.macaly.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Macaly Cloud MCP-Server
> Claude, ChatGPT, Cursor, Grok Bot oder Codex schreiben den Code - Macaly führt ihn aus, baut und hostet ihn
Macaly Cloud ist ein [MCP](https://modelcontextprotocol.io)-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.
1. Öffne den [Macaly-Cloud-Eintrag](https://claude.ai/directory/macaly-cloud) im Claude-Connector-Verzeichnis. Er funktioniert in claude.ai, in der Desktop-App und auf dem Handy.
2. Klicke auf **Connect**.
3. Melde dich bei Macaly an und gib den Zugriff im Fenster frei, das sich öffnet.
Führe im Terminal aus:
```bash theme={null}
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.
1. Öffne das [Macaly-Cloud-Plugin](https://chatgpt.com/plugins/plugin_asdk_app_6a732e22122c8191ac404137c0514300) im ChatGPT-Plugin-Verzeichnis. Dasselbe Plugin funktioniert im Browser und in der Desktop-App.
2. Klicke auf **Install**.
3. Wenn ChatGPT dein Konto verbinden möchte, melde dich bei Macaly an und gib den Zugriff im Fenster frei, das sich öffnet.
1. Öffne das [Macaly-Cloud-Plugin](https://cursor.com/marketplace/macaly) im Cursor Marketplace und füge es hinzu. Du kannst auch `/add-plugin macaly-code` im Cursor-Chat ausführen.
2. Wenn Cursor deinen Browser öffnet, melde dich bei Macaly an und gib den Zugriff frei.
1. Wähle in Grok Bot in der Seitenleiste **Plugins**. Tippe in der mobilen App auf deinen Avatar und wähle **Plugins**.
2. Suche nach **Macaly Cloud** und füge es hinzu.
3. Wenn Grok Bot dich zu **Authorize** auffordert, melde dich bei Macaly an und gib den Zugriff im Browser frei.
4. Prüfe, ob das Plugin unter **Installed** erscheint. Danach steht es jedem Bot zur Verfügung, den du ausführst.
Führe im Terminal aus:
```bash theme={null}
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](/docs/de/api/authentication) authentifizieren - praktisch für Headless-Agenten und Automatisierung. Übergib den Key als Bearer-Token:
```json theme={null}
{
"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
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.
`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.
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.
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.
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.
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](/docs/de/account/workspaces/usage).
## 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
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.
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.
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.
Vorschauen werden aus einem fertigen Build ausgeliefert. Prüfe `previewBuildStatus` mit `get_project` und lies bei einem Fehlschlag `get_logs` mit `log_type: "build"`.
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.
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](/docs/de/welcome/faq).
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.