Deploy a ZIP or a small inline artifact

Deploy to an existing site using a complete static build. Confirm the organization, site_slug, and target environment before starting. The initial /new workflow has already selected its reserved production destination; returning site work uses your authenticated account.

Prepare the artifact#

Build the project and inspect the output. index.html must be at the archive root, alongside its public pages and assets—not inside an enclosing dist/ directory.

For example, after entering the compiled output directory:

zip -r /tmp/site.zip .

Include required CMS manifests and private templates for a CMS-enabled site. Exclude source archives, dependencies, .git, environment files, credentials, and temporary launch responses. Read max_bytes from the deployment response as the artifact-size authority.

Start, upload, and finalize#

1. Call start_deploy with the selected organization_id, site_slug, and environment (staging, production, or both).
2. Save the returned deploy_id, signed upload_url, expiry, and size limit privately.
3. Upload the ZIP bytes to that exact signed URL using HTTP PUT before it expires. Use file/binary mode; do not upload base64 text or a JSON wrapper. Do not send the MCP bearer credential to storage.
4. Call finalize_deploy with the returned deployment ID. An optional artifact_sha256 can verify the ZIP bytes.
5. Poll get_deploy at its returned retry_after_seconds until the status becomes live or failed.

A representative tool argument object is:

{"organization_id":42,"site_slug":"example-site","environment":"staging"}

Replace the illustrative ID and slug with the values discovered for your site. Staging and both require the release workflow; production in that workflow requires an active custom domain.

Inline deployment for a tiny artifact#

deploy_files accepts files as { "path": "...", "content_base64": "..." } with a total decoded limit of 500 KB (500,000 bytes). It starts processing directly, so no signed upload or finalization is needed; still poll the returned deployment ID.

Treat inline files as a new artifact, not a patch merged with the previous website. Include all pages and assets needed by that tiny site. Sending only one changed stylesheet can leave the new deployment without its previous pages. Use a complete ZIP for normal Astro sites.

Verify publication and recover safely#

Inspect warnings, skipped pages, errors, environment, and live_urls. Open each selected destination, verify the changed content and important links, and check discovery and chat behavior.

If finalization says no_artifact, confirm the upload and retry the same unexpired upload URL before starting another deployment. If a response was lost, inspect history before duplicating work. Poll deployments already processing; do not re-finalize queued, extracting, or live runs. See deployment troubleshooting for failed artifacts and release environments for promotion.