MCP (Model Context Protocol)

Quave ONE MCP lets an AI client work with your Quave ONE account through a remote, authenticated MCP server. Ask your client to inspect logs, review a deployment, manage an environment, or run an approved Job without giving it unrestricted access to your infrastructure.

AI client → Quave ONE MCP server → Quave ONE API → your account resources

The MCP server validates identity, capabilities, account permissions, and tool-specific rules before an operation reaches the Quave ONE API. Results return to the AI client as MCP responses.

Autoscaling defaults and historical results

update-app-env-scaling-options preserves existing values for omitted fields and fills missing enabled-autoscaling settings with the same defaults as the dashboard. See Scaling Options. Explicit zero windows and memory-only policies are preserved.

get-app-env-history reports the historical lifecycle result at each activity, not the content's latest status. A failure remains a failure after recovery. Use statusTimestamp for the original event time shown in dashboard Activities and timestamp for activity pagination/filtering. Missing historical evidence is null, not success. See History API.

get-app-env-pods returns only the pods that are currently running. Pass includeFinished: true to also get the 50 most recently finished pods; they report Terminated (or Failed/Succeeded) with a non-null finishedAt. See Pods API.

Discover app types before creation

Use list-app-presets before create-app. It includes Functions (isFunction) and Jobs (isJob) as well as ordinary framework and Custom presets. requiresDockerfile applies to source builds; pre-built images do not need one. Use list-database-presets for managed Databases & Services.

For Functions, the MCP idle-period input floor is 300 seconds, but the account minimum defaults to 900 and raises lower values. On upgraded operators this is minimum last-pod retention after the autoscaler decides to scale to zero, not an exact timer from the last request. update-app supports App/Function type conversion without changing image/source mode. Do not interpret a successful configuration save as proof of timeout enforcement or safe migration of a protected custom-domain app: read the current Function limitations.

Delete owners with Disaster Readiness

Deleting an owner with Disaster Readiness also retires its owned recovery VM, boot disk and allocated public IP resources. Deletion remains pending until the provider confirms cleanup; retry the same delete if it reports pending. Cleanup continues asynchronously and its ownership journal is preserved. The regional pool and other targets are unchanged. Recovery data disks are retained separately, so compute cleanup does not mean all storage charges have stopped. Deleting only the original source preserves an independently recovered Live environment; deleting that recovered environment itself or its account retires its VM.

Delete a Warren factory

Use the ordinary app/environment deletion tools. Prevent destroy is checked before credentials or workloads are touched. App deletion revokes its Warren execution credentials and stops all app-owned sandboxes; deleting only the control environment stops only its service-principal workloads. Unrelated apps and sibling environments are preserved. Pending or failed runtime termination reports a retryable deletion failure rather than claiming cleanup succeeded; retry deletion once stopping finishes. An app whose deletion has started cannot admit new sandboxes. Revoked identities and terminal sandbox/revision history are retained for audit, without execution access.

Allocation ownership is recorded before requesting runtime resources. Deletion stays pending while that request is in flight, even after a worker lease expires. An ambiguous allocation result (for example, a lost connection after submission) remains fenced instead of being redispatched or reported as deleted. If stopping does not converge, contact support for runtime reconciliation; repeatedly retrying deletion does not clear this safety fence. Environment deletion also fences new service-principal work for that environment.

If create-solution loses its response (for example, a proxy 502), call it again with the same arguments. A 409 result returns the installationId of the unfinished install, or reports that it is still running; retry with that ID to resume. Deleting the factory's App also removes its installation record.

Update an existing Warren factory

Unsupported inputs.warrenImage values are rejected before registry access or resource creation. The validation message explains the supported latest, numeric Quave version, and immutable digest formats for ghcr.io/quavedev/warren.

Use create-solution with the existing installationId and unchanged account, name, environment, region and provider selection. An explicit inputs.warrenImage requests an in-place upgrade of both control and approved sandbox images without replacing the factory's data or credentials. Omit that input to leave a completed installation unchanged. Wait for current runs to finish, then verify get-app-env-status reports a successful deployment before starting a new run.

Choose how to connect

Method	Best for	How it works
OAuth	Clients that support remote MCP OAuth	The client opens Quave ONE consent and receives its own scoped tokens.
MCP key	Existing integrations or clients without OAuth support	You create a separate key and configure it in that client’s Authorization header.

OAuth is the recommended connection method. MCP keys remain supported unless an account administrator enables Require OAuth for automated API and MCP access for that account. That setting affects automated credentials only; it does not affect dashboard sign-in.

An MCP key can be limited to chosen accounts with Limit accounts (off by default). Every tool call to any other account is then rejected, including for Quave internal operators; see Limit accounts.

An MCP key can also be restricted to one account and some of its apps, regions and sandbox templates. Set it with create-mcp-key or update-mcp-key; see Restrictions. MCP keys work only through MCP; for direct Public API calls use an API token.

Agents can also run in Agent Sandboxes with your personal AI subscription (create-ai-subscription, then aiSubscriptionId on a command in a private sandbox). Only you can use it; see Private sandboxes and personal AI subscriptions.

Start here

1. Connect your client with OAuth or an MCP key.
2. Choose server-enforced authorization: capabilities, or an explicit MCP tool allowlist for OAuth grants and MCP keys.
3. Apply safety best practices, especially before giving an agent access to production.
4. Review available tools and use least privilege.
5. Keep management, troubleshooting, and FAQ handy.

What Quave ONE enforces

The server enforces the authorization grant or key configuration, Quave ONE account and environment permissions, and tool-specific checks. Client-facing confirmation prompts and approval-session duration are helpful UX safeguards, but depend on the MCP client.

Security Best Practice: Grant only the access shape you need. Use By permissions for capability-scoped access, or By tools when you want an explicit MCP tool allowlist. The server blocks every other operation regardless of how the MCP client is configured. Read Safety best practices before connecting an agent to production.

patch-json-env-var requires account admin permission and both quave:write:config and quave:read:secrets capabilities, even for plaintext JSON. Selecting the tool does not bypass account permissions. Only the target variable is decrypted; unrelated secrets remain encrypted. Secret-processing failures return a safe 500 rather than an admin-permission 403.

list-nodes, get-node-metrics-series and the node pool tools (list-node-pools, get-node-pool, update-node-pool-scaling, update-node-pool-power, update-node-pool-disk-autogrow, update-node-pool-node-power, grow-node-pool-disk) are Connect tools. They appear in the tool list, the MCP key tool picker, and the OAuth tool picker only when you belong to at least one Connect account. Calls still check that the requested account is a Connect account with that private region enabled; node pool changes also need an account admin. To ask why a pool does not scale down, use get-node-pool: it returns the autoscaler's last decision, the CPU and memory averages it measured and the thresholds it compares. See Node pools and autoscaler.

For API automation that is not MCP, use the Public API instead. OAuth tokens are resource-bound: an MCP token can only open MCP sessions, and a Public API token can only call the Public API.

get-app-env-backup-overview calculates freshness from the newest valid full or incremental snapshot, not just the chain creation date. Chains without usable entry timestamps fall back to their creation date. The stale threshold remains 48 hours.

update-app-env-snapshot-options accepts fullSnapshotPeriod (EVERY_DAY, EVERY_7_DAYS, EVERY_15_DAYS or EVERY_30_DAYS) next to snapshotFrequency; an omitted option keeps its stored value, and snapshot option responses return fullSnapshotPeriod. See Full snapshot period for the restore-time and retention trade-offs.

list-app-env-backups returns logical database backup metadata together with databaseBackupDisabled and backupListingUnavailable. When logical dumps are intentionally disabled and historical storage cannot be listed, it returns an empty backup list with both fields set to true; clients should treat that as an explicit opt-out, not a missing-backup finding.

get-account-security-posture is a read-only, deterministic security review of an account and an explicit list of environments you consider production or critical. Account checks are account-wide; environment checks cover only the selected environments you can see. Treat unknown, unavailableChecks, and notEvaluatedChecks as gaps in visibility, never as compliance. It never returns secrets and never changes anything.

list-agent-profiles returns the full library catalog, including each profile's publishedAt timestamp for its current published revision. For newest-first suggestions, filter for eligible profiles without an enabledAutomation, sort by publishedAt descending, then limit the results. A profile with requiresExplicitEnvironmentScope: true must be enabled with at least one appEnvIds entry; an empty selection is rejected.

For Job automation, run-app-env-job creates customer-visible JobRuns and list-app-env-job-runs returns a paged list. Use page and limit for pagination, status for one status or comma-separated statuses, and from / to for createdAt time filters.

The dashboard keeps Job execution settings under Settings → Job Config and recurring timing under Settings → Schedule. For recurring Jobs, update-app-env-job-schedule configures or disables one exactly five-field cron schedule on a Job environment, and get-app-env-job-schedule returns the next time plus recent scheduled, skipped, failed, or missed occurrences. Schedule updates take effect immediately and remain separate from pending Job execution config. Accepted occurrences create normal SCHEDULED JobRuns and Kubernetes Jobs, not a Kubernetes CronJob.

For actual CPU or memory usage by replica, call get-app-env-metrics-series with groupBy: "pod". The response returns seriesByLabel and summaryByLabel keyed by pod name, for both regular apps and managed databases. Omitting groupBy preserves the aggregate environment response.

The same grouping is available for anomaly summaries. Pass groupBy: "pod" to get-app-env-metrics-baseline-summary or get-account-observability-summary; each metric then returns baseline, recent, and deviation statistics under summaryByLabel for every pod.

For a fleet sweep on a large account, pass compact: true to get-account-observability-summary. Each metric then returns only baselineP95, recentP95, recentMax, and zScore, and the shared windows appear once at the top level.

For MongoDB databases managed by Quave ONE, analyze-app-env-mongodb-queries reads the profiler (operations slower than 100 ms by default) and returns the costliest query shapes with findings, suggested indexes and unused indexes. Every value is redacted to its type, and the tool only runs profiler and index-metadata commands, never reads of your collections. See the MongoDB Query Analysis API.

For distributed tracing (OpenTelemetry → Tempo), use search-app-env-traces to find failing or slow requests of an environment by status, minDuration, spanName, httpRoute, minHttpStatusCode or kind, then open one with get-app-env-trace to read its spans, timings, errors and key attributes. Tracing must be released for the account and enabled on the environment with update-app-env-tracing. Searches default to the last hour and are limited to 6 hours per call, so narrow the window instead of scanning long ranges. See the App Environment Traces API.

update-app-env-resources can increase the disk allocation after it has been applied for managed databases and regular apps with a local persistent volume. Disk decreases are rejected because persistent volumes are grow-only. Shared NFS volumes and stateless apps do not use this disk setting. Use list-database-presets for the current managed-database min/max limits. For eligible Quave ONE Direct environments, storage overage uses this configured local disk allocation, including regular apps with a local persistent volume.

To grow that disk automatically, use update-app-env-storage-autoresize (scope quave:write:config) on a managed database or a regular app with a local persistent volume. Send enabled, the required maxDiskMb (at most the account disk limit) and optionally triggerUsedPercent, minFreeGb, stepPercent, minStepGb and cooldownMinutes; call it with dryRun: true first to preview the validated policy. Grows are permanent and, on Direct, increase the billed disk. get-app-env returns the policy and its lastAction in storageAutoResize; a block at the maximum adds lastAction.maximumCode (POLICY_MAX, NODE_POOL_LIMIT or ACCOUNT_LIMIT), and account admins are emailed. See Disk Autoresize.

For a managed MongoDB with Search enabled, update-app-env-resources also takes databaseSettings.mongodb.search to size MongoDB Search: resources.zClouds (1, 2, 4, or 8 per replica), replicas (1 to 3; values above 1 apply once the region supports them, and the console does not expose this field yet) and storage (MB, grow-only, default = the database disk). create-app-env accepts the same fields at creation, and get-app-env returns them. Search is billed as its zClouds × replicas plus its disk.

For alert replication, use copy-alert with sourceAlertId and one to five exact destination cliEnvName values in targetEnvNames. The server reads the source alert, reuses its condition and contact points, creates a unique rule name per target, and reports each destination separately. Use create-alert when defining a new condition instead. list-contact-points returns status (ACTIVE or PAUSED); a paused Slack destination stays unused until it is updated and saved.

create-alert and update-alert accept the disk_usage_percent metric: the used space of the environment's fullest persistent volume, in percent (default threshold 85). It is accepted only for a database with storage or an app with a local volume; any other environment, including one on a shared volume, is rejected with an error.

When checking deployment progress with get-app-env-status, use currentDeployment for the content version currently attached to the environment and latestDeployment for the newest build or deploy activity. For source deploys, latestDeployment.status can be BUILDING before that version becomes current. CLI source deploy content can also expose latestDeployment.uploadEventId so tooling can correlate polling with the exact upload event.

Disaster readiness setup and status

Dashboard usage for account owners is documented in Disaster Readiness. The tools below follow the same readiness rules; a successful tool call is not Disaster Ready.

list-disaster-readiness-points lists current-generation retained candidates with explicit cutoffs and optional retained source sizing; availability and target capacity still require verification. Warm protection lists its configuration-owned validated point from the original receiver, including a protected incremental point rather than always the seed. Missing or ambiguous custody does not produce a selectable warm point. Warm Data until and RPO use retained destination evidence, never a newer source-only snapshot notification. The dashboard's cold snapshot chooser can validate an explicit full or incremental point before exposing it to the existing retained point activation contract; MCP request shapes remain unchanged. Status may also include warmValidationOperationId for check-only eligibility. A fully cleaned failed check can permit another isolated check while recovery remains blocked. The server verifies retained cleanup and receiver ownership; this hint is neither successful data validation nor Disaster Ready. New clients prefer this hint for checks; the recovery hint remains separate. A historical failed check no longer blocks recovery permanently after its cleanup is verified and a later check succeeds for the protected point. A failed latest check, pending operation, or unverifiable cleanup still blocks recovery; normal activation evidence and custody checks remain mandatory.

Status may advertise a matching warmRecoveryOperationId for a settled warm sync owner. With an established validation schedule, that hint also permits requesting a fresh isolated warm check using a new request ID. Append, check, resize and activation remain serialized: both actions recheck the lease and journal atomically. The receiver remains the active owner; the check response identifies a separate attributed request. Retry an uncertain response with the same request ID and generation. Neither action admission is a Ready claim. activate-disaster-readiness submits one selected point using a stable request ID and explicit user acknowledgment of source double-writing risk. Requires account admin and both deploy/dangerous capabilities (or that tool's explicit grant). Never infer acknowledgment or select a point silently. Admission is not recovery success; follow operation status. No DNS switch/customer application start is implied. Live recovery remains under staging qualification. See the activation contract.

discard-disaster-readiness-activation discards an activation that has not become live (the dashboard Discard action), so a stuck activation stops blocking reset-disaster-readiness or a new activation. Supply the configuration ID, its activeOperationId, current generation, a stable request ID and discardAcknowledged: true only after the user explicitly agrees. Requires account admin and both deploy/dangerous capabilities (or that tool's explicit grant). Succeeded or live-handoff activations, and activations that have not reached promotion yet (except a cold one that keeps failing there), are rejected (status canRequestDiscard). The receipt starts cleanup; poll status until it finishes. No dryRun parameter. See the discard contract.

Use list-disaster-readiness-sources for eligible volume environments and suggested settings, and list-disaster-readiness-configurations for current readiness and failure reasons. Both are account-scoped, member-filtered and paginated.

DR destinations come from configured DR-labeled regional node pools, including pools with zero VMs. There is no separate region-enable flag. The same account and volume eligibility checks apply in the dashboard, REST API and MCP. Inactive VMs inherit the pool's compute defaults at 12.5%; validation never raises their CPU baseline. Activation vertically scales the selected VM and confirms 50% before live handoff. Pool availability alone does not prove recovery readiness.

configure-disaster-readiness accepts a reviewed bulk selection with stable per-environment request IDs. It requires account admin permission plus both quave:write:config and quave:write:deploy capabilities. Preparation can allocate billable resources; confirm selection, settings and warnings before submitting. Inspect every item result and poll status—acceptance is not recovery completion. Warm items must include target with the recovered envName (and appName for databases); cold items may include it to save the names for activation. No live promotion or dry-run is exposed by this tool. See the DR API contract.

DR configure, validate, activate, discard and reset tools do not support a dryRun parameter or preview call. Review the selected settings, costs and warnings before confirming the actual request; confirmation and authorization requirements still apply.

MongoDB restore validation remains available, but Activate as live is not supported yet. Configuration status reports activationUnavailableReason; activation requests are rejected before changing ownership or targets.

validate-disaster-readiness-now requests an isolated validation after initial enrollment. It requires account admin permission and quave:write:deploy, can allocate temporary billable resources, and leaves source traffic and normal snapshot/validation schedules unchanged. Supply the current configuration ID and generation plus a stable request ID; reuse them after an uncertain response. Poll status/evidence: the operation receipt is not validation success or Disaster Ready. It does not activate a live target and has no dryRun parameter.

Inactive validation uses a bounded standby engine budget without growing the VM. Live activation separately verifies workload-sized compute and 50% baseline; validation success alone is not proof of live capacity.

reset-disaster-readiness wipes Disaster Readiness for one environment or the whole account. It requires account admin permission, both deploy/dangerous capabilities (or that tool's explicit grant), and the exact environment or account name. Confirm the name with the user first. It deletes configuration records and leftover recovery destinations still owned by those settings. It does not delete the live source or a destination that already became live. There is no dryRun parameter. Reset waits for exact owned compute cleanup, including unfinished allocations. A pending cleanup keeps its configuration and operation records; retry the same confirmed reset. Data disks retain their existing retention policy. Regional pool settings and other targets are not reset.

Image environments and snapshot restores

Image-based environments deploy their environment-level image directly; creating one does not require a Git branch or CLI source upload. create-branch-preview initially copies the source environment image; its branch is preview metadata, not an image selector.

create-app-env-from-volume-backup always requires a non-empty target.envName. Database restores always create a new App and also require target.appName; other applications can set target.createNewApp: true and provide target.appName, or stay in the source App by default. Database additional services are not copied. It restores volume data into a separate environment using the source's current image and runtime configuration, including encrypted environment variables. It starts with one container and autoscaling disabled, without copying custom hosts or shared NFS claims. Variable values and callback URLs are not rewritten. A missing source image is rejected before target creation. See snapshot restore semantics.

Snapshot validation evidence

Active DR configuration owns the source snapshot cadence and storage across normal deploys; ordinary snapshot edits do not override it. Logical database dump settings remain independent. DR snapshot intervals must be exactly representable by the CSI schedule; unsupported intervals fail rather than being rounded.

Restore/validation preflight verifies the selected chain and uses its original encryption key, including a retained historical key after rotation. Missing or ambiguous keys and mixed-key chains are rejected; preflight alone does not prove data recovery. See snapshot validation failures.

list-app-env-backup-validations and snapshot-overview tools expose the same safe run evidence as Snapshots: requested depth, executed/skipped/unknown checks, real operator timestamps where recorded, restore progress, and separate cleanup status. The tool identifiers retain backup for compatibility; this flow validates volume snapshots, not logical dump backups. A successful snapshot validation is not Disaster Ready or a DR Check. See validation evidence and limitations.

Agent Sandbox egress restrictions

For Agent Sandbox templates, create-sandbox-template-revision accepts networkControl with independent address and domain triggers. enabled:true requires a non-blank address allowlist. For domain-only restrictions, use enabled:false with a non-empty domainAllowlist; this still enables the egress proxy. See the sandbox revision API for examples and validation boundaries.

Agent Sandbox retries

Sandbox creation deduplicates the full account, app, caller and idempotency-key tuple, including while the first sandbox is still starting. If the database uniqueness prerequisite cannot be established, creation fails instead of allocating a duplicate. See the Sandbox API.

A paused sandbox resumes on its own: execute-sandbox-command, start-sandbox-command and a repeated create-sandbox with the same idempotency key start the resume. While it is still resuming, or the runtime agent is still restoring a SNAPSHOT workspace (AGENT_UNREACHABLE), the tool returns a retryable error with retryAfterSeconds; call it again after that delay. resume-sandbox stays available.

Agent Sandbox long-running commands

execute-sandbox-command holds one request open for at most 900 seconds. For longer work, start-sandbox-command returns an executionId at once and the command keeps running for as long as the sandbox lives. Read it with get-sandbox-command: pass the returned nextSeq as from to get each output event once, and waitSeconds to wait for new output. Stop it with kill-sandbox-command. Reuse the same idempotencyKey when you retry a start. A sandbox with a running started command is never idle-terminated. To be called back instead of polling, pass executionWebhook (a public HTTPS url and a whsec_ signing secret) to create-sandbox: each finished command then sends a signed sandbox.execution.completed event. See Long-running work and Execution completion webhooks.

Shared volumes and Storage Servers

list-storage-servers, create-shared-volume, create-object-storage-server and update-object-storage-server need Shared Storage on the account; connecting or updating a bucket also needs Object Storage on the account and an account Admin (connecting one also needs the object storage add-on in the region). The bucket access key, secret key, hub token and master key are write-only: they are masked in MCP logs and the call audit, and never returned. An omitted masterKey is generated and can be revealed on the dashboard by a member with the Secrets Access role. update-object-storage-server rotates the hub token of the account's own bucket (running mounts keep the old token until the volume is re-published: a pod restart, or a sandbox pause and resume), changes its hub URL (refused with 409 while the account has volumes in the region) and sets the uid/gid new volumes report as file owner; create-object-storage-server takes uid/gid too. See the Shared Volumes API.

Managed Redis HAProxy timeouts

The existing database settings object supports redis.haproxy.timeoutClientSeconds and redis.haproxy.timeoutServerSeconds for managed Redis HA. Values are integer seconds (1–2147483), with a 60-second default when omitted. Save via the existing environment update operation and apply changes. See the database settings API.

DR activation also accepts target: { envName, createNewApp, appName }. Use the same naming choice as Snapshots: databases need a new app name; applications may keep the source app or choose a new one. Confirm these names alongside the exact cutoff, and keep the entire payload unchanged on retries. Names are applied only at verified Live handoff, without changing region, resources or runtime identifiers. Older clients can omit target for legacy naming. Follow activationResult.targetAppId when opening the recovered environment.

After a verified native PostgreSQL handoff, the normal replica collector registers the existing ready runtime in the ordinary environment history. The environment then shows Running, actual replicas and CPU/memory metrics; Live on the DR card remains the historical activation result. Registration does not rebuild, restart, copy or replace the retained warm disk. Existing completed PostgreSQL handoffs are reconciled the same way. A handoff receipt alone never creates a Running status, and later failed/unready replicas remain visible through normal runtime telemetry. Client reconnection is still a separate action.

Environment-local WAF extensions

update_app_env_security accepts wafConfig as complete JSON text. Rule count and individual fields are bounded, and enabled rules must compile within the documented ModSecurity size limit. Omit it to preserve settings; send an empty string to clear extensions. It uses the same server validation and permissions as the Security settings page. Changes remain pending unless applyImmediately is explicitly true, and never silently enable WAF. Environment read-back includes the saved JSON; use deployment History to verify what was applied.

The dashboard flow is Copy prompt → paste config → validate → save/apply. Use Copy AI prompt in App Env → Settings → Security settings with your preferred agent. See the supported format and examples.

Secrets Access role

The quave:read:secrets scope permits a secret-returning capability; it does not replace account authorization. Revealing account/environment secrets also requires Secrets Access, and secrets inside managed credentials require Manage Credentials and Secrets Access. Admin alone is insufficient. Existing Admins receive Secrets Access during migration. Personal-token ownership and restrictions on returning legacy credentials through OAuth remain unchanged. See User Roles.

Agent Sandbox resource enforcement

The runtime preserves the pinned template's process and temporary-disk bounds. Process limits include threads and descendants; temporary-disk overages are handled by Kubernetes eviction rather than immediate write errors. See resource limits.

Sandbox creation also enforces an atomic account-wide ceiling on active sandboxes and the sandbox resource limits. A refused create returns HTTP 429 with a documented capacity reason and allocates nothing; reconnect with the same idempotency key still returns the original sandbox. See atomic sandbox admission. Project overrides are restricted to the app-bound orchestration service, not ordinary MCP inputs.