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 — think of it 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 about 15 minutes; the next call transparently re-boots.
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 — 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 runs the type-check and build validations. Fix everything it reports before committing.
5

Commit

commit type-checks, commits and pushes, and kicks off a background build and snapshot. It returns the editor URL to share. Builds run in the background, so a fresh commit reports buildStatus: "building".
6

Verify at runtime

A clean type-check doesn’t prove the app works — SQL identifier mistakes and integration errors only surface at runtime. Exercise the key workflows (seed a record, call the dashboard workflow) and pull get_logs to check 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 — findAll caps at 2,000 records.

​
Conventions

  • Project layout — imports via zitejs/* and @project/components/ui/* aliases; never edit generated .zite/ or src/main.tsx; only the bundled frontend libraries compile.
  • Build tools — every tool’s parameters and behavior.