lavela MCP tools

The details behind the lavela MCP tool descriptions — each description links to one section here. What lavela does, and every tool with its cost, is on /info (for agents: /llms.txt). Prices: /pricing.

Connect

Add the server to any MCP client that supports remote servers with browser sign-in (OAuth) — nothing to paste:

https://console.lavela.dev/api/mcp

That URL gives the core tools — the "deploy this repo → operate it" journey: lavela.account_status, lavela.analyze_stack, lavela.launch_saas, lavela.list_projects, lavela.project_overview, lavela.connect_github, lavela.deploy_link, lavela.provision_compute_from_repo, lavela.compute_build_status, lavela.compute_rebuild, lavela.provision_hosting, lavela.get_status, lavela.redeploy, lavela.get_logs, lavela.check_health, lavela.set_compute_secret, lavela.set_build_vars, lavela.env_link, lavela.compute_lifecycle, lavela.compute_always_on, lavela.destroy_compute, lavela.provision_database, lavela.list_resources, lavela.provision_domain, lavela.diagnose_domain, lavela.provision_email, lavela.connect_stripe, lavela.create_checkout, lavela.topup_link, lavela.resume_compute, lavela.delete_project.

For every tool — ads, schedules (cron), preview environments, security scans, legal documents, volumes / object storage, one-off jobs and exec, pushing a private image, and the rest listed under Advanced tools — connect with:

https://console.lavela.dev/api/mcp/all

Sign-in is the same for both URLs (each is its own OAuth protected resource). To switch an existing connection, remove the lavela connector and add it again with the other URL. Claude Code keeps a connection in up to three places (user, local and project), and a leftover one — an old address, or an Authorization header from an old token — stops the browser sign-in from starting, so remove it from all three first (a line for a place with no entry only says so), then add it with the URL you want:

claude mcp remove lavela -s user
claude mcp remove lavela -s local
claude mcp remove lavela -s project
claude mcp add --transport http --scope user lavela https://console.lavela.dev/api/mcp

For every tool, end with this line instead:

claude mcp add --transport http --scope user lavela https://console.lavela.dev/api/mcp/all

npx @lavela/cli connect sets up Claude Code, Cursor, Windsurf and Claude Desktop with the core URL. A static token (Authorization: Bearer mcp_…), created in the console under Settings → Connect your agent → Manage connections → When you need a manual token, works on either URL.

What a connection can do. A browser sign-in, and npx @lavela/cli connect, give the connection every permission except adding funds (projects, provisioning, ops such as ads and security scans, and reading the balance); a manual token has only the permissions the user chose when creating it. lavela handles a request made within those permissions as the user's own request. The user can disconnect an app or revoke a token at any time under Settings → Connect your agent → Manage connections: a revoked token stops working at once, and a disconnected app's current access ends within about an hour.

When a core connection's result names a tool it doesn't have, its next_step.reason starts with "Advanced tool — not in this connection…" — ask the user to reconnect with https://console.lavela.dev/api/mcp/all. Start every new conversation with lavela.account_status. A connected client also lists a guided prompt, launch-my-app ("Launch my app"; in Claude Code type /mcp__lavela__launch-my-app, with the repo URL if known), that walks the first launch step by step.

Deploy from repo

lavela runs an app one of two ways. lavela.analyze_stack says which lane fits the app (its lavela field), and lavela.launch_saas — which creates the project — decides for this account in its deploy field and next_step:

A server is paid from the lavela wallet — confirm with the user before starting one (Money). Web hosting needs a funded account (not the welcome credit) but isn't charged to the wallet while it runs. launch_saas is not idempotent: a retry creates a second project, so check lavela.list_projects first.

Building a server from a repo. lavela builds on its own servers from GitHub — the repo's Dockerfile when it has one, otherwise an auto-detected build; the user needs no Docker. The call returns a buildId; builds usually take 3–6 minutes. Poll lavela.compute_build_status (each call waits up to ~20 seconds) until ok or failed and don't start another build meanwhile. Anything not passed gets the default: the repo root, the default branch, port 8080, no env — and a new server is 512 MB. On a redeploy, leaving size (or alwaysOn) out keeps what the running server has; passing it sets it (512mb shrinks a bigger server to 512 MB). Use gitRef for a branch/tag/commit and subdir for a folder of a monorepo. Multi-service: call once per service with a distinct service (web, api, worker) — e.g. the same repo with env {"SERVICE":"api"}.

Reading the repo first. lavela.analyze_stack also says, when it finds them: diskData — signs of a SQLite or file-based database, or of uploads kept on the server's own disk, which is wiped on every redeploy, restart and sleep (ask the user whether that data belongs in a database or on a volume before deploying); and readWarning — the repo could not be read (a wrong URL, or a private repo: connect_github), which is never answered as a static site. An app whose only database is its own Supabase project shows deploy.db: "none" and databaseConnection.migrationRequired: false: lavela keeps that project and creates no database for it, so there is nothing to migrate.

Server sizes. Every account can run the default size, 512 MB (512mb) — the only size on the free welcome credit. After the account's first paid top-up (and once the user has accepted the current Terms, which list the sizes), a bigger size, up to 8 GB (1gb, 2gb, 4gb, 8gb), can be chosen: on a deploy with the size parameter of lavela.provision_compute_from_repo, or in place for a running server with lavela.compute_set_size (an advanced tool — connect with https://console.lavela.dev/api/mcp/all; the server restarts once, no rebuild). A smaller size needs no top-up; before the user accepts the current Terms, only a change back to 512 MB is allowed (CONSENT_REQUIRED otherwise). A bigger size costs more while awake or always on: confirm the price with the user first, quoting a server that sleeps when idle as a range — its asleep price up to its always-on price, the most it can cost a month (Money). A running server's prices are in lavela.project_overview (asleepMonthlyUsd, capMonthlyUsd, with monthToDateUsd and awakeShare for this month so far), every size's on /pricing (and lavela.compute_estimate {size}, advanced — its monthlyUsd is the most the server can cost a month). Before that top-up a bigger size is refused — SIZE_NEEDS_PAID_TOPUP (TRIAL_ROUTE_UNSUPPORTED on the welcome credit): the user adds funds once, then call again. An account that got the welcome credit and whose paid top-ups were all refunded is back on the credit's rules: no bigger size and no growing a server until its next paid top-up (a server already running at a bigger size keeps running; redeploying it then meets the credit's limits). Redeploys and lavela.compute_rebuild keep a server's size; lavela.compute_set_size is the way to change only the size.

Private repos: lavela.connect_github gives a link the user opens once. Code that isn't on GitHub: for a project that already exists, an account with a paid top-up can use lavela.deploy_link — a one-time link (30 minutes, one per service) where the user connects GitHub or drags in the folder; the first call may answer CONSENT_REQUIRED — the user accepts the Terms at the link it gives, then call again. An account with only the welcome credit can't upload a folder (TRIAL_ROUTE_UNSUPPORTED, and a folder dragged in on that page is refused after it is packed): help the user put the code on GitHub first (they can create a repository there), then deploy that repo.

Ports. lavela sets PORT to the port it routes HTTPS to (default 8080). An app that reads $PORT needs nothing. An app that binds a fixed other port needs internalPort — setting only env: { PORT: … } changes the app but not the routing, and every request answers 502.

Environment variables and .env files. An app's variables are of two kinds, set in two places — and the agent never reads a .env value:

• Secrets (API keys, DATABASE_URL, a Supabase service_role key, tokens): lavela.set_compute_secret — encrypted and write-only (lavela never shows one back), reaching the server when it starts; see Secrets under Redeploy and rollback.
• Public build settings (names starting NEXT_PUBLIC_, VITE_, REACT_APP_, EXPO_PUBLIC_, NUXT_PUBLIC_, GATSBY_, VUE_APP_, NG_APP_, PUBLIC_ — the Supabase URL and anon key a web frontend's bundler bakes into the page every visitor downloads): lavela.set_build_vars — readable, never a secret, and used by the next build, so call lavela.compute_rebuild afterwards (confirm first: it replaces the running server). With no vars it returns the current set. An account that doesn't have it yet is refused with BUILD_VARS_UNAVAILABLE: the public values then have to be in the repo (for example .env.production, committed — never a secret key), since a build reads only what the repo commits and what set_build_vars stored. A page that loads blank usually means a public value is missing.

For the user's whole .env, call lavela.env_link {projectId}: it returns the way that works for this account to send it, with public entries stored as build settings and the rest as secrets — a command for the user to run in the project folder, npx @lavela/cli env push --project <id> (it prints variable names only and the user clicks Allow once in their browser; --dry-run shows the sorting without sending anything), or else a console page where they paste the file. Values travel from the user's computer or browser straight to lavela, never through the agent or the chat. If env_link has no route for the account yet, or for a single secret, set_compute_secret takes a value directly — it then passes through the conversation, so confirm with the user first. A deploy's own env is for non-secret runtime settings.

The disk is not permanent — see Persistent data.

Web hosting details. provision_hosting builds the frontend and adds a database when the app needs one. Build-time env (e.g. NEXT_PUBLIC_SUPABASE_URL + anon key) is stored encrypted on the project and reused by later redeploys — pass only what changes; it may be bundled into the browser, so never put server secrets there. subdir and branch are remembered ("" goes back to the repo root / default branch); a branch name containing "/" must be passed as branch, not as a /tree/… URL. Up to 600 files / 8 MB of build files are sent; optional files (images in public/, docs, tests) may be left out (filesTruncated: true), and a repo whose build files alone are bigger is refused with REPO_TOO_LARGE_FOR_HOSTING — deploy it as a server instead. Other failures:

"200 ≠ live." A finished hosting deploy can still serve an error or blank page: get_status shows the hosting module's verified: false with a verifyWarning. Before telling the user the app is live, open the URL or call lavela.check_health (it checks for a real page, not just any HTTP 200).

Nothing watches a server for you. Servers are not monitored, and no alert is sent if one goes down — don't promise the user one. A web-hosting site is checked every 15 minutes, and a change (down, back up) is sent to the project's Slack, Discord or JSON webhook channels (Operations → Notifications), never by email. For a server, call lavela.check_health when the user asks whether the app is up (it wakes a sleeping server, billed as awake time) and read lavela.get_logs.

Build status codes

lavela.compute_build_status returns building, ok (with the live URL) or failed. Its next_step always carries the fix; this table is the reference.

• ok with a non-empty error is a warning: the server was created but the app didn't answer on its port in time — usually a wrong port or a crash on start. Read lavela.get_logs before calling it live. A PORT_NOT_RESPONDING warning that ends in [detected-port: N] says the app's own files (a Dockerfile's EXPOSE, a literal listen(N) or port=N, a start script's -p N) show it listens on port N: make it listen on 0.0.0.0 and the port in $PORT, or deploy again with internalPort N — lavela never changes the routed port by itself. An error starting CERT_PENDING is only informational: the app works at the returned URL and the branded address is still getting its HTTPS certificate (a few minutes). CERT_QUEUED is informational too: the app works at the returned URL, and lavela issues its branded address later (a weekly limit on new certificates; checked every hour). PRIVATE_SERVER means a database or cache server (its port, e.g. 5432 or 6379) was deployed private by design: no public URL (url is null), and the note names the private address your other servers use while it runs. ok without a URL is therefore healthy for such a server: the result carries privateAddress (<app>.internal:<port>) and serverClass (database or cache), also when a readiness warning replaced the note — next_step then says to set DATABASE_URL / REDIS_URL on your other server to that address with lavela.set_compute_secret. A database or cache server is always on, and its always-on price is confirmed first: a new one deployed without alwaysOn: true, a request that would make one sleep, and a redeploy of one that sleeps are all refused with DATABASE_NEEDS_ALWAYS_ON, which states the prices.
• No buildId (a new conversation): pass projectId (and service) to get the latest build.
• rebuildable: true means lavela.compute_rebuild can repeat the build exactly.
• counted — whether this build counts toward the daily and monthly build limits: true while it runs and once its builder started, false for a build refused before its builder started and for one whose builder lavela's own build machine failed (BUILDER_OUT_OF_RESOURCES, inside the account's allowance of such failures). An error that says "does not count toward your build limits" always comes with counted: false.
• serviceSize, serviceAlwaysOn — the size and always-on setting the service's server runs with; with no server running, the ones lavela.compute_rebuild of that build would create it with (see Redeploy and rollback).

The build ran and failed:

The build was refused before it started — the builder never ran, so there is no build log and nothing in the code to fix; the fix is the account's (for SIZE_NOT_OFFERED, the request's):

Redeploy and rollback

A server built from a repo (after the user pushes, or once a failure is fixed): lavela.compute_build_status {projectId, service} returns the service's last build — pass its id to lavela.compute_rebuild. It repeats the build exactly (branch, folder, port, env, volume mounts) and fetches the branch again, so pushed code is included (a build pinned to one commit builds that commit again). The server keeps its current size and always-on setting — a resize or a switch made after the build is never undone. With no server running (it was removed, or lost), the rebuild creates it with the size and always-on setting it last ran; a build started after that server was removed, or for a service that never had one, uses its own — and on the welcome credit a removed server bigger than 512 MB comes back at the build's own size (512 MB when that is what it was built with). The build's serviceSize and serviceAlwaysOn say which. An always-on server pays its always-on price every second, while a sleeping one pays it only while awake (its asleep price otherwise), and a bigger size costs more while awake or always on (this server's prices: project_overview; all: prices) — say so when you confirm the rebuild with the user. To change only the size, lavela.compute_set_size (advanced) resizes the running server in place, no rebuild. Never redeploy with provision_compute_from_repo and guessed settings: whatever it is given replaces the running server — defaults for the rest, except the size and always-on setting, which it keeps when they are left out. To change only the port, the folder or the branch, pass internalPort, subdir or gitRef to the same compute_rebuild call (they are checked like provision_compute_from_repo's; "" for subdir / gitRef means the repo root / the default branch): everything else is repeated as above, the new build stores the change, and every later rebuild of that build repeats it — a failed build keeps it too, so rebuilding that one repeats the change. For env, use set_compute_secret / set_build_vars. When a build can't be repeated:

• DATABASE_NEEDS_ALWAYS_ON — the exception for a database or cache server (private; its private address never wakes a sleeping server): a rebuild of one that sleeps is refused before anything is queued or counted, with both prices — confirm the always-on price with the user, switch it on first (lavela.compute_always_on {alwaysOn:true}), then rebuild. One whose server was removed while asleep: provision_compute_from_repo with alwaysOn: true and the same repository, branch, folder and port (a rebuild never raises it silently). One that is already always on, or whose last server was, rebuilds as before.
• REBUILD_REQUEST_UNKNOWN — its settings weren't kept: confirm branch, folder, size, port, env and mounts with the user, then provision_compute_from_repo.
• UPLOAD_REBUILD_UNSUPPORTED — it came from an uploaded folder: a new deploy_link for the user to upload again.

A server whose last build says ok but that no longer exists (it was removed) is shown by lavela.project_overview as not_running — redeploy it with compute_rebuild (it comes back as the build's serviceSize and serviceAlwaysOn say — normally the size and always-on setting it last ran; uploaded code: a new deploy_link), never report the old URL as live. A server that exists shows as deployed with live: null: lavela's records can't tell a running server from one stopped by the user or a balance pause — check_health checks it, and compute_lifecycle action start starts a stopped one.

A reclaimed server: when a welcome-credit server's machine was removed (its balance ran out and it stayed stopped, or its owner left it stopped for a long time), lavela.project_overview and lavela.compute_list show it as reclaimed (state) with reclaimedAt, appDeletesAt and its old machineId. lavela keeps its settings, image and variables until appDeletesAt: lavela.compute_lifecycle {machineId, action:'start'} recreates it exactly as it was ("Start again": no build, nothing to repeat; it needs funds and is paid from the wallet) — use it before compute_rebuild, which rebuilds from source and counts as a build. After appDeletesAt the variables and the built image are deleted: a start then rebuilds from the repository (it counts as a build) and the result lists the variables to set again (variablesToSetAgain). lavela.resume_compute only lifts a pause; it never starts or recreates a server.

Web hosting: lavela.redeploy {projectId} rebuilds the same repo, folder and branch with the env stored on the project (CONFLICT = a deploy is already running). To undo a bad deploy instantly, lavela.list_deployments → lavela.rollback {deploymentId} (advanced tools) re-points the live site without a rebuild (web hosting only — confirm with the user; it changes what is live).

Secrets: lavela.set_compute_secret restarts the running server by default (a server at rest gets them at its next start; a one-off job or a build running at that moment keeps its old values); with apply: false the next deploy picks them up. A service name nothing runs under yet starts a new service: the result says createdService: true, and warns SIMILAR_SERVICE next to a close name (wbe for web), so confirm the name with the user. unset: ["NAME", …] removes names (the running server restarts; a name that is not set is a clean no-op that restarts nothing; the same name can't be in secrets and unset in one call). A name is capital letters, digits and underscores (at most 64, not starting with a digit), a value is at most 32 KiB, and a service holds at most 100. PORT, PATH, HOME, HOSTNAME, PRIMARY_REGION, FLY_* and LAVELA_* are set by lavela and the provider and are refused (VARIABLE_RESERVED): a server's port is internalPort on a deploy. A secret value that contains ${{ … }} is refused:

Read command audit history (lavela.compute_exec_history, advanced). Pass projectId, optional service (default web) and limit (up to 50). Returns only owned audit times, outcomes, exit codes and bounded byte/duration metadata; no command text, command output or credentials. It never runs a command or wakes a server.

Run a command in a server (lavela.exec_compute, an advanced tool). {projectId, service, cmd} runs a shell line (/bin/sh -c, at most 4 KiB) inside the service's server for up to 60 seconds; argv (the program and its arguments as a list, no shell) is for an image that has no /bin/sh. The result has exitCode, stdout and stderr — at most 64 KiB of each, then truncated: true (stdoutBytes and stderrBytes say how much there was) — and durationMs. It is free, but it only runs in a server that is already running: it never starts or wakes one and never keeps one awake. An account may run 10 commands a minute. On a server with a disk, or a database or cache server, a command can change data on the disk: confirm with the user first — dryRun: true answers (with that warning) without running anything or counting against the limit. lavela never returns a password, but a command run in your server can read its environment, so its output may show one; lavela keeps no command text and no output — each call leaves one audit record with a keyed fingerprint of the command, never the command. An account that only has the welcome credit cannot run commands yet (TRIAL_ROUTE_UNSUPPORTED).

Conditional service control refusals

Service control features require account availability and verified provider capabilities. A documented refusal does not mean a feature is enabled. No failed verification is treated as permission to expose a port, start a held server, or allocate paid resources.

Persistent data

A server's own disk is ephemeral: everything the app writes there — SQLite files, uploads, JSON/file stores, file sessions — is wiped on every redeploy, restart, and sleep/wake — tell the user so when a deploy goes live. An app that keeps any state needs one of:

• Managed Postgres — lavela.provision_database (a direct connection string, not the pooled one — the same string on a retry; lavela takes no backups — the database provider keeps only a short point-in-time history, so take your own dumps for long-term backups). wireToService stores DATABASE_URL on that server as a secret — it must name a server of the project that runs or is being built (a typo is refused with SERVICE_NOT_FOUND and creates nothing); the connection string is returned only when it was not stored on a server. Its region is fixed when it is created and the result says which (an EU-only account's databases are created in Frankfurt). It is free within these limits per database: 0.5 GB storage, 100 compute-hours and 5 GB of data transfer a month (past the compute or transfer allowance it pauses until next month; past the storage cap, writes fail). An account has a limit on lavela databases — a hosted app's own database and databases left by deleted projects count too (MANAGED_DB_LIMIT_REACHED names those, with the id destroy_resource takes). Calling it again with the same name (after a timeout, say) returns that database (adopted: true) instead of creating a second one; a name another resource or server of the project already uses is refused (SERVICE_NAME_TAKEN).
• Redis — lavela has no managed Redis: it creates no Redis databases. Use a Redis URL from the user's own provider (for example a free Upstash database under their own account) and store it with set_compute_secret as REDIS_URL. Or, on a funded account (not the welcome credit), run valkey or redis as the user's own server: provision_compute with a valkey/valkey or redis image runs it private and always on — no internet address, its always-on price confirmed first, its disk ephemeral like any server's (mount a volume if the data must survive restarts) — then set REDIS_URL on the app to its private address (compute_wire gives it).
• A volume — provision_volume, then mounts: [{volume: "vol_…", path: "/data"}] on provision_compute / provision_compute_from_repo (use the folder the app writes to). One volume belongs to one server and region and is not replicated, and lavela can't change its size later — pick enough. A redeploy that leaves mounts out keeps the attached volume (compute_rebuild keeps it too); a different set recreates the server. A volume is billed while it exists, also while its server is stopped or after the server is removed. Fly keeps a daily snapshot of each disk for up to 5 days by default (the create result states the number). It is not a backup service, and lavela cannot restore it for you — take your own dumps of data you can't lose.
• Object storage — provision_storage is disabled on most deployments (shared-key risk); use a volume or the database.

These need a funded account (not the welcome credit). Managed Postgres has no usage charge today — a per-account limit bounds it. On the welcome credit, or to keep the data with a provider of your own: Bring your own database.

When creating a disk or a database is refused (nothing was created or charged):

Reaching another service. All of an account's servers, in every project, share one private network. One server reaches another at <app>.internal on the port it listens on (compute_wire gives the address). That address answers only while the server runs: nothing wakes a server that sleeps when idle, or a stopped one, through it — so a database or an internal API that other services call must be always on (compute_always_on; it costs more — confirm with the user). The server must also listen on IPv6 (::): an app bound to 0.0.0.0 only can't be reached there. A one-off job or a build of that service shows up at the same address while it runs, so a connection can occasionally be refused — retry it.

Migrations: run_compute_job with the app's image — a job that outlasts ~180 seconds keeps running in the background on its own server, which stays billed (asleep once the job ends) until destroy_compute removes it; don't run it twice (pass the same idempotencyKey on a retry).

Bring your own database

Create a free Supabase or Neon database under your own account and set DATABASE_URL with set_compute_secret before or after your first deploy.

• Supabase: use the Session pooler connection (aws-…pooler.supabase.com:5432): it suits a long-running server and works over IPv4, while Supabase's direct host is IPv6-only. Use the transaction pooler (6543) only with ?pgbouncer=true (Prisma) or prepare: false (postgres.js, Drizzle): it does not support prepared statements.
• Neon: use the pooled connection string.
• Do not turn on an IP allowlist: lavela's outbound IPs are not static.

Set the whole connection string as the value: ${{ … }} references between services aren't available yet (REFERENCES_UNAVAILABLE).

Domains

lavela.provision_domain connects a domain the user already owns — lavela doesn't sell domains — and returns the DNS records to add at their registrar. target: "hosting" (default) attaches it to the web-hosting site, which verifies and gets HTTPS by itself once the records propagate. target: "compute" attaches it to a server (service, default web), which doesn't verify by itself — poll get_status. The app must be deployed first.

lavela.diagnose_domain checks each expected record against DNS and the HTTPS certificate, and returns a fix list in plain words:

The certificate is issued, not_yet (usually follows the records within minutes) or check_failed (couldn't check — try again). A common mistake: registrars that append the domain to the name themselves turn www.example.com into www.example.com.example.com — enter only www.

Email

lavela.provision_email sets up DKIM / SPF / DMARC on a domain the user owns (needs a funded account). Ownership is proven automatically when the domain is this project's live connected domain (provision_domain, DNS pointing at it) — its records are then published automatically. Otherwise the result carries an ownershipVerification TXT record: the user publishes it, then call provision_email again (nothing is set up for the domain until then), and publish the records it returns. lavela-owned domains (lavela.dev and subdomains) are refused. Poll get_status for verification.

send_email (advanced) sends from an address on that verified domain. Pass the same idempotencyKey on a retry so nothing is sent twice. EMAIL_DAILY_CAP: the daily limit is reached (lower for accounts under 14 days old; an account with only the welcome credit can't send email until a paid top-up) — wait for the reset. EMAIL_RATE_LIMIT_UNAVAILABLE: retry in a few minutes.

Email on the welcome credit. provision_email and send_email are refused there (TRIAL_ROUTE_UNSUPPORTED, action email_send) until a paid top-up. Meanwhile the app can send its own mail with the user's own Resend account: its API key set with set_compute_secret (for example RESEND_API_KEY).

Payments

lavela.connect_stripe lets the user's app take payments — confirm with the user first; it starts Stripe's identity checks (KYC, commonly 1–5 days). mode: "oauth" connects an existing Stripe account (it can be unavailable — then use mode: "new"); mode: "new" creates one with embedded onboarding. Poll get_status for the onboarding link and KYC state. If the user already has Stripe connected on another of their projects, mode: "new" answers status: "choice_required" with options and starts nothing — ask whether to reuse one (reuseAccountId) or create a separate account (forceNew: true). A revoked Stripe module means payments are broken until reconnected.

lavela.create_checkout creates a Checkout link for the user's customers. The charge runs on the user's connected Stripe account and settles to them in full — lavela takes no per-charge fee and is not the merchant. It needs KYC complete. amountCents is the smallest currency unit (1999 = $19.99) — except zero-decimal currencies (JPY, KRW, VND, CLP and the others Stripe lists), where it is the raw amount (5000 = ¥5,000). Getting this wrong overcharges real customers about 100x and Stripe can't catch it: confirm the price and currency with the user first. mode: "subscription" with an interval makes a subscription. Pass an idempotencyKey when retrying.

Money

• What a server costs. A server that sleeps when idle is billed by use, by the second (pricingModel: "asleep_awake" — the current Terms' pricing): its size's asleep price while it sleeps and its always-on price while it is awake — so never more than kept always on. Quote it as a range, asleepMonthlyUsd to capMonthlyUsd (the always-on price, the most it can cost a month), never as one monthly price; monthToDateUsd is what it has cost so far this month and awakeShare the share of its billed time this month billed at the awake rate — awake, or kept always on. awakeShare is null while the pace is not known — until the server has a day of billed time this month, and for the rest of a month in which its service ran before its current prices applied (a server it replaced included) — and estMonthlyUsd is then its always-on price, not a pace (when the month can't be read, monthToDateUsd and awakeShare are null and estMonthlyUsd is the always-on price). compute_status gives the account's monthEstimateUsd and monthMaxUsd: monthly rates of the servers billing now, not this month's total; its paceUnknown is true when monthEstimateUsd counts a sleeping server at its always-on price for want of a pace. It wakes on any request and sleeps again a few minutes after the last one, so something that calls it every few minutes (an uptime monitor, a polling client) keeps it awake all month at the always-on price — then suggest always on: the same price, no start-up delay. An always-on server pays its always-on price every second. An account that has not accepted the current Terms (pricingModel: "flat") is billed under the Terms it accepted: a flat monthly price per server, sleepingMonthlyUsd, which is null under asleep_awake. One-off jobs and schedules are billed at the smallest size's always-on price while they run. A one-off job still running after ~180 seconds goes on in the background on its own server, which stays billed (asleep once the job ends) until destroy_compute removes it.
• The wallet. Servers, one-off jobs, schedules and volumes are paid from the user's prepaid lavela wallet. Prices: /pricing. lavela.account_status has the balance and what can start (canUse) — decide from canUse and wallet, not billingMode (an account-level label that can read "legacy" on a wallet account). Top-ups happen in the console (lavela.topup_link) — an agent never takes card details or moves money; saving a card doesn't charge it by itself. Cards issued in the US or Canada pay lavela directly; cards from other countries (Korean cards, Kakao Pay, Naver Pay and others) pay on the same page through Stripe's Link checkout, which sells the credit and adds local tax on top. Automatic top-up needs a US or Canadian card.
• The free welcome credit. An eligible new account gets it once (one per person), automatically, when the user accepts the Terms and has confirmed their email — no card needed. Mention it only when account_status shows trial.claimable (an account that already has it, or cannot get it, does not). It covers one 512 MB server built from a GitHub repo (the default size — every app deploys that way on the credit, a web frontend too) and its secrets; bigger sizes need a paid top-up (Deploy from repo). While the account has only the welcome credit its builds are limited too — 20 a month for the whole account, each up to 10 minutes (BUILD_MONTHLY_LIMIT_WELCOME once the month's are used; a longer build fails BUILD_TIMEOUT). Web hosting, databases, schedules, one-off jobs, volumes, uploads, email, ads and previews need a paid top-up — any top-up lifts every trial limit, the build limits included.
• When a lane is closed on the welcome credit (TRIAL_ROUTE_UNSUPPORTED; its params.action names the lane, and the error's user_action says the same), a paid top-up opens it. Meanwhile: web hosting → deploy the repo as a server with provision_compute_from_repo, which takes every app on the credit; a preview environment → deploy the branch to try as the trial's server (provision_compute_from_repo with gitRef, or compute_rebuild with gitRef once a server runs — that replaces the running server, so get the user's OK); error tracking → a free Sentry project under the user's own account, its DSN set as SENTRY_DSN with set_compute_secret (the app needs Sentry's SDK, which the user's own coding agent adds — lavela never edits their code; get_logs meanwhile); analytics → the user's own Plausible or Google Analytics snippet in the app; a database → a free Supabase or Neon database as DATABASE_URL (Bring your own database); email → the app sends with the user's own Resend account, its key set with set_compute_secret (for example RESEND_API_KEY). Scheduled jobs have no alternative on the credit yet.
• When the free credit is used up, the server keeps running until trial.graceEndsAt (also wallet.graceEndsAt) and then stops unless the user adds funds. That grace is free — it doesn't become a debt.
• When a paid balance runs out, running servers keep running until wallet.graceEndsAt at the latest; the usage until then becomes a negative balance (wallet.debt) taken from the next top-up. Once that unpaid amount grows beyond its limit (Terms Section 7.1; the amounts are on /pricing), the servers stop right away instead — compute shows the pause (reason wallet_low_balance) and wallet.graceEndsAt moves to that moment — so never promise the user the full grace. Either way nothing new — builds, redeploys, jobs, volumes, starts — runs until a top-up brings the balance above zero, and after that time the servers stop.
• After a top-up the pause lifts once the payment settles (if the balance already covers it but compute is still paused, lavela.resume_compute lifts it now). Stopped servers stay stopped until started — compute_lifecycle action start with the machine ids from project_overview.
• Ads. The ad spend itself is on the user's own card at each platform; lavela charges a management commission, to the user's card once a month, on the ad spend in the ad account it set up for them — every campaign in it, including any they run there themselves (see /pricing).
• The user's sales settle 100% to them via Stripe Connect.

Destructive actions

Before any of these, show the user the exact target — the project's name, the server, the resource — and wait for their confirmation.

lavela itself requires a few confirmations in an agent's request, and you cannot skip them: delete_project needs the project's exact name in confirmName (a mismatch is refused); ads_launch and ads_set_budget need the daily budget repeated (confirmDailyBudgetCents, confirmNewDailyBudgetCents); destroy_resource on a hosted app's live database needs confirmHostedAppDatabase: true; and only the user can accept the Terms (in the browser), add funds and turn on automatic top-up (in the console). These requirements only make sure the request repeats the target or amount; they show the user nothing. lavela adds no other confirmation prompt to your requests, so the confirmation above is yours to get.

Four advanced tools are also marked destructive in the tool list, so an MCP client asks before each call: exec_compute (a command can change a server's data), run_compute_job (a job changes data and is billed), ads_launch (a live campaign spends real money daily) and send_email (a sent email cannot be recalled). Confirm the exact target with the user — the server and command, the daily budget, the recipients — before calling them.

Advanced tools

Connect with https://console.lavela.dev/api/mcp/all (Connect) for these: lavela.trial_claim_link, lavela.ping, lavela.capabilities, lavela.list_templates, lavela.configure_service, lavela.link_services, lavela.volume_extend, lavela.volume_snapshots, lavela.template_status, lavela.template_rotate, lavela.template_upgrade, lavela.template_lifecycle_status, lavela.compute_exec_history, lavela.volume_restore, lavela.public_port_link, lavela.egress_ip_link, lavela.compute_status, lavela.compute_list, lavela.compute_estimate, lavela.provision_compute, lavela.push_image, lavela.compute_set_size, lavela.compute_wire, lavela.run_compute_job, lavela.schedule_create, lavela.schedule_list, lavela.schedule_update, lavela.schedule_delete, lavela.schedule_run_now, lavela.preview_list, lavela.preview_destroy, lavela.preview_webhook_setup, lavela.exec_compute, lavela.provision_storage, lavela.provision_volume, lavela.destroy_resource, lavela.send_email, lavela.billing_setup_card, lavela.archive_project, lavela.unarchive_project, lavela.compliance_generate, lavela.compliance_list, lavela.security_scan, lavela.security_scan_status, lavela.list_security_scans, lavela.provision_error_tracking, lavela.get_errors, lavela.daily_brief, lavela.list_deployments, lavela.rollback, lavela.ads_platforms, lavela.ads_draft, lavela.ads_launch, lavela.ads_status, lavela.ads_pause, lavela.ads_provision_account, lavela.ads_assets_push, lavela.ads_setup_tracking, lavela.ads_report, lavela.ads_conversions, lavela.ads_set_budget, lavela.ads_commission.

• Images and servers. provision_compute runs an image already pushed to a registry (lavela doesn't build it); push_image gives the user a command to push a private one (npx @lavela/cli@latest push <image> --project <id>): their browser authorizes a one-hour push key for that one image repository, revoked when the push ends — no key or password passes through the agent — and the CLI prints the registry.lavela.dev/… ref to pass to provision_compute. No agent or user ever gets a hosting-provider credential. If lavela's image registry is switched off, push_image and repo builds answer REGISTRY_UNAVAILABLE (lavela's side; nothing is started or counted) — retry later. Calling provision_compute again for the same service redeploys its server (that call's image, env, port and checks replace the old ones; size, always-on and volumes are kept when left out), and its URL isn't readiness-checked; its checks don't hold back traffic. compute_list lists servers with their ids, sizes and prices (for a server that sleeps when idle: asleepMonthlyUsd, capMonthlyUsd, monthToDateUsd, awakeShare and estMonthlyUsd, this month's pace); compute_status shows limits and usage (on a wallet or trial account its account block is what counts — tier and spend-cap fields are legacy). exec_compute runs a command of up to 60 seconds inside a running server; run_compute_job runs one on a temporary small server (a job past ~180 seconds keeps running in the background, and its server stays billed until destroy_compute removes it — don't re-run it). compute_estimate quotes a spec.
• Schedules. schedule_create runs a command on a standard 5-field cron in UTC, at most every 5 minutes, 20 per project; a firing still running makes the next one skip. Each firing is billed. Its env is stored for the schedule's lifetime — never put secrets there. schedule_list outcomes: skipped_balance (the wallet ran out; resumes after a top-up), skipped_refused (nothing ran or was charged — lastError is CODE: what to do: accept the Terms, lavela paused new paid services, contact support, or the org guard's ORG_CAPACITY_REACHED (lavela is at capacity and has been alerted), TRIAL_CAPACITY_FULL (free trial servers are full: add funds) or ACCOUNT_MACHINE_LIMIT (the account's machine limit); the schedule stays on and each firing is checked again at its time), skipped_dispatch_error (a passing hiccup, not a job failure), skipped_paused, skipped_capped.
• Preview environments. Created automatically for pull requests once the user adds the GitHub webhook from preview_webhook_setup (its secret is shown once). Web-hosting projects only, and previews get no client env — an app whose database lives outside lavela fails them with DB_ENV_MISSING. They are removed when the PR closes (preview_destroy removes one early).
• Security scans. security_scan checks npm lockfiles for vulnerable dependencies and the repo for committed secrets; poll security_scan_status. Always relay secrets[]; only status ok with no secrets is a clean result. A private repo is scanned only when the server's own GitHub access can read it (clone_failed otherwise).
• Legal documents. compliance_generate drafts a privacy policy, terms and a cookie banner — not legal advice; model: "stub" means a basic template.
• Ads. Drafts for 10 platforms; lavela launches through the API only on Google (Search network) and Meta, where their credentials are configured (Meta also needs App Review) — everything else is a guided handoff the user finishes in the platform. Launching and budget changes echo the agreed daily budget (confirmDailyBudgetCents); a live campaign spends daily on the user's card until ads_pause. ads_commission is metered from Google API spend only and can under-report.

Errors and support

A tool error is { "error": { "code", "reason", "actor", "message", "user_action"?, "say"?, "docs_url", "retry_after_ms"? } }. Most carry user_action: do what it says first — the fix is usually self-serve (a link the user opens, a retry, another tool) — and don't retry in a loop when the user must act first. When it is missing, use the table below; a malformed call can also fail with a protocol error outside this shape.

• reason is the specific cause, such as TRIAL_SERVER_LIMIT_REACHED or CONSENT_REQUIRED — the same as code when there is nothing more specific.
• say, where there is one, is a plain sentence for the user, kept apart from user_action (what you do) — relay it in your own words.
• docs_url is the section of this page (or the console page) that explains the code; the support page only where contacting support is the fix.
• actor says who has to act: agent (change the call, use another tool, or wait and retry), user (accept the Terms, add funds, confirm, reconnect or contact support) or lavela (a problem or limit on lavela's side — retry later; if it persists, contact support).

CONSENT_REQUIRED: the user accepts the current Terms at /consent — once, and again when a new version requires it — then retry. A missing permission (scope): reconnect to refresh it — or, for a static token, the user creates one that has it (Manage connections).

Still stuck? Email support@lavela.dev or open /support — a person reads it, not a bot.