> ## 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. # Eine Base44-App remote über MCP entwickeln > Vendored from base44-dev/apper PR #11608 Diese Seite ist Teil eines KI-Coding-Agent-Skills und für Agenten geschrieben, nicht für Menschen. Für die menschenlesbare Base44-Dokumentation siehe die [Entwicklerdokumentation](/developers). # Eine Base44-App remote über MCP entwickeln Verbinde deinen eigenen Coding-Agenten mit der Sandbox einer Base44-App und entwickle darin direkt — führe Befehle aus, lese und bearbeite Dateien, grepe, liste Verzeichnisse — während Base44 die Sandbox liefert und du den Agenten und das LLM. Das funktioniert mit jedem MCP-fähigen Client. Die Beispiele nutzen Claude Code. > **Einfachster Start:** Klicke im Base44-App-Editor auf **Send to Coding Agent**. Für einen lokalen Agenten > bekommst du einen einfüge-fertigen Prompt (der ein README abruft und die Sandbox über MCP oder > die `base44 sandbox`-CLI treibt — Abschnitt 10); > für das Web bekommst du einen Prompt, den du in einen **claude.ai**-Chat einfügst (mit dem Base44-MCP-Connector) > plus einen **Open Claude**-Button. Der Button ist die Entdeckungsfläche — der Rest dieses Skills ist > die Referenz. > **Zwei Transporte:** Web-Agenten nutzen **claude.ai** mit dem Base44-**MCP-Connector** (Abschnitte > 1–9) — beachte, dass das der reguläre claude.ai-Chat ist, *nicht* Claude Code im Web (`claude.ai/code`), > das in seiner eigenen Repo-basierten Sandbox läuft. Ein lokaler Agent kann denselben MCP-Server verbinden oder > die Sandbox mit der **`base44 sandbox`-CLI** treiben (ein Base44-CLI-Token, Abschnitt 10) — gleiche Tools, > gleiches Verhalten, gleiche Fehlercodes; die CLI stellt sie nur unter kürzeren Befehlsnamen bereit > (`sandbox read`, `sandbox ls`, …). *** ## 1. Den MCP-Server verbinden Der Base44-MCP-Endpunkt ist: ``` https://app.base44.com/mcp ``` Registriere ihn bei Claude Code (aus jedem Ordner): ```bash theme={null} claude mcp add --transport http base44 https://app.base44.com/mcp ``` Füge `--scope user` hinzu, wenn du ihn in jedem Projekt statt nur im aktuellen Ordner nutzen möchtest. `claude mcp add` schreibt nur die Konfiguration — es authentifiziert noch nicht. ## 2. Authentifizieren Starte Claude Code und öffne das MCP-Menü: ```bash theme={null} claude ``` dann innerhalb von Claude Code: ``` /mcp ``` Wähle **base44** → **Authenticate**. Ein Browser öffnet den Base44-OAuth-Flow (PKCE) — melde dich an und bestätige. Bei Erfolg zeigt `/mcp` **base44** als verbunden und listet die Tools. **Reine CLI/Headless-Clients**, die keinen Browser öffnen können, nutzen stattdessen den OAuth-Device-Flow (`/oauth/device/code`) — Code anfordern, in einem Browser auf einem anderen Gerät bestätigen, und der Client erhält den Token. ### Scopes | Tools | Erforderlicher Scope | | ------------------------------------------------------------------------------------------------ | ----------------------------------- | | `read_file`, `grep`, `list_directory`, `get_app_preview_url`, `get_app_status`, `list_user_apps` | `apps:read` (standardmäßig gewährt) | | `write_file`, `edit_file`, `run_command`, `create_checkpoint` | `sandbox:write` | `sandbox:write` wird **nicht** standardmäßig gewährt — Shell und Dateiänderungen erfordern es ausdrücklich. Wenn die Read-Tools funktionieren, die mutierenden aber `NOT_AUTHORIZED` zurückgeben, fehlt deinem Token `sandbox:write`; verbinde neu und gewähre Sandbox-Zugriff (der Device-Flow kann ihn ausdrücklich anfordern). *** ## 3. Die App wählen und sich orientieren Jedes Tool benötigt ein erforderliches `appId`. Finde deine Apps mit `list_user_apps` und fixe die ID in deinen Anfragen, damit der Agent sie bei jedem Aufruf mitgibt. Beginne **schreibgeschützt**, um ein mentales Modell aufzubauen, bevor du etwas änderst: ``` 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. ``` > **Cold Start:** Wenn die App keine laufende Sandbox hat, holt der erste Tool-Aufruf transparent eine von deinem letzten Commit hoch — es dauert nur etwas länger. Nachfolgende Aufrufe sind schnell. > **CLI-Namen:** Über die `base44 sandbox`-CLI (Abschnitt 10) sind diese Read-Tools: > `list_directory` → `sandbox ls`, `read_file` → `sandbox read` und > `grep` → `sandbox grep`. *** ## 4. Änderungen vornehmen * **`edit_file`** (`sandbox edit` in der CLI) — bevorzugt für Änderungen an bestehenden Dateien. Gib exakte `old_text`→`new_text`-Edits an. Jedes `old_text` muss in der Datei eindeutig sein, außer du setzt `replace_all`. Alle Edits in einem Aufruf werden atomar angewendet (alles oder nichts) und du erhältst ein Unified Diff zurück. Übergib `dry_run: true`, um das Diff ohne Schreiben zu sehen. * **`write_file`** (`sandbox write` in der CLI) — zum Erstellen neuer Dateien. Um eine bestehende Datei zu überschreiben, musst du `overwrite: true` übergeben (sie wird nie stillschweigend überschrieben). * **`run_command`** (`sandbox run` in der CLI) — führt einen beliebigen Bash-Befehl in der Sandbox aus (Build, Install, Scaffolding, Codemods). Das Arbeitsverzeichnis ist standardmäßig das App-Root; `cd` bleibt nicht über Aufrufe hinweg bestehen, verwende also den Parameter `cwd` oder verkette Befehle (`cd sub && cmd`). Timeout ist standardmäßig 120s (max. 600s); Ausgabe ist auf \~1 MB begrenzt. * **`create_checkpoint`** (`sandbox checkpoint` in der CLI) — speichere einen benannten Wiederherstellungspunkt, zu dem der Nutzer später zurückrollen kann. Nimmt einen optionalen `name` (Nachricht/Titel; automatisch generiert, wenn weggelassen). Alle ausstehenden Änderungen werden **zuerst geflusht und commitet**, damit der Checkpoint an deinem neuesten Code hängt; danach gibt er die Checkpoint-ID, den Namen und den Git-Commit-Hash zurück. Nutze ihn, um vor oder nach einem Block von Edits einen bekannt-guten Stand zu markieren. (Wenn ein kürzlicher Auto-Commit noch nicht als dauerhaft bestätigt werden kann, weist er ab mit dem wiederholbaren `COMMIT_FLUSH_PENDING` anstatt einen veralteten Stand als Checkpoint zu speichern — bald erneut versuchen.) Beispiel: ``` 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. Preview und Verifizierung (die Edit → Check-Schleife) Es gibt kein Live-Log-Streaming-Tool, aber du kannst die Feedback-Schleife schließen: * **Live sehen:** `get_app_preview_url` bringt den Dev-Server hoch und gibt die Preview-URL zurück. Vite HMR spiegelt deine Edits wider. * **Build-Status:** `get_app_status` gibt `ready` / `processing` / `error` zurück. * **Build-/Typ-/Lint-Fehler auf Abruf** mit `run_command`: ```bash theme={null} npm run build # bundler/compile errors npx tsc --noEmit # type errors npm run lint # lint errors ``` * **Lies die Dev-Server (Vite)-Logs** — der verwaltete Dev-Server schreibt in `/tmp/vite.log`. Verfolge sie mit `run_command`, um HMR-/Kompilierfehler zu sehen: ```bash theme={null} tail -c 32000 /tmp/vite.log ``` (Das liegt außerhalb des App-Baums, ist also nur über `run_command` erreichbar, nicht die Datei-Tools — und benötigt daher `sandbox:write`.) Eine solide Schleife: `edit_file` → `npm run build` (oder tail `/tmp/vite.log`) → Fehler beheben → `get_app_preview_url`, um es anzusehen. > **Browser-Runtime-Fehler** (eine Komponente, die kompiliert, aber beim Rendern wirft, ein fehlschlagender Client-API-Aufruf) erscheinen in der Browserkonsole, nicht in `/tmp/vite.log`. Öffne die Preview-URL, um diese zu erwischen. *** ## 6. Wie deine Änderungen persistiert werden Du musst nichts "speichern". Jeder mutierende Aufruf plant einen **entprellten Auto-Commit** (\~5 Sekunden): Die Änderung wird commitet und zu Base44s Codespeicher gepusht, sodass sie: * den Sandbox-Tod überlebt (die Sandbox wird aus dem letzten Commit neu erstellt), * in den Library-/Data-Tabs des Builders erscheint, * Backend-Funktions-Deploys konsistent hält und * beim Veröffentlichen der App enthalten ist. Praktische Konsequenzen: * Es gibt ein kleines Verlustfenster (\~5s) — töte die Sitzung nicht sofort nach dem letzten Edit; gib ihr einen Moment, um zu commiten. * Änderungen an Entitäten, Agenten, Workflows, Backend-Funktionen und Seiten-Routing werden nach dem Commit automatisch in Base44 synchronisiert. Reine Seiten-/Komponenten-/CSS-Edits liegen in Git und brauchen nichts extra. *** ## 7. Konkurrenz: Du vs. der Base44-Builder Du und der In-App-Base44-Builder können nicht gleichzeitig dieselbe App mutieren: * **Solange du aktiv die Sandbox-Tools nutzt**, ist der Base44-Builder-Chat blockiert ("An external agent is currently working on this app"). Deine Sitzung ist implizit — jüngste Tool-Aufrufe *sind* die Sitzung; sie endet nach kurzer Untätigkeit (\~10 min). * **Wenn der Base44-Builder mitten im Build ist**, geben deine mutierenden Tools `BUILDER_BUSY` zurück. Frage `get_app_status` ab und versuche es erneut, sobald er `ready` ist. Nur-Lese-Tools funktionieren während eines Builds weiter. *** ## 8. Guardrails & Limits * **Pfade sind auf die App beschränkt.** Datei-Tools operieren nur im App-Verzeichnis; Traversal-/absolute Pfade werden abgelehnt (`PATH_OUTSIDE_SANDBOX`). * **`.agents/` ist für Datei-Tools tabu** (`PROTECTED_PATH`) — es enthält agentenverwaltete Konfiguration und Secrets (`.agents/.env`). Versuche nicht, es über die Datei-Tools zu lesen oder zu bearbeiten. * **Rate-Limits** gelten pro App: Reads \~120/min, Mutationen \~60/min, Befehle \~30/min. Wenn du `RATE_LIMITED` siehst, mache langsamer. * **`delete_file` ist kein eigenes Tool** — lösche über `run_command rm`. ### Fehlercodes, die du sehen kannst `NOT_AUTHORIZED` (fehlender Scope/Flag) · `APP_NOT_FOUND` (falsche ID oder kein Zugriff) · `PATH_OUTSIDE_SANDBOX` · `PROTECTED_PATH` · `NOT_FOUND` · `BINARY_FILE` · `EDIT_TEXT_NOT_FOUND` · `EDIT_TEXT_NOT_UNIQUE` (mache `old_text` eindeutig oder verwende `replace_all`) · `OVERWRITE_NOT_ALLOWED` (übergib `overwrite: true`) · `TIMEOUT` · `OUTPUT_TRUNCATED` · `BUILDER_BUSY` · `COMMIT_FLUSH_PENDING` (ein ausstehender Auto-Commit ist noch nicht dauerhaft; bald erneut versuchen — z. B. bei `create_checkpoint`) · `RATE_LIMITED` · `BACKEND_ERROR`. Meldungen sind so verfasst, dass der Agent sich selbst korrigieren kann — lies sie und passe an. *** ## 9. Tipps & Tricks * **Lies vor dem Schreiben.** Ein schneller `list_directory` + `read_file` (oder `grep`)-Durchgang kostet wenig und verbessert die Edit-Genauigkeit drastisch. * **Verwende `dry_run` bei `edit_file`**, um das Diff vor dem endgültigen Commit zu prüfen, besonders bei Multi-Edit-Aufrufen. * **Bevorzuge `edit_file` gegenüber `write_file`** bei bestehenden Dateien — chirurgische Edits vermeiden das Überschreiben und erzeugen ein überprüfbares Diff. * **Lies Zeilenbereiche** mit `read_file`s `offset`/`limit` bei großen Dateien, statt alles in den Kontext zu ziehen. * **Wenn etwas "kaputt aussieht", tail `/tmp/vite.log`** vor dem Raten — sie nennt normalerweise Datei und Zeile. * **Lass es commiten.** Halte nach dem letzten Edit ein paar Sekunden inne, damit der Auto-Commit landet, bevor du dich trennst oder veröffentlichst. * **Checkpointe bekannt-gute Zustände.** Verwende `create_checkpoint` (`sandbox checkpoint`), um einen Wiederherstellungspunkt vor oder nach einem riskanten Block von Edits zu markieren — es flusht zuerst ausstehende Änderungen, sodass der Nutzer immer zu diesem Punkt zurückrollen kann. * **Ein Agent zur Zeit.** Das Feature ist für einen einzelnen externen Agenten pro App ausgelegt; führe keine parallelen Sitzungen gegen dieselbe App aus. *** ## 10. Lokale Agenten über die `base44 sandbox`-CLI Wenn dein Agent auf deinem Rechner läuft, kann er dieselbe Sandbox über die Base44-CLI statt über MCP treiben und sich mit der Base44-CLI statt OAuth authentifizieren. Gleiche Tools, gleiches Verhalten, gleiche Fehlercodes (Abschnitt 8) — nur Oberfläche und Auth unterscheiden sich. **Auth.** Melde dich mit der Base44-CLI an (`base44 login`) — dieselben Anmeldedaten wie für `base44 functions deploy`. Wie die projektlosen `base44 connectors`-Befehle lösen die Sandbox-Unterbefehle die App-ID auf aus `--app-id`, dann `BASE44_APP_ID`, dann einer lokalen `.app.jsonc`; keine `config.jsonc` erforderlich. **Befehlsnamen.** Die CLI stellt jedes Sandbox-Tool unter einem kürzeren Namen bereit: | MCP-Tool | CLI-Befehl | | ------------------- | --------------------------- | | `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` nimmt einen optionalen `--name` (Nachricht/Titel) und speichert einen Wiederherstellungspunkt: ```bash theme={null} npx base44 sandbox checkpoint --app-id --name "before refactor" ``` **Gib einem Agenten die vollständige Referenz** für eine bestimmte App (Anweisungen, öffentlich, kein Auth zum Abruf nötig): ``` https://app.base44.com/api/sandbox//local-agent/readme.md ``` (Das Cloud/MCP-Äquivalent ist `.../api/sandbox//claude-web/readme.md`.) Alles andere in diesem Skill — die Edit→Preview→Verify-Schleife (Abschnitt 5), Persistenz (Abschnitt 6), Konkurrenz (Abschnitt 7) und Guardrails (Abschnitt 8) — gilt identisch; nur Oberfläche und Auth unterscheiden sich. *** ## 11. Connectors (OAuth-Integrationen) Über die Sandbox-Datei-/Shell-Tools hinaus stellt der Base44-MCP-Server zwei Tools zur Verwaltung eines Drittanbieter-OAuth-Connectors (Google Calendar, Gmail, Slack, …) für eine App bereit. Sie berühren das Sandbox-Dateisystem nicht — sie operieren direkt auf dem Connector-Status der App. Beide nehmen `appId`. | Tool | Scope | Zweck | | ------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `list_connectors` | `apps:read` | Listet die Connectors der App. Ohne `integrationTypes` gibt es den vollständigen Katalog zurück (Name, Beschreibung, verbunden?, und — falls verbunden — Status und gewährte Scopes). Übergib `integrationTypes` für Details zu bestimmten. | | `initiate_connector_connection` | `apps:write` | Verbinden (oder Scope neu anfragen) eines Connectors. Inputs: `appId`, `integrationType`, `scopes`, optional `connectionConfig`. | Zwei Semantiken, die du beachten musst: * **Deklarative Scopes (ersetzen, nicht mergen).** `initiate_connector_connection` setzt den Connector **exakt** auf die übergebenen `scopes`. Ausgelassene Scopes werden entfernt und der Nutzer wird erneut um Zustimmung gebeten. **Rufe immer zuerst `list_connectors` auf**, dann übergib das vollständige gewünschte Set (bestehende Scopes, die du behalten willst, **plus** neue). * **OAuth braucht einen Menschen.** Das Tool gibt entweder `already_authorized: true` zurück (nichts zu tun) oder eine `redirect_url`, die der **Nutzer** in einem Browser öffnen muss, um sich anzumelden und zuzustimmen — du kannst das nicht selbst abschließen. Nachdem er fertig ist, rufe `list_connectors` erneut auf, um zu verifizieren und die **gewährten** Scopes zu lesen (ein Anbieter kann weniger gewähren als angefordert). Diese benötigen nur `apps:read` / `apps:write` — **nicht** `sandbox:write`. Über die CLI-Oberfläche (Abschnitt 10) ist das Äquivalent die projektlosen `base44 connectors`-Befehle (`list-available`, `initiate --integration-type --scopes --app-id `, `pull`), die dieselbe Autorisierungs-URL ausgeben. Diese Seite wurde mit KI übersetzt. Für die genauesten und aktuellsten Informationen siehe die [englische Version](/).