> ## 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.
# Serveur MCP Macaly Cloud
> Laissez Claude, ChatGPT, Cursor, Grok Bot ou Codex écrire le code - Macaly l'exécute, le compile et l'héberge
Macaly Cloud est un serveur [MCP](https://modelcontextprotocol.io) qui fait de Macaly l'infrastructure de votre propre agent de développement IA. Votre agent écrit chaque ligne de code ; Macaly fournit le dépôt git, le sandbox cloud, la base de données et les capacités de la plateforme, la compilation, l'aperçu partageable et l'hébergement en production sur `macaly.app`.
Rien n'est généré sur votre ordinateur et l'agent Macaly ne se lance jamais. L'application vit dans votre workspace Macaly dès le premier fichier : vous pouvez l'ouvrir à tout moment dans l'éditeur Macaly et y poursuivre le travail.
## Ce dont vous avez besoin
Il vous faut un client MCP compatible avec les serveurs distants en Streamable HTTP - Claude (claude.ai, Desktop, Cowork), Claude Code, ChatGPT, Cursor, Grok Bot ou Codex.
## Connectez votre client
Claude, ChatGPT, Cursor et Grok Bot installent Macaly Cloud depuis leurs annuaires officiels. Dans Macaly, **Paramètres → Connexions** contient une carte pour chacun d'eux, avec les mêmes étapes et un lien vers la fiche. Les autres clients ajoutent le serveur à l'adresse :
```
https://www.macaly.com/api/cloud/mcp
```
Dans les deux cas, votre client ouvre une fenêtre de navigateur où vous vous connectez à Macaly et approuvez l'accès (OAuth). Aucune clé à copier.
1. Ouvrez la [fiche Macaly Cloud](https://claude.ai/directory/macaly-cloud) dans l'annuaire des connecteurs Claude. Elle fonctionne sur claude.ai, dans l'application de bureau et sur mobile.
2. Cliquez sur **Connect**.
3. Connectez-vous à Macaly et approuvez l'accès dans la fenêtre qui s'ouvre.
Exécutez dans votre terminal :
```bash theme={null}
claude mcp add macaly-cloud --transport http https://www.macaly.com/api/cloud/mcp
```
Lancez ensuite Claude Code et exécutez `/mcp` pour vous connecter à Macaly.
1. Ouvrez le [plugin Macaly Cloud](https://chatgpt.com/plugins/plugin_asdk_app_6a732e22122c8191ac404137c0514300) dans l'annuaire des plugins ChatGPT. Le même plugin fonctionne dans le navigateur et l'application de bureau.
2. Cliquez sur **Install**.
3. Quand ChatGPT demande à connecter votre compte, connectez-vous à Macaly et approuvez l'accès dans la fenêtre qui s'ouvre.
1. Ouvrez le [plugin Macaly Cloud](https://cursor.com/marketplace/macaly) dans le Cursor Marketplace et ajoutez-le. Vous pouvez aussi exécuter `/add-plugin macaly-code` dans le chat de Cursor.
2. Quand Cursor ouvre votre navigateur, connectez-vous à Macaly et approuvez l'accès.
1. Dans Grok Bot, sélectionnez **Plugins** dans la barre latérale. Dans l'application mobile, touchez votre avatar et sélectionnez **Plugins**.
2. Recherchez **Macaly Cloud**, puis ajoutez-le.
3. Quand Grok Bot vous demande **Authorize**, connectez-vous à Macaly et approuvez l'accès dans votre navigateur.
4. Vérifiez que le plugin apparaît sous **Installed**. Il est alors disponible pour tous les Bots que vous exécutez.
Exécutez dans votre terminal :
```bash theme={null}
codex mcp add macaly-cloud --url https://www.macaly.com/api/cloud/mcp
codex mcp login macaly-cloud
```
### Utiliser une clé API à la place
Vous pouvez vous authentifier avec une [clé API Macaly](/docs/fr/api/authentication) plutôt qu'avec OAuth - pratique pour les agents headless et l'automatisation. Transmettez la clé comme bearer token :
```json theme={null}
{
"mcpServers": {
"macaly-cloud": {
"url": "https://www.macaly.com/api/cloud/mcp",
"headers": {
"Authorization": "Bearer macaly_your_api_key_here"
}
}
}
}
```
Les clés API sont limitées à un seul workspace : les outils qui prennent un `teamId` le déduisent automatiquement.
## Construire une application de bout en bout
Votre agent appelle `create_app` avec un nom. Il reçoit un `chatId` et le briefing du projet. L'application est créée vide : ni prompt de départ, ni build IA.
`write_file` écrit un fichier entier et `edit_file` remplace un texte exact dans un fichier existant : une petite modification d'un gros fichier n'oblige donc pas à renvoyer tout le fichier. Chaque appel à `write_file`, `edit_file` et `delete_file` est un commit git atomique avec sa propre entrée dans l'historique de l'application. La première écriture sur un workspace froid prend 20 à 30 secondes de plus, le temps que le sandbox démarre.
Pour une base de données, des paiements, de l'IA, des médias ou de la recherche, l'agent lit le guide avec `skill_info` et exécute ses commandes avec `bash` : le sandbox contient déjà les identifiants dont les guides ont besoin.
Après la dernière écriture, l'agent exécute `bash ".sandbox/check-errors --strict"` - il repère les erreurs de types, de styles et du serveur en une passe, se termine par un résumé du résultat et sort avec une erreur en cas d'échec de TypeScript ou du CSS. En cas d'échec, `get_logs` renvoie la sortie réelle.
L'aperçu est reconstruit automatiquement quelques secondes après la dernière écriture. Une fois le build réussi, `preview_app` renvoie l'URL en direct à ouvrir ou à partager. Avec `path`, le lien ouvre directement une sous-page, par exemple `/pricing`. L'agent appelle `preview_app` à la fin de chaque tour qui a modifié l'application, même si un lien précédent est encore valide : cet appel indique à Macaly que le tour est terminé.
Quand vous demandez explicitement la mise en ligne, l'agent appelle `publish_app` puis interroge `get_deployment` avec le `deploymentId` renvoyé jusqu'au statut `READY`. Il vous donne ensuite `liveUrl`, l'adresse de la version en ligne. `connect_domain` rattache un domaine personnalisé ou renomme le sous-domaine Macaly.
## Outils disponibles
Macaly Cloud expose 20 outils.
### Workspaces et applications
| Outil | Rôle |
| - | - |
| `list_teams` | Liste les workspaces dans lesquels vous pouvez construire |
| `create_app` | Crée une application vide sur la stack par défaut et renvoie son briefing |
| `list_projects` | Liste les applications d'un workspace, les plus récentes d'abord, avec recherche et pagination. Les applications épinglées apparaissent sur la première page |
| `get_project` | État du projet : build de l'aperçu, URL d'aperçu, statut de la dernière publication et `liveUrl`, briefing, et qui travaille actuellement sur l'application |
| `get_messages` | Lit l'historique du chat de l'application - ce qui a été demandé et déjà construit - avant de faire des modifications |
| `duplicate_app` | Duplique une application avec son historique dans une nouvelle |
### Code
| Outil | Rôle |
| - | - |
| `list_files` | Liste les fichiers sources de l'application |
| `read_file` | Lit un fichier d'après son chemin, ou seulement une plage de lignes avec `startLine` et `endLine` |
| `write_file` | Écrit un fichier entier et le committe immédiatement |
| `edit_file` | Remplace un texte exact dans un fichier existant et le committe immédiatement - jusqu'à 20 remplacements par appel, appliqués tous ou aucun |
| `delete_file` | Supprime un fichier et committe la suppression immédiatement |
| `bash` | Exécute une commande shell dans le sandbox de l'application - installations, CLI, scripts de skills et vérification `.sandbox/check-errors --strict`. Une commande peut compter jusqu'à 32 000 caractères et s'exécuter jusqu'à 240 secondes |
### Médias
| Outil | Rôle |
| - | - |
| `upload_file` | Ajoute un fichier à la bibliothèque de médias de l'application et renvoie son URL publique permanente (jusqu'à 1 Go). Le fichier provient d'une URL publiquement accessible, ou de votre ordinateur ou du sandbox de l'application via une commande `curl` prête à l'emploi |
| `list_media` | Liste les fichiers de la bibliothèque de médias de l'application avec leurs URL publiques et fournit un lien où déposer un fichier local |
Aucun outil n'accepte les octets bruts d'un fichier. Pour un fichier sur votre ordinateur, `upload_file` renvoie une commande `curl` que votre agent exécute dans votre propre shell. Pour un fichier que l'agent a créé dans le sandbox, il exécute la commande dans le sandbox. Si votre agent n'a pas de shell, déposez le fichier dans la bibliothèque de médias avec le lien fourni par `list_media`.
Ne placez pas les images, l'audio et les vidéos générés ou téléchargés dans le dossier `public/` de l'application. Chaque build de l'aperçu téléverse de nouveau `public/` : des fichiers nombreux ou volumineux ralentissent le build et peuvent le faire échouer. Téléversez les médias avec `upload_file` et utilisez l'URL renvoyée.
### Capacités et diagnostic
| Outil | Rôle |
| - | - |
| `skill_info` | Lit le guide d'une capacité de la plateforme, avec des commandes prêtes à l'emploi et les patrons de code à appliquer |
| `get_logs` | Récupère les journaux de build, du serveur de développement ou du déploiement |
| `preview_app` | Renvoie un lien d'aperçu valable trois heures à partager, éventuellement vers une sous-page |
### Publication
| Outil | Rôle |
| - | - |
| `publish_app` | Publie l'application en production sur son URL `macaly.app` |
| `get_deployment` | Consulte la dernière tentative de publication (ou celle désignée par `deploymentId`), `liveUrl` et les domaines connectés |
| `connect_domain` | Connecte un domaine personnalisé ou renomme le sous-domaine Macaly |
## Actions Cloud
Les actions Cloud sont ce que votre agent externe fait via Macaly Cloud. Le forfait Gratuit comprend **100 actions Cloud par mois**. Les forfaits payants n'ont pas de limite mensuelle d'actions Cloud.
Ces actions sont comptabilisées :
* Créer ou dupliquer une app (`create_app`, `duplicate_app`)
* Écrire, modifier ou supprimer des fichiers (`write_file`, `edit_file`, `delete_file`)
* Exécuter des commandes (`bash`)
* Téléverser des fichiers (`upload_file`)
* Publier (`publish_app`)
* Connecter un domaine (`connect_domain`)
La lecture de fichiers (`read_file`), les listes et les aperçus (`preview_app`) sont gratuits. Discuter avec l'agent propre à Macaly dans l'app n'utilise pas d'actions Cloud.
Le quota du forfait Gratuit est partagé par tout le workspace, se réinitialise le 1er de chaque mois (UTC) et n'est pas reporté. Lorsqu'il est épuisé, les actions comptabilisées suivantes sont refusées, avec la date de réinitialisation et un lien vers Facturation. Les lectures, les apps déjà en ligne et la discussion avec Macaly dans l'app continuent de fonctionner. Facturation et **Paramètres → Utilisation et limites** indiquent combien d'actions Cloud vous avez utilisées. Voir [Utilisation et limites](/docs/fr/account/workspaces/usage).
## Travailler en parallèle de l'éditeur Macaly
Une application construite via Macaly Cloud est une application Macaly ordinaire. Vous pouvez l'ouvrir dans l'éditeur, consulter l'historique des versions, revenir en arrière ou continuer avec l'agent Macaly.
* **Chaque modification est consignée.** Chaque écriture porte une courte explication de votre agent, qui apparaît dans l'historique du chat sous forme de carte nommant le client à l'origine du changement - l'agent Macaly dispose ainsi du contexte si vous continuez là-bas. À la fin d'une session comportant plusieurs changements, sa carte résume ce qui a changé.
* **Vous pouvez revenir en arrière.** Cliquez sur **Restaurer la version précédente** sur une carte pour remettre l'app dans l'état où elle était après cette session. Tout ce qui suit est alors supprimé du chat. **Dupliquer** copie cette version dans un nouveau projet.
* **Une carte par tour.** Macaly ne voit pas les messages que vous envoyez à votre agent, seulement ses appels d'outils. Une session se termine quand votre agent vous rend l'application avec `preview_app` ou `publish_app`. S'il omet cet appel, plusieurs de vos demandes peuvent se retrouver dans une seule carte.
* **Un seul agent à la fois.** Pendant que votre agent externe travaille, le chat est verrouillé : l'agent Macaly ne démarre pas de tour et la zone de saisie indique qui détient l'application. Le verrou se libère quelques minutes après la dernière écriture, ou dès que votre agent vous montre l'aperçu.
* **L'aperçu attend l'application terminée.** Les reconstructions en cours de session sont retenues : le panneau d'aperçu continue d'afficher l'application que vous aviez déjà jusqu'à la fin de la session.
## Exemples de prompts
```
Construis-moi une application sur Macaly : une landing page pour un
abonnement café, avec hero, tarifs et formulaire d'inscription e-mail.
```
```
Ajoute un sélecteur de mode sombre à mon application café sur Macaly,
vérifie les types et donne-moi le lien d'aperçu.
```
```
Mets en place une base de données pour mon application café et
enregistres-y les inscriptions par e-mail.
```
```
Publie l'application café et connecte le domaine coffee.example.com.
```
## Dépannage
Vérifiez que votre client prend en charge les serveurs MCP distants avec OAuth et que vous avez saisi l'URL complète, y compris le chemin `/api/cloud/mcp`.
Quelqu'un d'autre détient l'application : l'agent Macaly est en plein tour, ou un autre éditeur externe y a écrit récemment. Patientez et réessayez - le verrou se libère quelques minutes après la dernière activité.
La sortie du build est trop volumineuse ou contient trop de fichiers, généralement des médias dans `public/`. `get_logs` avec `log_type: "build"` affiche le nombre de fichiers et leur taille. Sortez les médias de `public/` avec `upload_file`, utilisez les URL renvoyées et laissez l'aperçu se reconstruire.
Les aperçus sont servis depuis un build terminé. Vérifiez `previewBuildStatus` avec `get_project` et, en cas d'échec, lisez `get_logs` avec `log_type: "build"`.
Le forfait Gratuit comprend 100 actions Cloud par mois. Le message de refus indique la date de réinitialisation (le 1er du mois, UTC) et un lien vers Facturation. Les lectures et les aperçus continuent de fonctionner. Passez à Starter ou Pro pour supprimer la limite mensuelle.
Soit Macaly Cloud est désactivé pour le workspace concerné, soit l'action nécessite une fonctionnalité que votre forfait n'inclut pas - la publication sur un domaine personnalisé, par exemple.
Toujours bloqué ? Contactez-nous via le chat dans Macaly ou consultez la [FAQ](/docs/fr/welcome/faq).
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.