Provision a new Postgres database. Returns project credentials on success, or payment details if x402 payment is needed.

Execute SQL (DDL or queries) against a provisioned project. Returns results as a markdown table.

Query or mutate data via the PostgREST REST API. Supports GET/POST/PATCH/DELETE with query params.

Apply a declarative authorization manifest to a project (POST /projects/v1/admin/:id/expose). The manifest describes the full authorization surface: tables (with policy, owner_column, force_owner_on_insert, i_understand_this_is_unrestricted, custom_sql), views (with base, select, filter), and rpcs (with signature, grant_to). Convergent: applying the same manifest twice is a no-op; items dropped between applies have their policies/grants/triggers/views revoked. Tables are dark by default — any table not declared with expose:true is unreachable via anon/authenticated.

Validate an auth/expose manifest without applying it. This checks the authorization manifest used by manifest.json, database.expose, and apply_expose; it is not deploy-manifest validation. Optional migration_sql is reference context only and is not executed. Use deploy planning/dry-run surfaces for deploy manifest questions.

Get the current authorization manifest for a project (GET /projects/v1/admin/:id/expose). Returns the last-applied manifest from internal.project_manifest, or a manifest reconstructed by introspecting live DB state if none has ever been applied. The source field is "applied" or "introspected".

Introspect the database schema — tables, columns, types, constraints, and RLS policies. Useful for understanding the database structure before writing queries.

Get project usage report — API calls, storage usage, limits, and lease expiry.

Upload a blob (file or inline content) to project storage via direct-to-S3. Accepts local_path (any size up to 5 TiB) or content (≤ 1 MB inline). Public blobs get a CDN URL; private blobs require authenticated reads. Use immutable: true to produce a content-addressed URL that never needs cache invalidation. For image uploads (jpeg/png/webp/heic/heif), the gateway also returns width_px/height_px/blurhash/display_url and a variants map (thumb 320w, medium 800w, large 1920w WebP — plus display_jpeg for HEIC sources) so apps can render responsive thumbnails without re-encoding client-side. See the SDK docs for the full AssetRef shape.

Download a blob to a local file path. Writes bytes directly to disk (no context-window bloat). Returns size + SHA-256 header (if the blob has one stored).

List blobs in a project with optional prefix filter over a flat key namespace. Supports pagination via cursor.

Delete a blob from project storage and decrement the project's storage_bytes.

Generate a time-boxed S3 presigned GET URL for a blob. Use this to share a private blob externally without exposing your apikey. Default TTL 1 hour, max 7 days.

Returns the live CDN state for a public blob URL (probed once from gateway-us-east-1 — NOT a global view). Use this when a deployed asset shows the wrong version or you suspect cache staleness. The result includes expectedSha256 (from gateway DB), observedSha256 (what CloudFront just served), recent invalidation status, and a human-readable hint with actionable next-steps. The probeMayHaveWarmedCache: true field warns that the probe itself populates the cache, so subsequent reads from elsewhere may differ. URLs outside the requesting project return 403; non-*.run402.com URLs return 400 unless they're on one of your active custom domains.

Polls the CDN until a MUTABLE blob URL serves the expected SHA-256, or the timeout elapses. For mutable URLs only — for immutable URLs (the immutableUrl returned by assets_put), no waiting is needed; they're bound to a SHA at upload time and never previously cached. Use this after a re-upload to an existing public mutable key when an end-user-visible URL must reflect the new content before continuing. The probe is single-vantage (us-east-1). On timeout, the tool returns isError=true so an agent can branch into a fallback — typically: switch to the immutableUrl.

Deploy a serverless function (Node 22) to a project. Handler signature: export default async (req: Request) => Response. The function can import { db, adminDb, getUser, email, ai } from '@run402/functions' — auto-bundled by the platform. Additional npm packages are bundled at deploy time when listed in deps (bare names resolve to latest; pinned/range specs are honored verbatim; @run402/functions and run402-functions rejected; max 30 entries; native binaries rejected). The response includes runtime_version (the bundled @run402/functions version — surface as 'Functions runtime version', never bare 'runtime'), deps_resolved (map of dep name → installed concrete version), and an optional top-level warnings array (sibling to the function record).

Invoke a deployed function via HTTP. Returns the function's response body and status code. Useful for testing functions without building a frontend.

Get recent logs from a deployed function. Shows console.log/error output and error stack traces from CloudWatch.

List all deployed functions for a project. Shows names, URLs, runtime, timeout, memory, and (for functions deployed under bundling-at-deploy) the Functions runtime version (@run402/functions version) and resolved direct deps. Functions deployed before that change have runtime_version and deps_resolved set to null.

Delete a deployed function from a project.

Update a function's schedule, timeout, or memory without re-deploying code. Pass schedule as a cron expression to set/update, or null to remove.

Set a project secret (e.g. STRIPE_SECRET_KEY). Values are write-only and injected as process.env variables in functions. Setting an existing key overwrites it. Use this before deploy, then declare the key with secrets.require.

List secret keys for a project. Values and value-derived hashes are never shown; use this only to check which keys are configured.

Delete a secret from a project.

Submit a fixed platform-managed job. The request must match the gateway jobs API shape: job_type, input with input.json, and max_cost_usd_micros. The SDK supplies the required idempotency header.

Get a managed job run by id.

Read recent runner logs for a managed job. Use tail to cap entries and since for an epoch millisecond lower bound.

Cancel a queued or running managed job.

Deploy a static site (HTML/CSS/JS) from inline file bytes. Files are staged to a temp directory, then uploaded via the v1.32 plan/commit transport — only bytes the gateway doesn't already have are PUT. Served at a unique URL via CloudFront. Free with active tier.

Deploy a static site from a local directory. Walks the tree, hashes each file, and uploads only the bytes the gateway doesn't already have via the v1.32 plan/commit transport. Files named .git, node_modules, or .DS_Store are skipped; symlinks are rejected. Re-deploying an unchanged tree issues no S3 PUTs. Free with active tier.

Unified deploy primitive (v1.34+). Accepts a structured ReleaseSpec — database (migrations + expose), value-free secrets.require/delete declarations, functions, site, site.public_paths, subdomains, and routes.replace web routes — with explicit replace vs patch semantics per resource. Use site.public_paths for clean static URLs such as /events backed by release asset events.html; explicit mode does not expose /events.html unless separately declared, while mode: 'implicit' restores filename-derived reachability and can widen access. Route entries map exact/final-wildcard browser paths like /admin and /admin/* to Node 22 Fetch Request -> Response functions, or exact GET/HEAD method-aware static aliases such as /events to { type: 'static', file: 'events.html' }; intentional read-only GET/HEAD wildcard function routes may set acknowledge_readonly: true. Direct /functions/v1/:name remains API-key protected. Secret values must be set first with set_secret, never placed in deploy specs. All bytes ride through CAS (no inline-body cap). Returns release_id, URLs, warnings, and a structured progress-event log. Stops before upload/commit on confirmation-required warnings unless reviewed codes are passed with allow_warning_codes or allow_warnings is true.

Read-only authenticated diagnostics for a Run402 public URL or host/path pair. Explains whether the current live release would serve the URL, including match, diagnostic body status, static manifest/cache metadata when returned, structured warnings for ignored query/fragment, and next steps. This does not fetch bytes, purge cache, mutate deploy state, or expose internal CAS URLs.

Resume a deploy operation that ended in activation_pending or schema_settling (e.g. transient gateway failure between SQL commit and the pointer-swap activation). The gateway re-runs only the failed phase forward — SQL is never replayed. Idempotent: calling on an already-terminal operation returns the snapshot without re-running.

List recent deploy operations for a project. Returns operation_id, status, release_id, and timestamps. Use this to build deploy-history UIs or to find a recent operation_id to feed into deploy_resume / deploy_events. Pass limit to bound the result set; the gateway also returns a cursor for pagination when there are more.

Fetch the recorded phase-event stream for a deploy operation. Returns the same DeployEvent shapes the deploy tool emits inline during an in-flight deploy — useful for inspecting a deploy after the fact (e.g., a deploy that the agent didn't observe directly, or one being resumed from a different process).

Fetch a release inventory by id. Returns release metadata, effective/desired state kind, site path inventory, function inventory, secret keys, subdomains, and applied migrations. Use site_limit to cap large site inventories. Canonical SDK errors are preserved.

Fetch the current-live release inventory for a project. Returns release_id: null with an empty current-live inventory when no release is active yet. Use this before deploy diffs to understand what is currently serving. Canonical SDK errors are preserved.

Diff two release targets for a project. from may be empty, active, or a release id; to may be active or a release id. Returns release-to-release diff buckets and migrations.applied_between_releases. Semantic gateway errors such as invalid targets, same-release diffs, or no active release are preserved.

Create a GitHub Actions CI/OIDC deploy binding by sending a locally signed delegation to the SDK. This MCP wrapper does not sign or broaden authority; the signed delegation defines the repository/branch or environment, allowed events/actions, and optional route_scopes. Without route_scopes, CI cannot deploy route declarations.

List CI/OIDC deploy bindings for a project, including route_scopes when delegated. Use this to inspect which GitHub Actions subjects can deploy before editing bindings.

Get one CI/OIDC deploy binding by id, including its subject, allowed events/actions, repository id, revocation state, and route_scopes.

Revoke one CI/OIDC deploy binding. Revocation stops future CI gateway requests, but does not undo already deployed releases or rotate secrets.

Claim a custom subdomain (e.g. myapp.run402.com) and point it at an existing deployment. Free, requires service_key auth.

Release a custom subdomain. The URL will stop serving content.

List all subdomains claimed by a project.

Register a custom domain (e.g. example.com) to point at a Run402 subdomain. Returns DNS instructions for the human to configure.

List all custom domains registered for a project.

Check if a custom domain's DNS is configured and SSL is active. Poll this after registering a domain.

Release a custom domain mapping. Traffic to the domain will no longer route to Run402.

Browse public apps available for forking. Optionally filter by tags.

Fork a published app into a new project. Creates a full copy including database, functions, site, and optionally claims a subdomain.

Publish a project as a forkable app. Set visibility and tags for discoverability.

List published versions of a project.

Get tier pricing for Run402 projects. Free, no auth required. Shows prices, lease durations, storage limits, and API call limits.

Check current tier subscription — tier name, status, expiry, usage, and function authoring caps when returned (max timeout, memory, scheduled functions, min cron interval). Requires allowance auth.

Subscribe, renew, or upgrade tier. Auto-detects action based on allowance state. Returns success or payment details if x402 payment is needed.

Immediately and irreversibly delete a project: the gateway runs the full destructive cascade (drop tenant schema, delete Lambda functions, release subdomains, tombstone mailbox, remove sender domain, wipe secrets and app versions) and sets status=purged. This tool also removes the project from the local key store. Distinct from the automatic lease-expiry grace window — this action is the explicit purge and cannot be undone. To recover from a missed renewal use set_tier instead.

Pin a project so it is not garbage-collected or expired. Admin only — uses the configured allowance wallet for run402 platform admin auth; project owners authenticating with service_key or a non-admin SIWX wallet will receive 403 admin_required. Not a self-service command for regular users.

Promote a user to project_admin role by email. Admins can manage secrets from the browser. Requires service_key.

Demote a user from project_admin role by email. Reverts to default authenticated role. Requires service_key.

Check billing account balance for an agent allowance address. Shows available and held funds.

List all active projects for an agent allowance address.

Check local agent allowance status — address, network, and funding status.

Create a new local agent allowance (Base Sepolia testnet). Generates a private key and derives the Ethereum address. Saved to ~/.config/run402/allowance.json.

Export the local agent allowance address. Safe to share publicly.

Request free testnet USDC from the Run402 faucet (Base Sepolia). Rate limit: 1 per IP per 24h. Returns 0.25 USDC — enough for 2 prototype databases.

Generate a PNG image from a text prompt. Costs $0.03 USDC via x402. Aspect ratios: square (1:1), landscape (16:9), portrait (9:16).

Create a project-scoped email mailbox at @mail.run402.com. One mailbox per project.

Send an email from the project's mailbox. Two modes: template (project_invite, magic_link, notification) or raw HTML (subject + html). Optional from_name for display name. Single recipient only.

List sent emails from the project's mailbox. Shows message ID, template, recipient, status, and timestamp.

Get a sent email with details and any replies.

Get the raw RFC-822 bytes of an inbound email message, base64-encoded. The decoded bytes are bit-identical to the DKIM-signed original — no parsing, normalization, or CRLF cleanup. Use this for cryptographic verification (DKIM checks, zk-email proofs). Inbound messages only; outbound returns 404. For display/threading, use get_email instead.

Get the project's mailbox info (ID, address, slug). Use to check if a mailbox exists.

Delete the project's mailbox (irreversible — drops all messages and webhook subscriptions). Requires confirm=true. If mailbox_id is omitted, resolves the project's mailbox.

Register a webhook on the project's mailbox. Receives POST notifications for email events (delivery, bounced, complained, reply_received).

List all webhooks registered on the project's mailbox.

Get details of a specific webhook by ID.

Delete a webhook. Idempotent — succeeds even if already deleted.

Update a webhook's URL and/or events. At least one field required. Events is a full replacement, not a merge.

Translate text to a target language. Requires service key and active AI Translation add-on. Supports optional source language and context hint.

Run content moderation on text. Returns flagged status and category scores. Free for all projects, requires service key.

Get AI translation usage for the current billing period — used words, quota, and remaining balance.

Send a message to the Run402 developers. Requires an active tier.

Register agent contact info (name, email, webhook). New or changed emails start operator email reply verification. Free with allowance auth.

Get the current agent contact assurance state: wallet_only, email_pending, email_verified, passkey_pending, or operator_passkey.

Start or resend the operator email reply challenge for the active agent contact email. Does not expose the challenge secret.

Email a short-lived Run402 operator passkey enrollment link to the verified contact email. Requires email_verified.

Create a Stripe checkout URL for your human to fund your agent allowance with a credit card.

View billing transaction history for an agent allowance address.

Update metadata (description, tags, visibility, fork_allowed) of a published app version.

Delete a published app version.

Inspect a specific published app — details, required secrets, fork pricing.

Set up agent allowance, request faucet funding, and check tier status — single-call bootstrap. Idempotent, safe to re-run.

Full account snapshot — allowance, billing balance, tier subscription, projects, and active project. Single-call overview.

Show local project details — REST URL, keys, site URL, and deployment info. Reads from local keystore only.

Set the active/default project in the local keystore.

Get anon_key and service_key for a project from the local keystore.

Send a passwordless login email (magic link) to a project user. Auto-creates the user on first verification. Rate limited per email (5/hr) and per project (by tier).

Exchange a magic link token for access_token + refresh_token. Creates the user if they don't exist. Token is single-use and expires in 15 minutes.

Create or update a project auth user with the service key. Can set project_admin and optionally send a trusted invite.