Tools: build and deploy
Every tool returns a short summary line followed by the JSON result. On failure the result has isError: true and the text CODE: message, for example PROJECT_NOT_FOUND: ….
whoami
The signed-in user and the platform version.
Input: none.
Returns { user: { id, email, name, isAdmin }, product, version }.
get_docs
How to build apps on the platform, in one read: the SDK (browser and server, JavaScript and Python), the database (PostgREST/Supabase query syntax, row-level security helpers, migrations), file storage, Microsoft 365 as the signed-in user, and deploy conventions.
| Input | Type | Required | Description |
|---|---|---|---|
topic | "all" | "sdk" | "agents" | No | all (default), sdk (the SDK guide only), or agents (a short snippet to paste into a project's AGENTS.md / CLAUDE.md) |
Returns Markdown text.
list_my_projects
Projects you own, with production URL and latest deployment status.
Input: none.
Returns an array of { name, status, url, productionDeploymentId, liveDeploymentId, latestDeployment, lifecycle, createdAt }.
create_project
Creates a project (a URL and its services) and waits until it's ready. You usually don't need it: deploy creates the project too.
| Input | Type | Required | Description |
|---|---|---|---|
name | string | Yes | DNS-safe: lowercase letters, digits, dashes, e.g. q3-variance |
Returns the project. If it already existed, the summary says so.
deploy
Uploads source and deploys it. Creates the project if needed. Waits for the build, then returns the production URL, the immutable preview URL, the build log tail and any access requests the deploy created.
| Input | Type | Required | Description |
|---|---|---|---|
project | string | Yes | Project name |
files | { path, content, encoding? }[] | One of files / tarball_base64 | Preferred for agents. path is relative (src/App.tsx); encoding is utf8 (default) or base64 for binary files. |
tarball_base64 | string | One of files / tarball_base64 | A base64-encoded .tar.gz of the folder |
promote | boolean | No | Switch production to this deployment when healthy. Default true; false = preview only. |
wait_seconds | integer 0–600 | No | How long to wait for the build. Default 180. |
purpose | string (≤ 500) | When needed | One line for approvers: why the app needs its integrations. Required when the code uses an integration that needs approval. |
Returns
{
"project": "escalations",
"url": "https://escalations.apps.contoso.com",
"deployment": { "id": "d7f3a2", "status": "ready", "kind": "node", "type": "web", "previewUrl": "…", "production": true },
"accessRequests": [
{ "id": 14, "status": "pending", "integration": "salesforce", "scopes": ["Case:read"], "identity": "user", "approvers": [{ "name": "Leo Park" }], "url": "…", "autoRule": null }
],
"buildLogTail": "…"
}
The summary tells the agent what to tell the person: "Live at … Waiting for approval: #14 salesforce Case:read → Leo Park. Those calls return ACCESS_PENDING until approved; no redeploy needed."
Errors
| Code | When |
|---|---|
PURPOSE_REQUIRED | The files use integrations that need approval and no purpose was given. The message lists each integration with file and line. Nothing was deployed. |
NO_SOURCE | Neither files nor tarball_base64 |
| (isError, failed) | The build failed; the result includes the build log tail |
If the build is still running after wait_seconds, the summary says so: follow it with get_status.
Exclude node_modules, .git, build output and secrets from files.
get_status
Project status, production URL, recent deployments (status, preview URL, which one is production) and recent access requests.
| Input | Type | Required |
|---|---|---|
project | string | Yes |
Returns the project with deployments[] and accessRequests[] (id, status, integration, scopes, decision).
get_logs
Build and/or runtime logs for a deployment (default: the live one).
| Input | Type | Required | Description |
|---|---|---|---|
project | string | Yes | |
deployment_id | string | No | Default: the live deployment |
type | "build" | "runtime" | "all" | No | Default all |
tail | integer 1–5000 | No | Lines. Default 200. |
Returns { deploymentId, build?, runtime? }.
rollback
Switches production back to the previous ready deployment, or to to. Instant: no rebuild.
| Input | Type | Required | Description |
|---|---|---|---|
project | string | Yes | |
to | string | No | A deployment id |
Returns the project (name, status, url, productionDeploymentId, liveDeploymentId, latestDeployment, lifecycle, createdAt) plus previousDeploymentId and switched (whether the Edge already serves the new deployment).
Errors: NO_ROLLBACK_TARGET, DEPLOYMENT_NOT_FOUND, NOT_READY, PROJECT_NOT_ACTIVE, READ_ONLY.
promote
Makes a ready deployment (for example a preview) serve production.
| Input | Type | Required |
|---|---|---|
project | string | Yes |
deployment_id | string | Yes |
Returns the same shape as rollback.
Errors: DEPLOYMENT_NOT_FOUND, NOT_READY (only ready deployments can serve production), PROJECT_NOT_ACTIVE, READ_ONLY.