​

Remotely develop a Base44 app over MCP

Easiest start: in the Base44 app editor, click Send to Coding Agent. For a local agent it gives you a ready-to-paste prompt (which fetches a README and drives the sandbox over MCP or the base44 sandbox CLI — Section 10); for the web it gives a prompt to paste into a claude.ai chat (with the Base44 MCP connector) plus an Open Claude button. The button is the discovery surface — the rest of this skill is the reference.

Two transports: web agents use claude.ai with the Base44 MCP connector (Sections 1–9) — note this is the regular claude.ai chat, not Claude Code on the web (claude.ai/code), which runs in its own repo-backed sandbox. A local agent can connect that same MCP server, or drive the sandbox with the base44 sandbox CLI (a Base44 CLI token, Section 10) — same tools, same behavior, same error codes; the CLI just exposes them under shorter command names (sandbox read, sandbox ls, …).

​

1. Connect the MCP server

https://app.base44.com/mcp

claude mcp add --transport http base44 https://app.base44.com/mcp

​

2. Authenticate

claude

/mcp

​

Scopes

​

3. Pick the app and orient yourself

Using the base44 tools on appId <APP_ID>:
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: if the app has no running sandbox, the first tool call transparently brings one up from your last commit — it just takes a bit longer. Subsequent calls are fast.

CLI names: over the base44 sandbox CLI (Section 10) these read tools are list_directory → sandbox ls, read_file → sandbox read, and grep → sandbox grep.

​

4. Make changes

• edit_file (sandbox edit in the CLI) — preferred for changing existing files. Provide exact old_text→new_text edits. Each old_text must be unique in the file unless you set replace_all. All edits in a call apply atomically (all-or-nothing) and you get a unified diff back. Pass dry_run: true to preview the diff without writing.
• write_file (sandbox write in the CLI) — for creating new files. To overwrite an existing file you must pass overwrite: true (it never silently clobbers).
• run_command (sandbox run in the CLI) — run any bash command in the sandbox (build, install, scaffolding, codemods). The working directory defaults to the app root; cd does not persist across calls, so use the cwd parameter or chain commands (cd sub && cmd). Timeout defaults to 120s (max 600s); output is capped at ~1 MB.
• create_checkpoint (sandbox checkpoint in the CLI) — save a named restore point the user can later roll back to. Takes an optional name (message/title; auto-generated if omitted). Any pending changes are flushed and committed first so the checkpoint anchors to your latest code; it then returns the checkpoint id, name, and git commit hash. Use it to mark a known-good state before or after a chunk of edits. (If a recent auto-commit can’t be confirmed durable yet, it refuses with the retryable COMMIT_FLUSH_PENDING rather than checkpoint stale state — retry shortly.)

On appId <APP_ID>, 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 and verify (the edit → check loop)

• See it live: get_app_preview_url brings up the dev server and returns the preview URL. Vite HMR reflects your edits as you make them.
• Build status: get_app_status returns ready / processing / error.
• Surface build/type/lint errors on demand with run_command:
  npm run build       # bundler/compile errors
  npx tsc --noEmit    # type errors
  npm run lint        # lint errors
  
• Read the dev-server (Vite) logs — the managed dev server writes to /tmp/vite.log. Tail it via run_command to see HMR/compile errors:
  tail -c 32000 /tmp/vite.log
  
  (This is outside the app tree, so it’s only reachable through run_command, not the file tools — and therefore needs sandbox:write.)

Browser-runtime errors (a component that compiles but throws on render, a failing client API call) appear in the browser console, not in /tmp/vite.log. Open the preview URL to catch those.

​

6. How your changes persist

• survives sandbox death (the sandbox is recreated from the last commit),
• appears in the builder’s Library/Data tabs,
• keeps backend-function deploys consistent, and
• is included when you publish the app.

• There’s a small loss window (~5s) — don’t kill the session immediately after the last edit; give it a moment to commit.
• Edits to entities, agents, workflows, backend functions, and page routing are synced into Base44 automatically after the commit. Plain page/component/CSS edits live in git and need nothing extra.

​

7. Concurrency: you vs. the Base44 builder

• While you’re actively using the sandbox tools, the Base44 builder chat is blocked (“An external agent is currently working on this app”). Your session is implicit — recent tool calls are the session; it ends after a short idle period (~10 min).
• If the Base44 builder is mid-build, your mutating tools return BUILDER_BUSY. Poll get_app_status and retry once it’s ready. Read-only tools still work during a build.

​

8. Guardrails & limits

• Paths are confined to the app. File tools operate only within the app directory; traversal/absolute paths are rejected (PATH_OUTSIDE_SANDBOX).
• .agents/ is off-limits to file tools (PROTECTED_PATH) — it holds agent-managed config and secrets (.agents/.env). Don’t try to read or edit it through the file tools.
• Rate limits apply per app: reads ~120/min, mutations ~60/min, commands ~30/min. If you hit RATE_LIMITED, slow down.
• delete_file isn’t a dedicated tool — delete via run_command rm.

​

Error codes you may see

​

9. Tips & tricks

• Read before you write. A quick list_directory + read_file (or grep) pass costs little and dramatically improves edit accuracy.
• Use dry_run on edit_file to confirm the diff before committing to a change, especially for multi-edit calls.
• Prefer edit_file over write_file for existing files — surgical edits avoid clobbering and produce a reviewable diff.
• Read line ranges with read_file’s offset/limit on large files instead of pulling the whole thing into context.
• When something “looks broken,” tail /tmp/vite.log before guessing — it usually names the exact file and line.
• Let it commit. Pause a few seconds after your final edit so the auto-commit lands before you disconnect or publish.
• Checkpoint known-good states. Use create_checkpoint (sandbox checkpoint) to mark a restore point before or after a risky chunk of edits — it flushes pending changes first, so the user can always roll back to that point.
• One agent at a time. The feature is designed for a single external agent per app; don’t run parallel sessions against the same app.

​

10. Local agents via the base44 sandbox CLI

npx base44 sandbox read --app-id <APP_ID> src/App.jsx

npx base44 sandbox checkpoint --app-id <APP_ID> --name "before refactor"

https://app.base44.com/api/sandbox/<APP_ID>/local-agent/readme.md

​

11. Connectors (OAuth integrations)

• Declarative scopes (replace, not merge). initiate_connector_connection sets the connector to exactly the scopes you pass. Omitted scopes are removed and the user is re-prompted to consent. Always call list_connectors first, then pass the complete desired set (existing scopes you want to keep plus any new ones).
• OAuth needs a human. The tool returns either already_authorized: true (nothing to do) or a redirect_url the user must open in a browser to sign in and consent — you can’t complete it yourself. After they finish, call list_connectors again to verify and read the granted scopes (a provider may grant fewer than requested).