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.

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.

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.

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.

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.

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.

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

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.

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 are rejected. 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 omit it. 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.

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.

Personal Warren authentication

Personal Warren authentication runtimes are not generic Agent Sandboxes: their command, file and orchestrator-session access is denied (HTTP 403). Account administration does not grant access to another person's subscription. The owner manages AI Subscriptions (ChatGPT/Codex or Claude) and their Warren sign-in on the personal AI Subscriptions page. MCP does not expose device codes, Claude one-time codes, OAuth files, or a generic subscription provider. inputs.warrenAuthenticationMode: AI_SUBSCRIPTION (legacy PERSONAL_CODEX), with an optional inputs.aiSubscriptionId, installs Warren without an unused AI Provider Key. API-key mode remains the default. A Claude subscription signs in with the official, unmodified Claude Code CLI: the owner approves access on Anthropic's page and pastes Claude's one-time code back. Runs use the claude-subscription Warren agent, priced as an estimate, with no API fallback. Personal run dispatch still requires the separate owner-bound runtime integration and cannot use the shared operator token as owner identity.

The installation service-principal claim endpoint also requires a separate, expiring owner task grant. A claim binds one frozen task to one Warren run; it exposes neither a generic gateway session nor OAuth credentials and is not offered as an MCP tool. Managed execution remains separately gated.

The bound run's dedicated sandbox control endpoint allocates only the reserved supervised holder with existing authentication. It allows metadata-only status and explicit reset after whole-holder/storage teardown; missing auth cannot be recreated on a run. This service-principal control is not an MCP tool and does not open generic command/file/session access. Owner dispatch uses the dedicated Solution form described below; the fixed execution endpoint remains separate from generic MCP access.

Personal Codex managed execution is not an MCP model provider. Its installation-only /sandbox-orchestrator/codex-runs/:runId/execution start/status endpoint accepts only run-bound callback credentials, never arbitrary commands, environment or OAuth data. The owner-frozen task cannot consume the shared Warren inbox. An exited process is not proof of released authentication storage. Only whole-holder termination plus storage release produces a durable cleanup receipt. Successful cleanup preserves auth; cancellation/failure requires fresh sign-in. Old status and cleanup requests use the owner-scoped receipt without touching a newer run. Actual managed subscription qualification remains required before release.

The Warren Solution owner's Personal Codex form can now submit a private coding intent (approved repository, base branch and prompt). The server reserves the existing connection operation and sends a one-time owner grant to its installed Warren control host. Neither the grant nor the private prompt enters browser storage or the shared Warren task metadata. An uncertain create is never repeated; polling recovers only the run ID bound by the original claim. This owner-only Meteor action is not a generic REST/MCP dispatch capability. Live subscription qualification remains required before release.

The same form offers explicit continuation of its last successfully cleaned-up task. The parent receipt must match owner, installation, active principal, connection and private origin, with successful exit and preserved authentication. The frozen base branch is the parent's pushed Warren branch. Shared operators cannot inject a parent, and historical receipts without origin lineage fail closed. The official runner separately verifies the stored Codex thread lineage.

After confirmed authentication-storage deletion, prior continuation eligibility for that exact owner connection is invalidated before the operation fence clears. An interrupted invalidation stays fenced and can be reconciled safely.

Disaster readiness status can include a historical activationResult for a completed generic cold or accepted native PostgreSQL/Redis recovery: selected data cutoff, completion time, operation and recovered environment IDs. This does not claim running application health, application traffic cutover or renewed disaster readiness. For generic recovery, configure and deploy the target explicitly. Native completion requires database and public TLS endpoint verification plus ownership handoff; it exposes the tested database endpoint but does not reconnect clients. Verify application behavior and reconnect clients, then establish new protection. Native recovery is still being qualified.

DR configuration/source results can include activeOperation.cutoffAt and activities[].cutoffAt: canonical UTC timestamps of the pinned selected activation point, not the latest snapshot or step execution time. The dashboard formats these in browser-local time. Missing fields do not imply a cutoff or Live completion. See selected activation cutoff.

DR configuration results may include activeOperation.validationCleanup with an observed temporary-disk retention deadline. This is pending cleanup, not Disaster Ready acceptance. Retained storage may incur costs; deletion is not guaranteed at the deadline. See temporary validation cleanup.

DR configuration/source results may also contain pendingCleanup after the operation lock is released: pendingCount, retainedDiskCount, retryingCount and optional earliestRetentionUntil. This includes earlier validation cleanup obligations, even during a new recovery. A new recovery never adopts those temporary targets. Retention is not shortened; zero retained disks does not mean full validation passed. See temporary validation cleanup.

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 atomic per-account/app capacity, pending/queue bounds and sandbox resource quotas. 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.