Skip to main content

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.

InputTypeRequiredDescription
topic"all" | "sdk" | "agents"Noall (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.

InputTypeRequiredDescription
namestringYesDNS-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.

InputTypeRequiredDescription
projectstringYesProject name
files{ path, content, encoding? }[]One of files / tarball_base64Preferred for agents. path is relative (src/App.tsx); encoding is utf8 (default) or base64 for binary files.
tarball_base64stringOne of files / tarball_base64A base64-encoded .tar.gz of the folder
promotebooleanNoSwitch production to this deployment when healthy. Default true; false = preview only.
wait_secondsinteger 0–600NoHow long to wait for the build. Default 180.
purposestring (≤ 500)When neededOne 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

CodeWhen
PURPOSE_REQUIREDThe files use integrations that need approval and no purpose was given. The message lists each integration with file and line. Nothing was deployed.
NO_SOURCENeither 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.

tip

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.

InputTypeRequired
projectstringYes

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

InputTypeRequiredDescription
projectstringYes
deployment_idstringNoDefault: the live deployment
type"build" | "runtime" | "all"NoDefault all
tailinteger 1–5000NoLines. Default 200.

Returns { deploymentId, build?, runtime? }.

rollback​

Switches production back to the previous ready deployment, or to to. Instant: no rebuild.

InputTypeRequiredDescription
projectstringYes
tostringNoA 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.

InputTypeRequired
projectstringYes
deployment_idstringYes

Returns the same shape as rollback.

Errors: DEPLOYMENT_NOT_FOUND, NOT_READY (only ready deployments can serve production), PROJECT_NOT_ACTIVE, READ_ONLY.

Was this page helpful?