> ## Documentation Index
> Fetch the complete documentation index at: https://developers.zite.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Build tools
> Reference for the 17 Zite MCP build tools — creating workspaces and apps, editing code in a sandbox, checking, committing, and publishing.
These are the **build** tools exposed by the Zite MCP at `https://mcp.zite.com/mcp`. The server also
exposes 16 [data tools](/api/mcp/overview) for reading and writing records. The file-editing and check
tools run inside a sandbox and take the `sandboxId` returned by `create_sandbox`. The workspace tools,
`get_logs` and `publish_app` (both keyed by `appId`), `setup_integration`, and `send_feedback` work
without one.
If the sandbox, commit, and publish tools don't appear in your client's tool list, app building isn't
enabled for your organization yet. The workspace tools, the data tools, and `send_feedback` are always
available.
## Workspaces & sandboxes
| Tool | Parameters | Returns |
| ------------------ | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `create_workspace` | `name` | `{ workspaceId, name, url, next }` — a new, empty workspace (a database with no tables) |
| `list_workspaces` | — | `{ workspaces[] }` — every workspace you can access, each with its apps and forms |
| `get_workspace` | `workspaceId`, `sandboxId?` | `{ id, name, url, apps, forms, overview }` — pass `sandboxId` to also read the project `overview.md` |
| `create_sandbox` | `workspaceId` | `{ sandboxId, workspaceId, apps, files, integrations, connectableServiceTypes, docs, guide }` — boots a sandbox and returns the [framework guide](/ai-skill) |
| `create_app` | `sandboxId`, `name`, `accessMode?` | `{ appId, name, dir, editorUrl }` — scaffolds an empty app (`accessMode` defaults to `internal`) |
`create_app` is a **free scaffold** — it creates an empty app with no AI build, so it spends no Zite
credits. The scaffold lands in the repo with the agent's first `commit`.
## Files & editing
| Tool | Parameters | Returns |
| ------------ | ----------------------------------------- | --------------------------------------------------------------------------------------------- |
| `list_files` | `sandboxId`, `filter?` | `{ files, totalCount }` — substring or `*`-glob filter, capped at 1,000 |
| `grep` | `sandboxId`, `pattern`, `context?` | `{ results, matchCount }` — extended-regex search over code, `context` lines 0–10 (default 2) |
| `read_file` | `sandboxId`, `path`, `offset?`, `limit?` | `{ path, content, totalLines, offset }` |
| `edit_file` | `sandboxId`, `path`, `oldText`, `newText` | `{ path, replaced }` — exact string replacement; the primary way to change code |
| `write_file` | `sandboxId`, `path`, `content` | `{ path, bytes }` — new file or full rewrite |
| `bash` | `sandboxId`, `script` | `{ stdout, stderr }` — runs in the sandbox at the workspace root |
`edit_file` requires `oldText` to appear **exactly once** in the file. If it matches zero times or more
than once, the edit fails with guidance — include more surrounding context to make the match unique.
`bash` is the escape hatch for npm installs, `git` commands, file moves, and one-off scripts. Prefer the
structured file tools for editing so behavior stays predictable. Real commits should go through `commit`,
not raw `git commit`.
## Checks & logs
| Tool | Parameters | Returns |
| ----------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `check_app` | `sandboxId`, `appId?` | `{ ok, diagnostics, endpointErrors }` — regenerates types, then type-checks and validates config |
| `get_logs` | `appId`, `workflowId?`, `status?`, `mode?`, `limit?`, `hoursAgo?` | `{ runs, totalCount }` — workflow execution logs (inputs, output, console, stack traces) |
Use `get_logs` to catch runtime errors a type-check can't. Its filters:
| Parameter | Values | Default | Description |
| ------------ | --------------------------- | ------------- | ---------------------------------------------------- |
| `appId` | string, required | — | App to read logs for |
| `workflowId` | string | all workflows | Narrow to a single workflow |
| `status` | `all` · `success` · `error` | `all` | Filter by run outcome |
| `mode` | `live` · `preview` · `both` | `both` | `live` is production traffic, `preview` is test runs |
| `limit` | 1–50 | `5` | Number of runs returned |
| `hoursAgo` | 1–168 | `24` | Lookback window in hours |
## Ship
| Tool | Parameters | Returns |
| ------------- | ---------------------- | ------------------------------------------- |
| `commit` | `sandboxId`, `message` | `{ commitSha, changedApps[], message? }` |
| `publish_app` | `appId` | `{ published, liveUrl, accessMode, note? }` |
`commit` type-checks, commits and pushes, then **builds and snapshots in the background** — the returned
`changedApps` report `buildStatus: "building"`. If the remote has newer commits it returns a conflict;
run `git pull --rebase origin main` via `bash`, resolve, and commit again.
`publish_app` requires a **successful** build. If the latest build is still running or failed, it returns
an error — wait for the build, or fix errors with `check_app` / `get_logs` and commit again. External
apps publish to `https://.zite.so`.
## Integrations
| Tool | Parameters | Returns |
| ------------------- | --------------------------------------- | ------------------------------------------------------------------------------ |
| `setup_integration` | `workspaceId`, `service?`, `sandboxId?` | `{ connectableServiceTypes, orgServices, attached, connectUrl, instructions }` |
`setup_integration` returns the integration picture for a workspace: which third-party services can be
connected, the accounts your organization has already connected (`orgServices`), and — when a `sandboxId`
is passed — what's already attached to the database and each app. Two paths from there:
* **The org already has an account for the service** — the agent attaches it itself by writing the config
entry with the returned `connectionId`. No user interaction needed.
* **No account yet** — the agent shares `connectUrl` with you; the OAuth sign-in happens in your browser,
then the agent calls the tool again to pick up the new connection.
See [Integrations & secrets](/concepts/integrations-secrets).
## Feedback
| Tool | Parameters | Returns |
| --------------- | ------------------------------------------------------------- | -------------- |
| `send_feedback` | `severity`, `summary`, `details`, `toolName?`, `workspaceId?` | `{ ok, note }` |
Lets the agent report platform problems — broken tooling, unexpected behavior, docs gaps — straight to the
Zite team. `severity` is one of `broken_tooling`, `unexpected_behavior`, `environment_failure`,
`bad_schema`, or `other`. Available on every connection, with or without app building enabled.