> ## Documentation Index > Fetch the complete documentation index at: https://docs.base44.com/llms.txt > Use this file to discover all available pages before exploring further. # Développer une application Base44 à distance via MCP > Adapté de base44-dev/apper PR #11608 Cette page fait partie d'une compétence d'agent de code IA et est écrite pour les agents, pas pour les humains. Pour la documentation Base44 lisible par un humain, consultez la [documentation développeur](/developers). # Développer une application Base44 à distance via MCP Connectez votre propre agent de code au sandbox d'une application Base44 et développez-y directement — exécutez des commandes, lisez et modifiez des fichiers, faites du grep, listez les répertoires — pendant que Base44 fournit le sandbox et que vous fournissez l'agent et le LLM. Cela fonctionne avec tout client compatible MCP. Les exemples utilisent Claude Code. > **Démarrage le plus simple :** dans l'éditeur d'application Base44, cliquez sur **Send to Coding Agent**. Pour un agent local, cela vous donne un prompt prêt à coller (qui récupère un README et pilote le sandbox via MCP ou le CLI `base44 sandbox` — Section 10) ; pour le web, cela donne un prompt à coller dans un chat **claude.ai** (avec le connecteur MCP Base44) plus un bouton **Open Claude**. Le bouton est la surface de découverte — le reste de cette compétence est la référence. > **Deux transports :** les agents web utilisent **claude.ai** avec le **connecteur MCP** Base44 (sections 1-9) — notez qu'il s'agit du chat claude.ai régulier, *pas* de Claude Code sur le web (`claude.ai/code`), qui s'exécute dans son propre sandbox basé sur un repo. Un agent local peut se connecter à ce même serveur MCP, ou piloter le sandbox avec le CLI **`base44 sandbox`** (un token CLI Base44, Section 10) — mêmes outils, même comportement, mêmes codes d'erreur ; le CLI les expose simplement sous des noms de commande plus courts (`sandbox read`, `sandbox ls`, …). *** ## 1. Se connecter au serveur MCP L'endpoint MCP Base44 est : ``` https://app.base44.com/mcp ``` Enregistrez-le auprès de Claude Code (exécutez depuis n'importe quel dossier) : ```bash theme={null} claude mcp add --transport http base44 https://app.base44.com/mcp ``` Ajoutez `--scope user` si vous voulez qu'il soit disponible dans chaque projet plutôt que seulement dans le dossier courant. `claude mcp add` n'écrit que la config — il n'authentifie pas encore. ## 2. S'authentifier Démarrez Claude Code et ouvrez le menu MCP : ```bash theme={null} claude ``` puis, dans Claude Code : ``` /mcp ``` Sélectionnez **base44** → **Authenticate**. Un navigateur s'ouvre pour le flux OAuth Base44 (PKCE) — connectez-vous et approuvez. En cas de succès, `/mcp` affiche **base44** comme connecté et liste ses outils. **Les clients CLI purs / headless** qui ne peuvent pas ouvrir de navigateur utilisent plutôt le flux OAuth device (`/oauth/device/code`) — demandez un code, approuvez-le dans un navigateur sur un autre appareil, et le client reçoit le token. ### Scopes | Outils | Scope requis | | ------------------------------------------------------------------------------------------------ | -------------------------------- | | `read_file`, `grep`, `list_directory`, `get_app_preview_url`, `get_app_status`, `list_user_apps` | `apps:read` (accordé par défaut) | | `write_file`, `edit_file`, `run_command`, `create_checkpoint` | `sandbox:write` | `sandbox:write` n'est **pas** accordé par défaut — les mutations shell et fichiers l'exigent explicitement. Si les outils de lecture fonctionnent mais que les outils de mutation retournent `NOT_AUTHORIZED`, votre token n'a pas `sandbox:write` ; reconnectez-vous et accordez l'accès sandbox (le flux device peut le demander explicitement). *** ## 3. Choisir l'application et s'orienter Chaque outil prend un `appId` requis. Trouvez vos applications avec `list_user_apps`, puis épinglez l'id dans vos requêtes pour que l'agent le passe à chaque appel. Commencez en **lecture seule** pour construire un modèle mental avant tout changement : ``` Using the base44 tools on appId : 1. list_directory on the app root (recursive, depth 2) 2. read_file src/App.jsx and src/pages.config.js 3. grep for the component I want to change Summarize the structure before editing. ``` > **Démarrage à froid :** si l'application n'a pas de sandbox en cours d'exécution, le premier appel d'outil en fait apparaître un de manière transparente depuis votre dernier commit — cela prend juste un peu plus longtemps. Les appels suivants sont rapides. > **Noms CLI :** via le CLI `base44 sandbox` (Section 10), ces outils de lecture sont `list_directory` → `sandbox ls`, `read_file` → `sandbox read`, et `grep` → `sandbox grep`. *** ## 4. Effectuer des changements * **`edit_file`** (`sandbox edit` dans le CLI) — préféré pour modifier des fichiers existants. Fournissez des éditions exactes `old_text`→`new_text`. Chaque `old_text` doit être unique dans le fichier sauf si vous définissez `replace_all`. Toutes les éditions d'un appel s'appliquent atomiquement (tout ou rien) et vous récupérez un diff unifié. Passez `dry_run: true` pour prévisualiser le diff sans écrire. * **`write_file`** (`sandbox write` dans le CLI) — pour créer de nouveaux fichiers. Pour écraser un fichier existant, vous devez passer `overwrite: true` (il n'écrase jamais silencieusement). * **`run_command`** (`sandbox run` dans le CLI) — exécute n'importe quelle commande bash dans le sandbox (build, install, scaffolding, codemods). Le répertoire de travail par défaut est la racine de l'application ; `cd` ne persiste pas entre les appels, utilisez donc le paramètre `cwd` ou chaînez les commandes (`cd sub && cmd`). Le timeout par défaut est 120s (max 600s) ; la sortie est plafonnée à \~1 Mo. * **`create_checkpoint`** (`sandbox checkpoint` dans le CLI) — enregistre un point de restauration nommé vers lequel l'utilisateur peut revenir plus tard. Prend un `name` facultatif (message/titre ; auto-généré si omis). Les changements en attente sont **flushés et commités d'abord** pour que le point de contrôle s'ancre sur votre dernier code ; il retourne ensuite l'id du point de contrôle, son nom et son hash de commit git. Utilisez-le pour marquer un état connu-bon avant ou après un bloc d'éditions. (Si un auto-commit récent ne peut pas encore être confirmé durable, il refuse avec le `COMMIT_FLUSH_PENDING` retryable plutôt que de marquer un état obsolète — réessayez rapidement.) Exemple : ``` On appId , use edit_file to change the homepage heading in src/pages/Home.jsx from "Welcome" to "Welcome back". Show me the diff first with dry_run, then apply it. ``` *** ## 5. Prévisualiser et vérifier (la boucle edit → check) Il n'y a pas d'outil de streaming de logs en direct, mais vous pouvez fermer la boucle de feedback : * **Voir en direct :** `get_app_preview_url` fait apparaître le serveur de dev et retourne l'URL d'aperçu. Vite HMR reflète vos éditions à mesure que vous les faites. * **Statut du build :** `get_app_status` retourne `ready` / `processing` / `error`. * **Faire apparaître les erreurs de build/type/lint à la demande** avec `run_command` : ```bash theme={null} npm run build # bundler/compile errors npx tsc --noEmit # type errors npm run lint # lint errors ``` * **Lire les logs du dev-server (Vite)** — le serveur de dev géré écrit dans `/tmp/vite.log`. Faites-en un tail via `run_command` pour voir les erreurs HMR/compilation : ```bash theme={null} tail -c 32000 /tmp/vite.log ``` (C'est en dehors de l'arbre de l'application, donc uniquement accessible via `run_command`, pas les outils de fichiers — et nécessite donc `sandbox:write`.) Une boucle solide : `edit_file` → `npm run build` (ou tail `/tmp/vite.log`) → corriger les erreurs → `get_app_preview_url` pour visualiser. > **Les erreurs runtime navigateur** (un composant qui compile mais lève à l'affichage, un appel API client qui échoue) apparaissent dans la console du navigateur, pas dans `/tmp/vite.log`. Ouvrez l'URL d'aperçu pour les attraper. *** ## 6. Comment vos changements persistent Vous n'avez pas besoin de « sauvegarder ». Chaque appel mutant planifie un **auto-commit debouncé** (\~5 secondes) : le changement est commité et poussé vers le stockage de code de Base44, il : * survit à la mort du sandbox (le sandbox est recréé depuis le dernier commit), * apparaît dans les onglets Library/Data du builder, * garde les déploiements de fonctions backend cohérents, et * est inclus lors de la publication de l'application. Implications pratiques : * Il y a une petite fenêtre de perte (\~5s) — ne tuez pas la session immédiatement après la dernière édition ; laissez-lui un moment pour committer. * Les éditions sur les entités, agents, workflows, fonctions backend et routage de pages sont synchronisées dans Base44 automatiquement après le commit. Les éditions ordinaires de pages/composants/CSS vivent dans git et n'ont besoin de rien de plus. *** ## 7. Concurrence : vous vs. le builder Base44 Vous et le builder Base44 intégré ne pouvez pas modifier la même application en même temps : * **Pendant que vous utilisez activement les outils du sandbox**, le chat du builder Base44 est bloqué (« An external agent is currently working on this app »). Votre session est implicite — les appels d'outil récents *sont* la session ; elle se termine après une brève période d'inactivité (\~10 min). * **Si le builder Base44 est en cours de build**, vos outils mutants retournent `BUILDER_BUSY`. Interrogez `get_app_status` et réessayez une fois qu'il est `ready`. Les outils en lecture seule fonctionnent toujours pendant un build. *** ## 8. Garde-fous et limites * **Les chemins sont confinés à l'application.** Les outils de fichiers n'opèrent que dans le répertoire de l'application ; les traversées/chemins absolus sont rejetés (`PATH_OUTSIDE_SANDBOX`). * **`.agents/` est interdit aux outils de fichiers** (`PROTECTED_PATH`) — il contient la config et les secrets gérés par l'agent (`.agents/.env`). N'essayez pas de le lire ou de le modifier via les outils de fichiers. * **Des limites de taux** s'appliquent par application : lectures \~120/min, mutations \~60/min, commandes \~30/min. Si vous atteignez `RATE_LIMITED`, ralentissez. * **`delete_file` n'est pas un outil dédié** — supprimez via `run_command rm`. ### Codes d'erreur que vous pouvez voir `NOT_AUTHORIZED` (scope/flag manquant) · `APP_NOT_FOUND` (mauvais id ou pas d'accès) · `PATH_OUTSIDE_SANDBOX` · `PROTECTED_PATH` · `NOT_FOUND` · `BINARY_FILE` · `EDIT_TEXT_NOT_FOUND` · `EDIT_TEXT_NOT_UNIQUE` (rendez `old_text` unique ou utilisez `replace_all`) · `OVERWRITE_NOT_ALLOWED` (passez `overwrite: true`) · `TIMEOUT` · `OUTPUT_TRUNCATED` · `BUILDER_BUSY` · `COMMIT_FLUSH_PENDING` (un auto-commit en attente n'est pas encore durable ; réessayez rapidement — par exemple sur `create_checkpoint`) · `RATE_LIMITED` · `BACKEND_ERROR`. Les messages sont écrits pour que l'agent puisse s'auto-corriger — lisez-les et ajustez. *** ## 9. Conseils et astuces * **Lisez avant d'écrire.** Un passage rapide de `list_directory` + `read_file` (ou `grep`) coûte peu et améliore drastiquement la précision des éditions. * **Utilisez `dry_run` sur `edit_file`** pour confirmer le diff avant de vous engager sur un changement, surtout pour les appels multi-éditions. * **Préférez `edit_file` à `write_file`** pour les fichiers existants — les éditions chirurgicales évitent l'écrasement et produisent un diff revisable. * **Lisez des plages de lignes** avec `offset`/`limit` de `read_file` sur les gros fichiers plutôt que de tout tirer dans le contexte. * **Quand quelque chose « semble cassé », tailer `/tmp/vite.log`** avant de deviner — il nomme généralement le fichier et la ligne exacts. * **Laissez-le committer.** Pausez quelques secondes après votre édition finale pour que l'auto-commit atterrisse avant de vous déconnecter ou de publier. * **Points de contrôle sur les états connus-bons.** Utilisez `create_checkpoint` (`sandbox checkpoint`) pour marquer un point de restauration avant ou après un bloc d'éditions risquées — il flushe d'abord les changements en attente, l'utilisateur peut donc toujours revenir à ce point. * **Un agent à la fois.** La fonctionnalité est conçue pour un seul agent externe par application ; ne lancez pas de sessions parallèles contre la même application. *** ## 10. Agents locaux via le CLI `base44 sandbox` Si votre agent s'exécute sur votre machine, il peut piloter le même sandbox via le CLI Base44 au lieu de MCP, en s'authentifiant avec le CLI Base44 au lieu d'OAuth. Mêmes outils, même comportement, mêmes codes d'erreur (Section 8) — seuls la surface et l'authentification diffèrent. **Authentification.** Connectez-vous avec le CLI Base44 (`base44 login`) — le même identifiant utilisé pour `base44 functions deploy`. Comme les commandes sans projet `base44 connectors`, les sous-commandes sandbox résolvent l'id d'application depuis `--app-id`, puis `BASE44_APP_ID`, puis un `.app.jsonc` local ; aucun `config.jsonc` n'est requis. **Noms de commandes.** Le CLI expose chaque outil du sandbox sous un nom plus court : | Outil MCP | Commande CLI | | ------------------- | --------------------------- | | `list_directory` | `base44 sandbox ls` | | `read_file` | `base44 sandbox read` | | `write_file` | `base44 sandbox write` | | `edit_file` | `base44 sandbox edit` | | `run_command` | `base44 sandbox run` | | `grep` | `base44 sandbox grep` | | `create_checkpoint` | `base44 sandbox checkpoint` | ```bash theme={null} npx base44 sandbox read --app-id src/App.jsx ``` `base44 sandbox checkpoint` prend un `--name` facultatif (message/titre) et enregistre un point de restauration : ```bash theme={null} npx base44 sandbox checkpoint --app-id --name "before refactor" ``` **Passez à un agent la référence complète** pour une application précise (instructions, publique, sans authentification pour la récupérer) : ``` https://app.base44.com/api/sandbox//local-agent/readme.md ``` (L'équivalent cloud/MCP est `.../api/sandbox//claude-web/readme.md`.) Tout le reste de cette compétence — la boucle edit→preview→verify (Section 5), la persistance (Section 6), la concurrence (Section 7) et les garde-fous (Section 8) — s'applique à l'identique ; seuls la surface et l'authentification diffèrent. *** ## 11. Connecteurs (intégrations OAuth) Au-delà des outils fichiers/shell du sandbox, le serveur MCP Base44 expose deux outils pour gérer un connecteur OAuth tiers (Google Calendar, Gmail, Slack, …) sur une application. Ils ne touchent pas au système de fichiers du sandbox — ils opèrent directement sur l'état des connecteurs de l'application. Les deux prennent `appId`. | Outil | Scope | Objectif | | ------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `list_connectors` | `apps:read` | Liste les connecteurs de l'application. Sans `integrationTypes`, retourne le catalogue complet (nom, description, connecté ?, et — si connecté — statut et scopes accordés). Passez `integrationTypes` pour le détail sur des connecteurs précis. | | `initiate_connector_connection` | `apps:write` | Connecter (ou re-scope) un connecteur. Entrées : `appId`, `integrationType`, `scopes`, `connectionConfig` facultatif. | Deux sémantiques à maîtriser : * **Scopes déclaratifs (remplacer, pas fusionner).** `initiate_connector_connection` définit le connecteur sur **exactement** les `scopes` que vous passez. Les scopes omis sont retirés et l'utilisateur est réinvité à consentir. **Appelez toujours `list_connectors` d'abord**, puis passez l'ensemble complet souhaité (les scopes existants à conserver **plus** les nouveaux). * **OAuth nécessite un humain.** L'outil retourne soit `already_authorized: true` (rien à faire), soit une `redirect_url` que l'**utilisateur** doit ouvrir dans un navigateur pour se connecter et consentir — vous ne pouvez pas le faire vous-même. Après qu'il ait terminé, appelez à nouveau `list_connectors` pour vérifier et lire les scopes **accordés** (un fournisseur peut accorder moins que ce qui a été demandé). Ces outils n'ont besoin que de `apps:read` / `apps:write` — **pas** de `sandbox:write`. Via la surface CLI (Section 10), l'équivalent est les commandes sans projet `base44 connectors` (`list-available`, `initiate --integration-type --scopes --app-id `, `pull`), qui affichent la même URL d'autorisation. Cette page a été traduite à l'aide de l'IA. Pour les informations les plus précises et à jour, consultez la [version anglaise](/).