Serveur MCP Macaly Cloud - Macaly Documentation

Macaly Cloud est un serveur MCP 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.

Ouvrez la fiche Macaly Cloud dans l’annuaire des connecteurs Claude. Elle fonctionne sur claude.ai, dans l’application de bureau et sur mobile.
Cliquez sur Connect.
Connectez-vous à Macaly et approuvez l’accès dans la fenêtre qui s’ouvre.

Exécutez dans votre terminal :

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.

Ouvrez le plugin Macaly Cloud dans le Cursor Marketplace et ajoutez-le. Vous pouvez aussi exécuter /add-plugin macaly-code dans le chat de Cursor.
Quand Cursor ouvre votre navigateur, connectez-vous à Macaly et approuvez l’accès.

Exécutez dans votre terminal :

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 plutôt qu’avec OAuth - pratique pour les agents headless et l’automatisation. Transmettez la clé comme bearer token :

{
  "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

Créer l'application

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.

Écrire le code

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.

Ajouter des capacités de la plateforme

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.

Vérifier les types

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.

Aperçu

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é.

Publier

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.

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

La fenêtre de connexion n'apparaît pas

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.

Une écriture renvoie CHAT_CLAIMED_BY_AGENT ou CHAT_CLAIMED_BY_EDITOR

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é.

Le build de l'aperçu échoue avec un délai d'expiration du téléversement

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.

L'URL d'aperçu n'affiche encore rien

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".

Une action est refusée parce que mes actions Cloud sont épuisées

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.

Un outil renvoie FORBIDDEN

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.

​Ce dont vous avez besoin

​Connectez votre client

​Utiliser une clé API à la place

​Construire une application de bout en bout

​Outils disponibles

​Workspaces et applications

​Code

​Médias

​Capacités et diagnostic

​Publication

​Actions Cloud

​Travailler en parallèle de l’éditeur Macaly

​Exemples de prompts

​Dépannage

Ce dont vous avez besoin

Connectez votre client

Utiliser une clé API à la place

Construire une application de bout en bout

Outils disponibles

Workspaces et applications

Code

Médias

Capacités et diagnostic

Publication

Actions Cloud

Travailler en parallèle de l’éditeur Macaly

Exemples de prompts

Dépannage