base44_readme
ChatGPTCall this first, before any other Base44 tool, once per conversation, including for simple lookups. Explains which tool fits which job, the two ways to change an app, and the step-by-step loop for driving the builder AI: how to send a change, how to poll on every host, how to read the AI's reply and act on a paused turn, and how to preview and deploy. Do not call it again for follow-ups in the same conversation.
create_base44_app
ChatGPTCreate a new application using Base44's AI-powered builder. This operation is asynchronous — the app builds in the background, typically takes around 5 minutes but can take longer. IMPORTANT: After calling this tool, you MUST first respond to the user with the editorUrl from the response. Only AFTER you've sent the user the editor link, use get_app_status to poll until status is 'ready' or 'error'. All app editing is done through the Base44 Editor, not through this chat.
create_checkpoint
ChatGPTSave a restore point in the builder's version history, with an optional name. Pending changes are committed first so it captures the latest code. Files you write or edit are committed but not checkpointed, so this is the only thing that makes your work restorable: a Restore or Revert in the builder rolls the app back to the last checkpoint and everything after it is lost. Call it when you finish a unit of work and always before you stop; a short name saying what changed helps the user pick the right version. Pass the session_id from start_checkpoint to close that checkpoint session.
create_entities
ChatGPTAdd one or more data records to an existing entity (max 100 per call). This adds data only — it does not modify the app's code, UI, or schema. The built-in 'User' entity cannot be created through this tool. Use list_entity_schemas first to check required fields.
create_entity_schema
ChatGPTDefine a new entity type with its field structure. This creates the schema only — to add data records, use create_entities. Always check existing schemas with list_entity_schemas first. Row-Level Security (RLS) Entity schemas can include RLS rules under the 'rls' field to restrict record access based on user identity. RLS rules are defined per operation: create, read, update, delete. Template variables: {{user.id}}, {{user.email}}, {{user.role}}, {{user.data.<field>}}. Rule types: 1. user_condition — exact equality check on user attributes (no MongoDB operators). E.g. {"user_condition": {"role": "admin"}} 2. Entity-user field comparison — MongoDB query syntax. Custom fields MUST use "data." prefix (e.g. "data.user_id": "{{user.id}}"). Built-in fields (id, created_by_id, created_date, updated_date) are at root level. Combine with $and/$or/$in/$nin. Rules must reference user template variables, never static values. Example: {"rls": {"read": {"created_by_id": "{{user.id}}"}, "update": {"$or": [{"created_by_id": "{{user.id}}"}, {"user_condition": {"role": "admin"}}]}}}
edit_base44_app
ChatGPTEdit an existing Base44 app by sending a change request to the AI builder. This operation is asynchronous — changes are applied in the background, typically takes around 5 minutes but can take longer. IMPORTANT: After calling this tool, you MUST first respond to the user with the editorUrl from the response. Only AFTER you've sent the user the editor link, use get_app_status to poll until status is 'ready' or 'error'. Further editing is done through the Base44 Editor, not through this chat.
edit_file
ChatGPTApply one or more exact old_text→new_text edits to an existing file. Each old_text must be unique unless replace_all is set. All edits apply atomically (all-or-nothing) and a unified diff is returned. Use dry_run=true to preview the diff without writing. Changes auto-commit, but a commit is not a checkpoint: only checkpoints appear in the builder's version history, and a Restore or Revert there rolls the app back to the last checkpoint and discards everything written after it. Call create_checkpoint when you finish a unit of work and before you stop. If the app has no running sandbox, one is created transparently from the last commit (the first call on a cold app takes longer). Before a change, call start_checkpoint and pass its session_id here: changes made inside a checkpoint session consume fewer integration credits than changes made outside one, and create_checkpoint with the same session_id finishes it.
get_app_preview_url
ChatGPTGet the live preview URL for a Base44 app. Only returns a URL when the app build status is 'ready'. Returns null if the app is still building or has no sandbox.
get_app_status
ChatGPTCheck the build status of a Base44 app. Returns one of: 'ready', 'processing', or 'error'. Use this to poll after calling create_base44_app or edit_base44_app. Poll every 30 seconds until the status is 'ready' or 'error'.
grep
ChatGPTSearch the app's files for a pattern (ripgrep when available, grep otherwise). Returns matching lines with file/line, capped by max_results with a truncated flag. If the app has no running sandbox, one is created transparently from the last commit (the first call on a cold app takes longer).
import-claude-design-from-url
ChatGPTImport a design into Base44 from a publicly fetchable URL. The file is a self-contained HTML bundle with all images, fonts, and styles inlined. Base44 starts building an editable app from it and returns the Base44 Editor URL immediately so the user can watch progress.
initiate_connector_connection
ChatGPTConnect (or change the scopes of) a third-party OAuth connector (e.g. 'googlecalendar', 'slack') for a Base44 app. This SETS the connector to EXACTLY the scopes you pass — it REPLACES the current scopes (declarative/idempotent), it does not merge. IMPORTANT: ALWAYS call list_connectors FIRST to read the connector's current scopes, then pass the COMPLETE desired set (the existing scopes you want to keep PLUS any new ones) — any scope you omit is removed and the user is re-prompted to consent. If the requested scopes differ from what's authorized, returns a URL the USER must open in a browser to grant access (you cannot complete OAuth consent yourself) — tell them to open it, then call list_connectors to verify and read the granted scopes (the provider may grant fewer than requested). If the connection already has exactly these scopes, it reports already-connected and nothing changes. Discover valid integration_type values and any required connection_config via list_connectors first. Requires the 'apps:write' scope (part of the default scope set) — a session granted only 'apps:read'/'sandbox:write' must re-authenticate with 'apps:write' to use this tool.
list_branches
ChatGPTList main and active branches of a Base44 app, with names, IDs, and status. Use the returned ID as branchId/branch_id in subsequent MCP calls, or the name with CLI --branch. Main has a null ID: omit branchId/branch_id to target main. Ask the user when the intended branch is unclear.
list_connectors
ChatGPTList the OAuth connectors (third-party integrations like Google Calendar or Slack) available to a Base44 app, and which are already connected. Call with no integration_types to get the full catalog — each entry has the connector's name, description, whether it's connected, and (if connected) its status and granted scopes. Pass integration_types to get full detail for specific connectors, including the connection_config_fields needed before connecting. Use this to discover what can be connected AND to verify a connection succeeded after the user authorizes.
list_directory
ChatGPTList directory entries for orientation, optionally recursive with a depth cap. If the app has no running sandbox, one is created transparently from the last commit (the first call on a cold app takes longer).
list_entity_schemas
ChatGPTList the entity schemas (data models) defined in a Base44 app. Returns the JSON schema structure for each entity, including field names, types, and constraints. Use this to understand the data model before querying entities.
list_user_apps
ChatGPTList all apps owned by the authenticated user. Always returns both app names and their IDs. Optionally filter by name.
query_entities
ChatGPTQuery entity records (rows) from a Base44 app using MongoDB-style filters. Supports filtering, sorting, pagination, and field selection. Use list_entity_schemas first to understand the available entities and their fields. Every app has a built-in 'User' entity — to list app users, query entityName='User'.
read_file
ChatGPTRead file contents, optionally a line range (offset/limit) for token efficiency. Per-file errors are reported individually rather than failing the whole call. If the app has no running sandbox, one is created transparently from the last commit (the first call on a cold app takes longer).
run_command
ChatGPTExecute a bash command inside the app's sandbox (working dir defaults to the app root). Each call is a fresh shell — cd does not persist; use the cwd param or chain commands. Output is capped (~1 MB) and the timeout is clamped (default 120s, max 600s). Note: shell access can read any files in the sandbox, including any secrets stored there. Changes auto-commit, but a commit is not a checkpoint: only checkpoints appear in the builder's version history, and a Restore or Revert there rolls the app back to the last checkpoint and discards everything written after it. Call create_checkpoint when you finish a unit of work and before you stop. If the app has no running sandbox, one is created transparently from the last commit (the first call on a cold app takes longer). Before a change, call start_checkpoint and pass its session_id here: changes made inside a checkpoint session consume fewer integration credits than changes made outside one, and create_checkpoint with the same session_id finishes it.
start_checkpoint
ChatGPTCall this before you start changing an app. It returns a session_id to pass to every write_file, edit_file and run_command call of the change, and to the create_checkpoint call that finishes it. Changes made inside a checkpoint session consume fewer integration credits than changes made outside one. Writes still apply to the app immediately; they only become restorable once create_checkpoint with this session_id saves the restore point, so always finish the session.
update_entities
ChatGPTUpdate entity records matching a query using MongoDB update operators. Does not require individual record IDs — use a query filter to match records and apply operators to all matches (up to 500 per call). IMPORTANT: The 'data' field MUST use update operators — bare field assignment like {"status": "active"} is not accepted; use {"$set": {"status": "active"}} instead. The built-in 'User' entity cannot be updated through this tool. If the response contains has_more=true, more records matched than the batch limit — call again with an adjusted query that excludes already-updated records (e.g. filter on the old value) to avoid an infinite loop. Supported operators: $set, $rename, $unset, $inc, $mul, $min, $max, $currentDate, $addToSet, $push, $pull. Examples: query={"status": "pending"}, data={"$set": {"status": "active"}} to update matching records; query={"category": "legacy"}, data={"$rename": {"oldField": "newField"}} to rename a field on matching records.
update_entity_schema
ChatGPTUpdate the field definitions, types, or constraints of an existing entity. To modify data records, use update_entities. Always check existing schemas with list_entity_schemas first. This also writes the entity's definition into the app's source code (base44/entities/<Name>.jsonc), so the change is durable. IMPORTANT: Security rules are automatically preserved when omitted from your update: - Entity-level RLS (the top-level 'rls' field) is preserved if you omit it. - Field-level security (per-field 'rls' inside properties) is preserved for each field that omits it. To intentionally modify or remove security rules, include them explicitly (use an empty object like 'rls': {} to clear). Row-Level Security (RLS) Entity schemas can include RLS rules under the 'rls' field to restrict record access based on user identity. RLS rules are defined per operation: create, read, update, delete. Template variables: {{user.id}}, {{user.email}}, {{user.role}}, {{user.data.<field>}}. Rule types: 1. user_condition — exact equality check on user attributes (no MongoDB operators). E.g. {"user_condition": {"role": "admin"}} 2. Entity-user field comparison — MongoDB query syntax. Custom fields MUST use "data." prefix (e.g. "data.user_id": "{{user.id}}"). Built-in fields (id, created_by_id, created_date, updated_date) are at root level. Combine with $and/$or/$in/$nin. Rules must reference user template variables, never static values. Example: {"rls": {"read": {"created_by_id": "{{user.id}}"}, "update": {"$or": [{"created_by_id": "{{user.id}}"}, {"user_condition": {"role": "admin"}}]}}}
write_file
ChatGPTCreate a new file, or overwrite an existing one only when overwrite=true (never silently clobbers). Prefer edit_file for changes to existing files. Changes auto-commit, but a commit is not a checkpoint: only checkpoints appear in the builder's version history, and a Restore or Revert there rolls the app back to the last checkpoint and discards everything written after it. Call create_checkpoint when you finish a unit of work and before you stop. If the app has no running sandbox, one is created transparently from the last commit (the first call on a cold app takes longer). Before a change, call start_checkpoint and pass its session_id here: changes made inside a checkpoint session consume fewer integration credits than changes made outside one, and create_checkpoint with the same session_id finishes it.
create_base44_app
Claudeedit_base44_app
Claudelist_entity_schemas
Claudelist_user_apps
Claudequery_entities
Claude
