Skip to main content
Building a Zite app with the MCP follows a tight loop that mirrors how Claude Code works: boot a sandbox, write code, check it, commit, and publish, verifying at runtime before calling it done.

Sandboxes

A sandbox is the agent’s session, much like a browser tab. create_sandbox(workspaceId) boots a cloud environment with the workspace’s whole monorepo checked out, and returns a sandboxId plus the file tree and the apps already in the workspace.
  • Every build tool takes the sandboxId. create_sandbox is the only tool that returns one.
  • One sandbox per chat. Two chats get separate sandboxes, so they never clobber each other.
  • You can work on any app in the workspace from one sandbox, and creating a new app stays in the same session.
  • Idle sandboxes stop automatically after a few minutes; the next call wakes them again.
  • Uncommitted files don’t survive a sandbox reset, so commit at working checkpoints, not only at the end.
create_sandbox also returns a framework guide: the concise spec of how Zite apps are structured. See The framework guide.

The loop

1

Create the app

create_app scaffolds an empty app at apps/<dir>/. This is a free scaffold, so no AI build runs.
2

Write workflows and UI

Add backend workflows in src/api/ and the React frontend in src/. Use edit_file for changes (exact string replacement) and write_file for new files. Use grep and read_file to navigate.
3

Regenerate types

After adding, renaming, or deleting workflow files, run npx zitejs generate from the workspace root via bash. It refreshes the typed zitejs/api client. check_app and commit also run it for you.
4

Check

check_app refreshes .zite/db.ts from the live database, regenerates types, and type-checks every app. Fix everything it reports before committing, because commit doesn’t type-check.
5

Commit

commit commits and pushes, and kicks off a background build and snapshot of the apps it touched. It returns the editor URL to share. Builds run in the background, so a fresh commit reports buildStatus: "building". To rebuild code that reached main another way, use build_app.
6

Verify at runtime

A clean type-check doesn’t prove the app works. SQL identifier mistakes and integration errors only surface at runtime. Try key queries and integration calls with run_one_off_script, which runs in the same runtime as workflows. It writes to the live database, so ask before seeding data or remove what you add. Then pull get_logs to check the workflows’ runs for errors.
7

Publish

publish_app takes the latest successful build live. External apps get a zite.so URL. See Publishing.

Data access

The frontend never touches the database directly. It calls backend workflows, which query the database client (zite.<table> and zite.sql()). Read .zite/db.ts first for exact table and field names, and prefer zite.sql() for counts, joins, and aggregates, because findAll returns 500 records unless you pass a limit, and 2,000 at most.

Conventions

  • Project layout: imports via zitejs/* and @project/components/ui/* aliases; never edit generated .zite/ or src/main.tsx; install any other npm package into the app with npm install <pkg> -w apps/<dir> via bash.
  • Build tools: every tool’s parameters and behavior.