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.

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

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

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.

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

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.

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 Warren Solution owner flow manages sign-in; MCP does not expose device codes, OAuth files or a generic subscription provider. inputs.warrenAuthenticationMode: PERSONAL_CODEX installs Warren without an unused AI Provider Key; API-key mode remains the default. 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.

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.