> ## 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.

<Note>
  **Availability.** The build tools are free for 7 days. The trial starts the first time your agent calls
  `create_sandbox`, with no card and nothing to switch on. After that they're on the Business plan and
  above: they stay listed in your client, and calling one returns an upgrade message. The workspace tools,
  the data tools, and `send_feedback` are always available, and the Zite editor builds apps on any plan.
</Note>

## 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`) |

<Note>
  `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`.
</Note>

## 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 |

<Warning>
  `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.
</Warning>

<Note>
  `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`.
</Note>

## 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? }` |

<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.
</Note>

<Warning>
  `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://<subdomain>.zite.so`.
</Warning>

## 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.