# impreza-mcp

[Model Context Protocol](https://modelcontextprotocol.io) server for
[Impreza Host](https://imprezahost.com). Lets AI coding tools (Claude
Code, Cursor, Codex CLI, Continue, Zed, ...) deploy customer-built
apps to managed Impreza VPSes without leaving the chat.

When you say "deploy this for me" to Claude with this MCP server
loaded, Claude calls `impreza_deploy_custom` directly — packages your
project, uploads it, builds + runs on your Impreza VPS, and reports
back the URL.

## Deployment progress and agent restarts

Compose review and deployment accept
`context_id` for one retained upload containing local build contexts and runtime
`env_file`, configs or secrets. The same context must be supplied at review and
deployment. Runtime files require agent 0.6.11+ with `compose-source-files-v1`.

Custom Node server/static deployments
accept `node_package_manager`, such as `pnpm@10.26.1` or `yarn@4.9.2`, matching the
project's exact `packageManager` and committed lockfile. Omit for npm. Supported
versions are standalone pnpm 10–12 and Yarn 4 projects, without combining
this field with `npm_workspace`. Inspection infers the pin and saved plans retain
it. See the deployment documentation for supported inputs and limits.

Read `last_operation.progress` from `impreza_list_deployments` for the last
reported step and timestamp. Agent 0.6.6+ saves final results before sending them;
after restart it resends the same receipt without repeating the deploy.
Agent 0.6.7+ can verify a completed preparation checkpoint and restore previous
configuration without replaying the deploy (`recovery=reconciling`). Wait for the
terminal failure or confirmed cancellation before retrying.
`recovery=required` means automatic reconciliation could not be verified; contact
support. Busy builds, missing checkpoints and replacement uncertainty stay blocked. A long-running build can
continue after the agent exits. Progress is not a live percentage or proof of
current runtime health. Existing agents update explicitly before the next deploy.
See [deployment progress](https://docs.imprezahost.com/deployment-progress.html).

## Cancel a deployment

Use `impreza_cancel_deployment` with the deployment ID and exact
`last_operation.command_id`. Requires manage permission. Queued cancellation
is immediate; running preparation needs agent 0.6.5+. Agent 0.6.12+ can interrupt an owned build after the server administrator
enables controlled builds on supported Ubuntu 24.04 amd64 hosts. Other preparation
waits for its current step. Confirmation still requires verified cleanup and restored
configuration. `requested` is not `cancelled`. Replacement/recovery cannot
be cancelled. Cancelling a tracking Task remains separate.
Read [the cancellation guide](https://docs.imprezahost.com/deployment-cancellation.html).

## Runtime health and deployment operations

`impreza_list_deployments` returns `runtime` and `last_operation` separately.
A failed build can leave the previous application healthy. Read runtime state,
observation time and reason; old or missing readings remain unknown.
Running without a confirmed healthcheck is not healthy. This requires agent
0.6.4+ for observations and does not verify external HTTP/DNS/TLS. Existing
servers update explicitly. See [runtime health](https://docs.imprezahost.com/runtime-health.html).

## Saved project plans and safe retries

`impreza_plan_project` also accepts
`git_url` and an exact 40-character `git_commit` instead of `context_id`.
Optional `git_username` and `git_token` are used only for the fetch. The server
captures an immutable retained archive, accounts for its upload quota, and
returns `source.origin` alongside the archive SHA256. Review those values before
preparing/applying the saved configuration. Only public-network HTTPS on port
443 is supported; redirects and submodules are refused. Project code is not
executed by inspection. These options require the corresponding control-plane
capabilities; update the local MCP package before using them.

Use `impreza_plan_project` with a retained `context_id` to inspect the archive
inventory and selected configuration files. Choose `project_dir`,
`dockerfile_path`, a Python `start_command` or `php_document_root` as needed.
Review the findings and `analysis.deployment_options`.

With MCP **0.32.0+**, call `impreza_prepare_project_deployment` with `plan_id`,
zero-based `option_index`, app name, server and runtime settings. It validates
and saves the effective configuration without creating an app, job or DNS
record. Review the returned configuration, then call
`impreza_apply_project_deployment` with only `execution_id` and
`configuration_digest`. Later form/request changes cannot override that record.

A repeat of the same saved deployment returns its original acceptance receipt,
including after expiry or app removal. The receipt, app and queue job commit
together. After an uncertain response, retry the same ID and digest instead of
preparing another deployment. Acceptance means queued; inspect app status,
logs and health. This does not restart a failed job or update an existing app.

`impreza_list_prepared_deployments` lists the latest 20 saved configurations or
retrieves one `execution_id`. Environment values are encrypted in the prepared
record, omitted from review responses and cleared from that record on acceptance;
the app then uses its normal environment storage. Reviews show variable names.
Use at most 100 string values, with no system/routing variable overrides.

At most 20 pending records per account, valid no longer than the source plan
and for at most 24 hours. Source, rules, target availability/IP and effective
settings are rechecked before first apply. There is no domain, port or capacity
reservation, dependency pinning or build guarantee. DNS is external to the app
transaction and can remain after an interrupted attempt. Expired pending records
are removed on the account's next preparation; accepted receipts are retained.

Source inspection remains available in MCP 0.31.0+. The older
`impreza_deploy_project_plan` creates directly from an option and is not
idempotent. Plan creation requires deploy scope; listing requires read scope;
preparation/apply require deploy scope. These account-wide tools require
credentials without resource restrictions. No agent update is needed solely for
this flow; recipe requirements still apply. See the
[project plan and review guide](https://docs.imprezahost.com/project-plans.html).

## Retained source uploads

Use `impreza_upload_context` with `dir` and an optional `label` to upload an immutable
source version without deploying. The response includes its `context_id`, SHA256,
size and expiry. List or inspect versions with `impreza_list_contexts`.

Create an app with `impreza_deploy_custom`, `mode: "dockerfile"` and `context_id`
(or deploy a local `dir` directly). Rebuild it with `impreza_redeploy_deployment`
and optionally another retained `context_id`. The app identity, domain, host port,
volumes and build recipe stay fixed. The selected source can differ from the
running release after failure or rollback; inspect deployment history.

Sources in use remain available. Unreferenced versions expire seven days after
upload or their last deployment request, not seven days after detachment. Default
quotas are 10 unexpired/referenced archives, 300 MiB per account and 100 MiB per
archive; referenced sources count. Delete an unused version with
`impreza_delete_context`, `context_id` and `confirm: true` after customer confirmation.
Metadata requires read scope, upload requires deploy, and deletion requires
manage. Resource-confined credentials cannot manage account uploads.

The packer excludes common dependency/VCS folders, .env and .env.* (except
example/sample/template files), .npmrc and .pypirc. It does not scan arbitrary
secrets or interpret .gitignore/.dockerignore; review what you upload. Portal
archives are sent unchanged. Legacy REST uploads remain temporary unless they
opt into `retain=true`. Older uploaded-source apps can migrate by selecting a
fresh retained context on redeploy. These MCP tools require 0.22.0+; no agent
update is needed solely for source retention. See the
[source upload guide](https://docs.imprezahost.com/source-uploads.html).

## Node.js npm builds

Deploy an independent npm HTTP application without a repository Dockerfile using
`impreza_deploy_custom` with `mode: "dockerfile"`, `build_strategy: "node_npm"`,
`git_url` (or local `dir`), and `target_port` (usually 3000).
The API generates a Node 24 recipe: npm ci, optional build script, production
pruning and npm start as a non-root user. The selected project folder must contain package.json, package-lock.json
and a production start script. Docker Compose 2.17+ and BuildKit
must be available on the server. Select npm workspaces explicitly with
`npm_workspace`. Use `build_secrets` for named credentials and the `npmrc` secret
for private npm installation; agent 0.6.11+ is required. The app must listen on 0.0.0.0 and the
configured port. Keep runtime PORT consistent with that port.

Git redeploys and previews reuse the recipe snapshot. Retained uploaded sources
support reuse and source-version selection; older temporary uploads remain single-use. The recipe excludes .git, node_modules, .env,
.env.* and .npmrc from the source copy; this does not scan arbitrary secrets.
Keep credentials out of source code. The HTTP startup probe accepts responses
below 500 at / and is not a functional application test.

## Public build variables

Required healthy start: opt in with require_healthy_start=true, an explicit healthcheck_path and build_strategy=node_npm. In the portal, enable Require a healthy start. Agent 0.6.3 or newer must be reported in Servers; update it explicitly and wait for the next heartbeat. startup_timeout_seconds accepts an integer from 30 to 600, default 60. The budget starts after containers are created and includes the stable health observation; Git fetch, dependency/image builds and recovery have separate time limits. Every running service must report Docker healthy and at least one serving container must exist. HTTP redirects, authentication errors and timeouts do not pass the configured 2xx probe. When the first install fails, its containers are removed and persistent volumes are preserved; the failure includes diagnostic logs. A failed replacement recovers a verified healthy previous release when available. Recovery and manual rollback use the saved release startup policy, so a slow healthy release retains its original deadline. Failure recovery does not undo database writes or mutable data. The control plane refuses incompatible agents at creation, never dispatches the policy without startup-health-v1 support in the current poll, and accepts success only with a matching health confirmation. Previews inherit the policy; redeploy keeps the snapshot. Deployment reads expose startup_health. Choose a new deployment to change the saved policy. Omission or false preserves legacy behavior; a startup timeout requires the option enabled. The public option is for generated Node builds. This does not provide zero-downtime switching or continuous automatic rollback after startup. Local MCP input support requires 0.20.0+. Existing agents update only when the customer runs the updater. See https://docs.imprezahost.com/tutorials/agent-apps-panels.html#required-startup

Node health checks: with build_strategy=node_npm, optionally set healthcheck_path (for example /health or /api/ready), or fill Health check path in the portal. The generated Docker health check sends HTTP GET to 127.0.0.1 on target_port inside the container and requires status 200-299; it does not follow redirects or send credentials. The route must work without login and should report the dependencies your app needs to serve requests. Use / or a path of at most 200 ASCII characters; segments start with a letter, digit, underscore or hyphen and may then include dots or tildes. A trailing slash is allowed. URLs, query strings, fragments, percent escapes, spaces, parent segments and repeated slashes are refused. Omit the field (leave it blank in the portal) to keep the legacy / probe accepting statuses below 500; explicitly setting / requires 2xx. Existing deployment snapshots remain unchanged. The saved healthcheck_path is returned by deployment reads, inherited by new previews and retained on redeploy; changing it requires a new deployment. Static sites keep their index.html probe; custom Dockerfiles define their own HEALTHCHECK. The probe runs every 5 seconds with a 2-second request timeout. With required startup disabled, agents 0.6.2 and later observe startup for up to 60 seconds: a failed replacement recovers a verified healthy previous release when one exists. Without that recovery target, a first install can still complete with a startup warning, so inspect health and logs before treating it as ready. This default policy does not provide continuous rollback, zero-downtime routing or external uptime checks. To enforce a startup deadline, enable required healthy startup with agent 0.6.3+. Local MCP inputs require 0.19.0+; healthcheck_path alone needs no agent update beyond 0.6.2.

Public build settings: generated node_npm and node_npm_static recipes accept public_build_vars, an object of string values available only to npm run build (including its prebuild/postbuild scripts). For example, {"VITE_API_URL":"https://api.example.com"} lets Vite compile a public API URL into the site. Names must start with VITE_, NEXT_PUBLIC_ or PUBLIC_, contain only uppercase letters, digits and underscores, and be at most 128 characters. Limits: 20 entries, 4096 UTF-8 bytes per value and 16384 bytes for names plus values. Empty strings are preserved; NUL is refused. Values are literal data, without shell or variable expansion. The portal exposes Public build variables as KEY=value lines; do not add surrounding quotes, which would become part of the value. These values are public and may appear in bundles, image metadata and logs: never send passwords, tokens or secrets. They are not supplied to npm ci or automatically added to runtime variables. Runtime vars still configure the running container and do not rewrite compiled browser files. Settings are saved at creation, exposed on deployment reads, inherited by new previews and reused on redeploy. Preview runtime inheritance/overrides do not change this build snapshot; create a separate deployment for different public build values. Existing snapshots default to no public build values. Use build_secrets for supported build credentials with agent 0.6.11+; unsupported build settings require a custom Dockerfile. Local MCP requires 0.18.0+; no agent update is required beyond the existing build executor.

See the [build configuration guide](https://docs.imprezahost.com/tutorials/agent-apps-panels.html#public-build-settings).

## Apps in project subfolders

Deploy an independent npm app from a subfolder: set project_dir (default .) with node_npm or node_npm_static, or choose Project folder in the portal. For example, apps/site must contain its own package.json and matching package-lock.json; static_output_dir is relative to that folder. Only the selected folder is copied into /app for npm installation and builds. The repository/upload remains the Docker build context, so its root .dockerignore still applies. Paths allow up to 120 characters and five non-hidden segments; parent, node_modules and symlink components are refused. Missing folders or failed builds retain the previous healthy runtime. The project_dir value is returned by deployment reads, saved at creation and inherited by new previews; redeploy reuses the saved recipe. Existing snapshots default to .; changing the folder requires a new deployment. This supports independent apps in one repository, not shared workspaces or dependencies outside the folder; use a custom Dockerfile for those. The analyzer does not discover subfolders: supply the selected app metadata and review Project folder yourself. Local MCP requires 0.17.0+; no agent upgrade is required beyond the existing build executor.

See the [project folder guide](https://docs.imprezahost.com/tutorials/agent-apps-panels.html#project-folder).

## Import a Compose stack

Use `impreza_prepare_compose` with `compose_yaml`, then explicitly select
`web_service` and the integer `target_port`. Review services, persistent
volumes, required variables, changes and blockers before deploying with
`impreza_deploy_custom`, `mode: "compose"`, the same YAML/service/port and
`compose_review_id` set to the returned `analysis_id`.

Supports self-contained public-image stacks with up to 12 services, private
bridge networks, local named volumes and service dependencies. Original host
port bindings are removed; only the selected HTTP service joins the proxy and
receives a managed loopback port. Container and volume names become specific
to the deployment. Declare CPU/memory limits per service in YAML.

The review does not fetch images, execute code or reserve resources. Local build
contexts and auxiliary files require the same retained context_id at review and
deploy. Runtime env_file accepts literal assignments only, without interpolation
or inherited bare keys. Aliases, profiles, host privileges and external resources
are outside this import subset. Reference uppercase variables instead of
embedding secrets. Runtime values must be single-line strings up to 4 KiB,
without surrounding whitespace, quotes, backslashes, dollar signs or space
followed by #. Variables supply explicit references, not every service's
environment. Required values are checked at creation, editing and redeploy.

The imported source is saved as a manifest. Redeploy reuses it and the named
data; changing the source/topology requires a new deployment. Failure recovery
uses the existing agent policy and does not undo database writes. Local MCP
support for public-image stacks requires 0.21.0+. Retained build/runtime sources
require MCP 0.34.0+ and agent 0.6.11+.
See the [Compose import guide](https://docs.imprezahost.com/compose-import.html).

## Prepare project configuration

Use `impreza_prepare_project` with `package_json`, `dockerfile`, and optional
`dockerfile_path` before deploying. It returns framework hints, available build
and start commands, explicit ports from the final Dockerfile stage, and findings
to review. Each file is limited to 32 KiB. Review files for credentials before
sending; never submit .env files or secrets.

This is advisory analysis of supplied text. It does not fetch a repository,
execute code, generate a Dockerfile or deploy resources. Git deploys use a Dockerfile by default; supported npm projects can opt into the Node recipe. The analysis ID identifies metadata, not an executable plan.
Requires an API exposing /v1/platform/deployments/custom/prepare.

## Why this host and not a mainstream one

Any provider can run your app. This one is built so an **agent can obtain and
operate infrastructure that is not tied to your identity**, end to end, without
you opening a browser:

- **No KYC, and no email address, to open an account.** An account is a
  generated client ID plus a recovery token. No documents, no selfie, no phone
  number.
- **Funded in cryptocurrency.** `impreza_topup` accepts BTC, XMR, USDT and TRX,
  and `impreza_order_vps` buys the server from that balance. The agent can go
  from "I need a server" to a running deployment without a card.
- **Offshore and onshore jurisdictions side by side**, chosen per project
  rather than per account.
- **Tor is a deployment target, not an add-on.** `impreza_add_onion` gives a
  deployment a `.onion` address in one call, so an agent can publish a hidden
  service the same way it publishes a normal site. `impreza_onion_auth_*`
  manage Tor v3 restricted discovery (client authorization): private keys
  never leave the customer's Tor client unless they ask the server to
  generate a keypair — and then the private key is shown once, never stored.
- **No API key in your config.** The hosted connector authenticates over OAuth.

If none of that matters for your project, a mainstream provider is a perfectly
good choice and usually cheaper to start with. This exists for the projects
where it does matter: research and journalism under pressure, censorship
circumvention, security work, and anything that should not be one support
ticket away from being linked to a legal name.

## Retained-release rollback

The source tree adds `impreza_rollback_deployment`. Read a deployment's
`release_history` through `impreza_api_call` at
`/platform/deployments/{id}`, then choose a `rel_...` entry with
`rollback_supported: true`.

Explain the selected release and possible interruption to the customer before
calling the tool with `deployment_id`, `target_version` and `confirm: true`.
The hosted connector uses its two-call `confirm_token` flow instead.
The operation requires `manage` scope and a compatible API and agent.

A historical release may no longer be retained. The agent checks local images
and unchanged ports, storage and routing before replacing containers. It saves
the current healthy runtime and attempts recovery if the selected release fails
startup. Database contents and mutable data are not reverted. A queued response
does not confirm restoration; check deployment history for the result.

Available in impreza-mcp 0.12.0. Requires a compatible API and agent.

## Static npm sites

Static npm sites: choose build_strategy=node_npm_static with a Git/context source (mode=dockerfile), or Static site + npm in the portal. Requires an independent npm package in the selected project folder, matching package-lock.json and a build script producing index.html in the selected output folder. Node 24 installs dependencies and runs the build; unprivileged Nginx serves only the selected output folder with configurable SPA fallback. No start script is required. Default target_port is 8080. Compose 2.17+ and BuildKit required. No SSR or server functions. Explicit npm_workspace and build_secrets are supported with their documented source and agent requirements. Runtime variables (including VITE_* and PORT) do not rewrite static bundles or change the configured Nginx port. Use static_output_dir (default dist) to choose a relative output folder containing index.html, and static_spa (boolean, default true) to choose SPA fallback or 404 for unknown routes. The portal exposes both fields. Paths are limited to 120 characters and five segments, without hidden, parent or node_modules segments; symlinks in the output or its parent path are refused. These settings are chosen at creation, stored in the recipe snapshot, exposed as static_options and carried to new previews. Redeploy reuses the saved recipe; changing these settings on existing deployments requires creating a new deployment. Existing snapshots keep their original recipe. Local MCP option inputs require 0.16.0+. Use public_build_vars for supported public settings; other build-time configuration requires a custom Dockerfile. Source .env/.env.*/.npmrc/.git/node_modules are excluded; review all generated files because the output folder is public. Missing index.html and symlink output fail the build. Existing preview/redeploy snapshots preserve the strategy. Local MCP requires 0.15.0+; no agent upgrade is needed beyond the existing build executor. The analyzer returns static_npm_recipe and conditional deployment_options; metadata is not proof of a static, working build.

## Status

**Package version: 0.46.0.** The tool catalog covers app deployment plus account +
crypto balance, catalog + ordering, domains/DNS + registration, invoices, VPS
lifecycle with snapshots and backups, dedicated / bare-metal servers, plan
upgrades, and Titan / Google Workspace mailboxes — with a setup wizard that
generates ready-to-paste config snippets for 5 AI tools.

On top of that, everything an app needs after it is running: backup and
restore into the customer's **own** S3 bucket, a timer on an app with its
output kept, outbound webhooks so you stop polling, reading the app's own
files, and running the app's own command line.

The local (`npx`) server and the hosted OAuth connector expose the **same tool
catalog — 184 tools on both sides**. Two declared, one-direction gaps remain:
`impreza_get_log_request` stays hosted-only (only the control plane resolves a
bare `request_id`; locally, call `impreza_tail_logs` again on the application —
requests dedupe), and `impreza_upload_context` stays local-only (binary tarball
streaming does not fit the hosted transport).

### New in 0.11.0

**Run the app's own command line.** WP-CLI for WordPress, `occ` for
Nextcloud, `gitea admin` for Gitea, and the database client for a dump —
`impreza_app_cli` to run, `impreza_get_cli_run` to collect the output. Call
`impreza_get_cli_run` with no `run_id` first: it names the command lines the
app has, says what each is for, and gives one example that works.

- **No docker socket, and that is measured rather than claimed.** The command
  runs in a separate container built from the app's own image, joined to the
  app's own network, with its data mounted — the shape the official CLI
  images are designed for. `cap_drop: ALL`, and no new privilege on the
  machine.
- **Arguments are a list, never a string.** Each element becomes one `argv`
  entry through `execve`, so nothing is split, globbed or substituted:
  quoting is not your problem, and a `$` or a `;` inside a value is just
  that. Verified against a live site — `option update blogname
  'dollars $HOME and a ; semicolon'` reads back exactly as sent.
- **Destructive, and treated as such.** A command line can do anything the
  app itself can, so it needs the `manage` scope and is confirmation-gated.
  Arguments are free rather than allowlisted: that is the same ceiling
  `uninstall` with `purge_data` already sits at, and a list of `wp`
  subcommands would age badly while protecting nothing the confirmation gate
  does not.
- **The CLI version follows the app.** Where the command line is the app's
  own image it is taken from that deployment, so a catalog bump carries it —
  running `occ` from an older Nextcloud against a newer database is how a
  maintenance command corrupts an install.

Custom deployments have no command line here: it is your own image and the
platform cannot know what it ships. Use a scheduled task of kind `command`
for those.

### New in 0.10.0

**Look inside the app's own files.** `impreza_get_logs` reads stdout, which
cannot answer the question a deploy that came up wrong actually raises: did
that variable reach the config file? Two tools now do —
`impreza_inspect_app` to ask and `impreza_get_app_read` to collect the answer.

- **Four actions, and no fifth:** `list` a directory, `read` a file (capped at
  256 KB), `tail` its last lines, `grep` under a path with an extended regular
  expression. There is no command string in the interface, and therefore no
  shell.
- **Read-only by construction.** A one-shot container mounts the app's storage
  read-only — the same mechanism the backup already uses — with no docker
  socket and no write capability. So it also works on an app that is `failed`
  and will not start, which is when it is wanted most.
- **Only the app's own storage:** `data`, or one of the named volumes the app's
  manifest declares (a WordPress exposes `data` and `wp_db`, so its database
  files are readable too). Call `impreza_get_app_read` with no `read_id` to
  see the list for a given app.
- **What comes back is untrusted and often secret** — an app's config file is
  where its database password lives. It reaches you and nothing else: the
  field is on our request log's deny list, and the record is deleted within a
  day.

### Since 0.6.1

Three releases the npm page never described, each one a whole capability:

- **0.7.0 — backup and restore** of a deployment's data into the account's own
  Impreza S3 bucket, with a per-chunk SHA-256 manifest that sits beside the
  data so the copy stays verifiable with the customer's own credentials and no
  call to us. Plus a schedule (daily by default, keeping 3), and a restore
  that can land in a *different* app, which is how an app moves between
  servers.
- **0.8.0 — scheduled tasks:** a timer on an app with the output kept, for the
  apps that need one to behave correctly (Nextcloud's cron, WordPress's
  `wp-cron` on a site with no visitors).
- **0.9.0 — outbound webhooks:** subscribe to deploy, backup and VPS events
  and stop polling, with HMAC-signed delivery and a delivery log.

### New in 0.6.1

**`tools/list` now reflects what your account actually owns.** About a third of
the tools only make sense if you have the machine behind them — VPS power
controls with no VPS can only ever answer "not found" — so those are left out
of the listing until you own one. Typical accounts see around 70 tools instead
of 97, which is roughly six thousand fewer tokens of context spent before you
ask anything.

Three things worth knowing about how it behaves:

- **The purchase path is never filtered.** An account that owns nothing is the
  one that needs to buy something, so ordering, top-up, invoices and the
  catalogue are always listed.
- **Buying something grows the list mid-session.** The server sends
  `notifications/tools/list_changed` on the same response as the order, so a
  client that honours it picks up the new tools without reconnecting.
- **It fails open.** If this server cannot reach the API to ask, it lists
  everything rather than guess.

Hiding a tool is not an authorization boundary — the API still refuses anything
your account does not own. This only stops the listing from carrying tools that
could never work for you.

### New in 0.6.0

Four things that only make sense on a host built for anonymity:

- **Dark previews** — push a branch, get a preview on its own ephemeral Tor
  `.onion`. Every other platform's preview URL puts your branch name into
  public DNS and into a permanent Certificate Transparency log; branch names
  carry ticket ids, customer names and unshipped features. This one creates
  neither record, and destroys its keys when the branch is deleted or the TTL
  runs out. `impreza_configure_previews`, `impreza_list_previews`,
  `impreza_retire_preview`.
- **Agent sub-credentials** — mint a narrower credential from the one you hold
  and hand it to a subtask: one deployment, one hour, no spending. A child can
  never exceed its parent on any axis, and revoking a credential revokes
  everything it minted, however deep. `impreza_mint_subcredential`,
  `impreza_list_credentials`, `impreza_revoke_credential`,
  `impreza_agent_activity`.
- **A privacy report you can check** — `impreza_privacy_report` returns every
  field we store about your account, what it is for, how long it survives and
  who else sees it, and then measures our own retention against the oldest
  record that actually survived. Counts and date ranges, never contents.
- **Ask before you guess** — search our docs, validate a deployment manifest
  before deploying it (including a privacy lint for third-party CDNs, public
  DNS resolvers and leaked secrets), or run a diagnosis when something is
  wrong. `impreza_search_docs`, `impreza_validate_manifest`, `impreza_doctor`.

Plus the Tasks extension, so long operations report completion instead of
leaving you to poll, and three MCP Apps panels — a payment card, a server card
and a deploy wizard — that render inside clients which support them.

The table below is a **selection**, not the full list — it covers the tools
most people reach for first. Your client's own tool listing is authoritative,
and `impreza_api_search` finds anything not named here.

| Tool | Wraps |
|------|-------|
| **Apps & deployments** | |
| `impreza_list_servers` | `GET /v1/platform/servers` |
| `impreza_list_apps` | `GET /v1/platform/apps` |
| `impreza_list_deployments` | `GET /v1/platform/deployments` + `/custom` (merged) |
| `impreza_upload_context` | `POST /v1/platform/deployments/custom/contexts?retain=true` |
| `impreza_list_contexts` | `GET /v1/platform/deployments/custom/contexts[/{context_id}]` |
| `impreza_delete_context` | `DELETE /v1/platform/deployments/custom/contexts/{context_id}` |
| `impreza_deploy_custom` | `POST /v1/platform/deployments/custom` (3 modes) |
| `impreza_deploy_catalog_app` | `POST /v1/platform/deployments` |
| `impreza_uninstall_deployment` | `POST .../uninstall` |
| `impreza_get_logs` | `POST .../logs` (sync tail, last N lines) |
| `impreza_restart_deployment` | `POST .../restart` |
| `impreza_redeploy_deployment` | `POST .../custom/{id}/redeploy` (in-place rebuild, same domain) |
| `impreza_add_onion` | `POST .../onion/add` |
| `impreza_set_onion_profile` | `POST .../onion/profile` (`standard` / `hardened` / `max` hardening tiers) |
| `impreza_export_onion_key` | `POST .../onion/export` (sealed to your X25519 key; plaintext never transits) |
| `impreza_fetch_onion_key_export` | `GET .../onion/export/{command_id}` (read-once — the blob is burned) |
| `impreza_rotate_onion_key` | `POST .../onion/rotate` (new .onion; the old address dies) |
| `impreza_onion_auth_list` | `GET .../onion/clients` |
| `impreza_onion_auth_add` | `POST .../onion/clients` (`pubkey`, or `generate:true` → `private_key` shown once) |
| `impreza_onion_auth_revoke` | `DELETE .../onion/clients/{name}` |
| `impreza_change_domain` | `POST .../domain` |
| `impreza_git_webhook_status` | `GET .../custom/{id}/git-webhook` |
| `impreza_git_webhook_connect` | `POST .../custom/{id}/git-webhook/connect` |
| `impreza_git_webhook_disconnect` | `POST .../custom/{id}/git-webhook/disconnect` |
| **Account & balance** | |
| `impreza_account_info` | `GET /v1/account` |
| `impreza_list_services` | `GET /v1/account/services` |
| `impreza_topup` | `POST /v1/account/topup` — top up in BTC / XMR / USDT / TRX |
| `impreza_topup_status` | `GET /v1/account/topup/{invoice_id}` |
| `impreza_topup_payment` | `GET /v1/account/topup/{invoice_id}/payment` — crypto address + amount to pay |
| **Catalog & ordering** | |
| `impreza_list_products` | `GET /v1/products` — products + pricing; the VPS is listed at its smallest size (`configurable: true`) |
| `impreza_vps_offer` | `GET /v1/products/vps` — VPS locations, operating systems, CPU / memory / disk ranges and prices; with a whole configuration, `GET /v1/products/vps/quote` — its exact price |
| `impreza_order_vps` | `POST /v1/orders` — a VPS by location, OS and size (or a fixed plan by `product_id`); paid from balance; born deployable (`@agent`); 202 + poll `impreza_list_servers` |
| **Domains & DNS** | |
| `impreza_domain_check` | `GET /v1/domains/check` |
| `impreza_domain_details` | `GET /v1/domains/{domain}` |
| `impreza_list_dns` | `GET /v1/domains/{domain}/dns` |
| `impreza_add_dns_record` | `POST /v1/domains/{domain}/dns` |
| `impreza_update_dns_record` | `PUT /v1/domains/{domain}/dns` |
| `impreza_delete_dns_record` | `DELETE /v1/domains/{domain}/dns` |
| `impreza_set_nameservers` | `PUT /v1/domains/{domain}/nameservers` |
| **VPS lifecycle** (Proxmox) | |
| `impreza_vps_status` | `GET /v1/vps/proxmox/{id}/status` |
| `impreza_vps_power` | `POST /v1/vps/proxmox/{id}/{start\|shutdown\|reboot\|stop}` |
| `impreza_vps_list_backups` | `GET /v1/vps/proxmox/{id}/backups` |
| `impreza_vps_create_backup` | `POST /v1/vps/proxmox/{id}/backups` |
| `impreza_vps_list_templates` | `GET /v1/vps/proxmox/{id}/templates` |
| `impreza_vps_reinstall` | `POST /v1/vps/proxmox/{id}/reinstall` — destructive (wipes) |
| `impreza_vps_resize` | `POST /v1/services/{id}/resize` — more vCPU, memory or disk at the pro-rated price (quote first with `GET /v1/services/{id}/resize/quote`); `max_amount` pins it |

## Install + setup

### Prerequisites

  - Node ≥ 20
  - An Impreza Host account with an API key + secret
    (clientarea → API Keys; the IP of the machine running this MCP
    server must be whitelisted under the key)

### One-shot via `npx`

No global install needed — `npx impreza-mcp` works.

### Or install globally

```sh
npm install -g impreza-mcp
```

### Get a ready-to-paste config snippet

The fastest path: ask the binary itself.

```sh
npx impreza-mcp setup --tool claude-code
# also: cursor | continue | zed | codex-cli
```

The wizard prints the JSON block to drop into your AI tool's MCP
config + the exact file path + the post-config step (usually "fully
quit + re-open the AI tool"). It does NOT write to disk — paste it
yourself so you don't accidentally clobber an existing config with
other MCP servers.

### Or wire it in manually

**Claude Code** — add to `~/Library/Application Support/Claude/claude_desktop_config.json`
(macOS) or `%APPDATA%/Claude/claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "impreza": {
      "command": "npx",
      "args": ["-y", "impreza-mcp"],
      "env": {
        "IMPREZA_API_KEY": "imp_...",
        "IMPREZA_API_SECRET": "..."
      }
    }
  }
}
```

Restart Claude Code. The tools appear under the MCP icon.

**Cursor** — add to `~/.cursor/mcp.json` (same shape as above).

**Continue** — add to `~/.continue/config.json`:

```json
{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "npx",
          "args": ["-y", "impreza-mcp"],
          "env": {
            "IMPREZA_API_KEY": "imp_...",
            "IMPREZA_API_SECRET": "..."
          }
        }
      }
    ]
  }
}
```

**Zed** — add to your settings:

```json
{
  "context_servers": {
    "impreza": {
      "command": {
        "path": "npx",
        "args": ["-y", "impreza-mcp"],
        "env": {
          "IMPREZA_API_KEY": "imp_...",
          "IMPREZA_API_SECRET": "..."
        }
      }
    }
  }
}
```

## Usage in chat

After setup, talk to your AI naturally:

> *"List my Impreza servers."* → calls `impreza_list_servers`
>
> *"Deploy this directory to my Impreza VPS, expose via .onion."* →
> packages the cwd as a Dockerfile-mode custom deploy, uploads, deploys
> with `onion=true`, reports the .onion address.
>
> *"What apps are running on my agent?"* → calls
> `impreza_list_deployments` filtered to the right server.

## Auth + security

`IMPREZA_API_KEY` + `IMPREZA_API_SECRET` live in the AI tool's MCP
config env — not in any file on disk owned by `impreza-mcp` itself.
The MCP server holds the secret only in memory and only attaches it
as HTTP request headers.

The IP of the machine running this MCP server (almost always your
laptop) must be on the API key's whitelist. Manage the whitelist in
your Impreza clientarea.

## Using over Tor

The MCP server can route every API call through a local Tor daemon, so
API requests use the configured proxy. Your network provider can still observe
your connection to Tor; this option does not hide that you are using Tor.

  1. Install and start Tor (the `tor` daemon, or Tor Browser — both
     commonly expose a SOCKS5 listener on `127.0.0.1:9050` for the daemon
     or `127.0.0.1:9150` for Tor Browser; check your local configuration).
  2. Add `IMPREZA_PROXY` to the MCP config env:

     ```json
     "env": {
       "IMPREZA_API_KEY": "imp_...",
       "IMPREZA_API_SECRET": "...",
       "IMPREZA_PROXY": "socks5://127.0.0.1:9050"
     }
     ```

Every API request then exits through Tor, and the API hostname is
resolved by Tor itself (remote DNS) — nothing is resolved locally, so
no DNS leak. The transport fails closed: if the proxy is unreachable
or refuses the connection, the request fails — it never silently falls
back to a direct clearnet connection.

Optionally point `IMPREZA_BASE_URL` at the API's `.onion` mirror —
`http://` is accepted only for v3 `.onion` hosts, since Tor authenticates and
encrypts onion connections. Clearnet hosts require `https://`. An onion URL
also requires an explicit `IMPREZA_PROXY`; the client refuses direct DNS and
connections even when the onion URL uses HTTPS. Proxy requests refuse redirects,
use a bounded request deadline and accept response bodies up to 16 MiB.

One account-side adjustment: Tor exit IPs rotate constantly, so a
fixed-IP whitelist on the API key cannot work. Set the key's IP factor
to `tofu` or `keyonly` in the clientarea.

## PHP deployments

Use `impreza_prepare_project` with `composer_json` and optionally `php_document_root` to review a PHP app. Deploy with `impreza_deploy_custom`, `mode: "dockerfile"` and `build_strategy: "php_composer"`, using Git, a local directory or a retained upload. The PHP 8.4/Apache recipe installs production dependencies from `composer.json` and a matching `composer.lock`, without Composer scripts or plugins, and checks actual platform requirements. Choose `project_dir` for the application and `php_document_root` for its public subfolder containing `index.php` (default `public`). Apache runs as a non-root user on `target_port` (default 8080, minimum 1024); it serves public files and sends missing paths to `index.php`.

Health checks require HTTP 2xx without redirects, at `/` or your `healthcheck_path`. Optional `require_healthy_start` needs an explicit path and agent 0.6.3+, with a 30–600 second startup budget. Previews and redeploys keep the saved recipe. Custom repositories, private dependency credentials, installation plugins, extra extensions, `.htaccess` rules, frontend builds and application setup/migrations require a custom Dockerfile. `start_command` and public build variables are not PHP options. Analysis is advisory and does not inspect the lockfile or repository. See the [PHP deployment guide](https://docs.imprezahost.com/tutorials/agent-apps-panels.html#php-build).

## Python deployments

Use `impreza_prepare_project` with `requirements_txt` and an explicit `start_command` to review a Python app. Deploy with `impreza_deploy_custom`, `mode: "dockerfile"` and `build_strategy: "python_pip"`, using Git, a local directory or an uploaded context. The Python 3.13 recipe installs a flat `requirements.txt` from PyPI and runs as a non-root user; choose `project_dir` for an independent application folder. Start a production server on `0.0.0.0` at `target_port` (default 8000), for example `exec gunicorn --bind 0.0.0.0:$PORT app:app`, with Flask and gunicorn declared in requirements. `PORT` and `HOST` are runtime variables. Keep credentials out of the saved command.

The default Python health probe requires HTTP 2xx on `/`; choose `healthcheck_path` for another route. Optional `require_healthy_start` needs an explicit path and agent 0.6.3+, with a 30–600 second startup budget. Previews and redeploys retain the saved recipe. Dependency options, includes, URLs, local projects, private build credentials, system packages and other package managers require a custom Dockerfile. Public build variables remain npm-only. Analysis is advisory; builds resolve actual dependencies on the server. See the [Python deployment guide](https://docs.imprezahost.com/tutorials/agent-apps-panels.html#python-build).

## Build

```sh
npm install
npm run build
# dist/server.js is the entry point
```

## Supervised preparation

These legacy worker rules remain in effect unless the administrator enables agent 0.6.12+ [controlled builds](https://docs.imprezahost.com/deployment-cancellation.html#controlled-builds), which add verified executor stop and recovery for new builds.

Agent 0.6.8+: supported Linux/systemd deploys run image pull and build in a separate supervised process. If the agent restarts, it waits for the exact worker receipt without repeating that work. Only a durable successful receipt allows the existing preparation reconciliation: revalidate operation/phase and unchanged containers, restore previous configuration, and close as failed or confirm a previously requested cancellation. recovery=reconciling can include waiting for the original worker. Missing/invalid receipts, worker failure or timeout, host reboot before a receipt, legacy unsupervised work, replacement uncertainty, data ownership and onion preparation still require review. A process or service disappearing is never proof of completion. The customer must wait for the final result before retrying; no automatic deploy retry, immediate build termination, data rollback or runtime-health guarantee is added.

## License

MIT — see `LICENSE`.


## Supervised replacement

Agent 0.6.9+: new supported Linux/systemd deploys keep the authorized container replacement, startup checks, lifecycle hooks, routes and normal startup recovery in one supervised worker. If the agent restarts, recovery=reconciling with step=reconciling_replacement waits for that original worker. Its verified durable final receipt is delivered without repeating containers or hooks, including a failed deployment whose previous release was restored. Missing or invalid receipts, worker loss or timeout, host reboot before completion, legacy unsupervised operations, data ownership changes and onion provisioning still require support; keep the private journal and do not retry to unblock the queue. This does not add automatic deployment retries, database rollback or zero-downtime traffic switching. Update the agent explicitly before the next deploy.

Python deployments may select python_package_manager=uv@0.12.15 with python_pip, pyproject.toml and uv.lock. Installation is locked, production-only and non-editable on Python 3.13; public PyPI sources only. Custom uv workspaces/indexes require a Dockerfile. Use MCP 0.34.0+ and a control plane supporting this recipe.


## PostgreSQL application connections

`impreza_prepare_service_binding` reviews a dedicated PostgreSQL connection for an image application in the same project environment and server. `impreza_prepare_service_binding_removal` reviews removal or a pending-cleanup retry with the exact `deployment_id` and `binding_id`. Read the saved plan with `impreza_get_service_binding_plan`; apply only after explicit confirmation using `impreza_apply_service_binding_plan`, the exact digest and `confirm: true`. Removal retains database data and disables the dedicated login only after a healthy replacement without the connection. Acceptance means queued, not verified completion. Requires agent 0.6.13+ and a compatible control plane.

`impreza_prepare_service_binding_rotation` reviews a credential rotation for an existing connection with `deployment_id`, `binding_id` and `mode` (`rotate` or `abandon`). Rotating replaces the dedicated login with a distinct new one and disables the previous login only after a healthy replacement with the rotated `DATABASE_URL`; the database and its data are always retained. A failed startup keeps the previous application serving with the current credential and requires a newly reviewed retry; if the previous login could not be confirmed disabled, the rotation stays pending cleanup and a new `rotate` review retries it. `abandon` discards the unused candidate credential and keeps the current one; it is refused once only cleanup remains. Apply the returned review with `impreza_apply_service_binding_plan` as above; preparation queues nothing and returns no credential. Rotation requires an agent announcing `postgres-service-binding-rotation-v1`: older agents refuse the dispatch and the failed job directs the customer to update the agent explicitly, preserving its identity, configuration and applications. Rotation requires a v2-protocol connection; legacy first-protocol connections are not adopted.

## Public HTTPS diagnostics

`impreza_probe_deployment` takes `deployment_id` and checks the saved public hostname through the control plane. It reports public DNS resolution, TLS verification and the HTTPS HEAD status, without following redirects or sending application credentials. It does not read response bodies or verify dependencies. One attempt per account every 30 seconds; no agent update is required.

## Image promotion and environments

`impreza_prepare_image_promotion`, `impreza_get_image_promotion` and `impreza_apply_image_promotion` review an exact registry digest for an existing destination configuration. Apply requires the returned review digest and explicit confirmation. Destination variables and data remain local to that application.

Project/environment tools organize existing applications with explicit component associations. They do not copy variables, create network connections or deploy workloads. See the [project environments guide](https://docs.imprezahost.com/project-environments.html).

### Reviewed deployment workflows

Version 0.38.0 adds environment configuration comparison, prepare/read/apply traffic
switches and explicit branch previews with optional password protection. Compare
returns variable names, never values. Traffic switches require a reviewed digest
and confirmation, keep the source running, and require operator reconciliation if
recovery cannot be verified. Protected preview credentials are shown once.
Traffic switches and protected previews require agent 0.6.16 or newer. Existing
servers update only at the customer's request. Assisted database restore is a REST
workflow. See [project environments](https://docs.imprezahost.com/project-environments.html)
and [deployment safety](https://docs.imprezahost.com/deployment-safety.html).

### Basic Cloud VPS management

Basic Cloud VPS supports status and allocated resources through `impreza_api_call`,
and boot, graceful shutdown and reboot through `impreza_cloud_power`. Use the WHMCS
service ID from `impreza_list_services`. Advanced Cloud infrastructure tools are
no longer advertised; retired calls return `FEATURE_NOT_AVAILABLE`. Contact
Impreza support for other infrastructure changes. Ordering and cancellation keep
their normal account workflows. Application management through an enrolled agent
is separate.


## Configuration, metrics and recovery (0.39.0)

Review application configuration with export/prepare/get/apply tools; inspect
per-app metrics and alert rules; download backup parts and review/apply a
PostgreSQL restore into a new database. Applying a review requires its digest
and explicit confirmation; acceptance is queued work, not verified completion.
The custom deploy and preparation tools also support `static_files` and
`go_build`. Metrics and MariaDB bindings require agent 0.6.17 or newer.
See [configuration, metrics and recovery](https://docs.imprezahost.com/customer-workflows.html)
for permissions, examples and limits. No automatic server update occurs.

### Isolated runtime through Tor (0.42.0)

Custom image and source deployments can opt in with `tor_egress: true` through
`impreza_deploy_custom` and saved deployment preparation. This option needs an
agent advertising `tor-egress-v1`, Docker Engine 28+, and a SOCKS5h-capable
application. The runtime has no direct outbound fallback. Source downloads,
image pulls and builds retain the server's normal network connection. Catalog
installs, imported manifests and external service bindings are unsupported.
See the [Tor runtime guide](https://docs.imprezahost.com/onion-services.html#runtime-egress)
for availability and verification. This option is separate from using Tor to
connect the MCP client itself and from publishing an inbound onion address.

## Local and hosted parity (0.46.0)

The local package now carries the 16 tools that only the hosted connector had:

- projects and environments: `impreza_rename_project`, `impreza_delete_project`,
  `impreza_rename_environment` and `impreza_delete_environment`;
- variable groups: `impreza_get_variable_group` and `impreza_set_variable_group`;
- configuration promotion: `impreza_prepare_config_promotion`,
  `impreza_get_config_promotion` and `impreza_apply_config_promotion`;
- ordered environment deploys: `impreza_deploy_environment`,
  `impreza_get_environment_deploy` and `impreza_list_environment_deploys`;
- agent updates: `impreza_get_update_policy`, `impreza_set_update_policy` and
  `impreza_request_agent_update`;
- Shield: `impreza_set_shield`.

Tool annotations (read-only, destructive, idempotent) now match the hosted
connector. A destructive tool called with `confirm` missing or false is refused
before any request is sent.

## Point-in-time PostgreSQL recovery (0.45.0)

Six tools cover status, configuration, a recovery drill, and prepare/get/apply
of a reviewed UTC recovery point: `impreza_get_pitr`, `impreza_configure_pitr`,
`impreza_drill_pitr`, `impreza_prepare_pitr_restore`,
`impreza_get_pitr_restore`, and `impreza_apply_pitr_restore`. Status uses read
scope; changes use deploy scope. The hosted connector requires a credential
without resource confinement because physical PostgreSQL recovery can cover
several bindings on a provider.

WAL and base backups consume the account's storage. After six consecutive
failures, automatic work pauses until the cause is repaired and configuration
is saved again. Disabling stops protection but retains stored objects. A
restore requires the review digest and `confirm: true`, creates a new database,
and never redirects the live application. Poll the review until its receipt
says `verified` or `failed`; acceptance alone is not a successful recovery.

## Scheduled tasks (0.45.0)

`impreza_create_task` creates a scheduled task on an app and `impreza_update_task`
changes one that exists (any field you leave out keeps its current value, so
`enabled=false` pauses a task without losing its schedule or history), as on the
hosted connector. They replace `impreza_schedule_task`, which is gone: update
any client or prompt that still calls it. `impreza_list_tasks`,
`impreza_run_task` and `impreza_delete_task` are unchanged.

## VPS resize (0.44.0)

`impreza_vps_resize` gives a configurable VPS more vCPUs, memory or disk. Price it
first with `impreza_api_call` on `/services/{id}/resize/quote`, passing the new
sizes as `query`: it returns the pro-rated amount due today (the billing
system's own figure), what the VPS renews at and whether the balance covers it.
Then call `impreza_vps_resize` with the same sizes and `max_amount` set to that
`due_today`, so a price that moved in between is refused rather than charged.
Sizes only go up. The disk is enlarged at once; the new vCPU count and memory
take effect when the VPS is restarted with `impreza_vps_power` action=reboot (a
reboot from inside the server keeps the old ones). See
[Resize a VPS](https://docs.imprezahost.com/order-vps.html#resize).

## Configurable VPS (0.43.0)

The VPS is one configurable product: choose the location, operating system,
vCPUs, memory and SSD disk. `impreza_vps_offer` lists every choice with its
price per unit for each billing cycle, in the account currency; given a whole
configuration (`billing_cycle`, `location`, `os`, `cpu_cores`, `memory_gb`,
`disk_gb`) it returns the exact price, whether the balance covers it and
whether that location has room right now. `impreza_order_vps` orders that
configuration with `product_id` left out; fixed plans such as Tor Hosting are
still ordered by `product_id`. The price charged is the price quoted. See
[Order a VPS](https://docs.imprezahost.com/order-vps.html).

## Private onion previews and retained identities (0.42.0)

Preview creation supports `private: true`; optionally supply one or more `onion_clients`.
Supplied reviewers use a name and X25519 public key. Without supplied clients, a reviewer keypair is generated and the private key is shown once. This mode requires agent
0.6.20 with `onion-private-preview-v1`; reviewer authorization is installed
before the first onion publication. Repeated deploys preserve later revocations.
Do not combine this option with password-protected HTTPS previews.

`impreza_purge_onion_key` requires the exact old onion address and explicit
confirmation. Queued work is not proof of deletion: inspect its completed
result. Active addresses are refused. Purge removes retained copies on that
server; exports and backups elsewhere remain. Releasing a reservation for an
uninstalled application does not delete key material.

See the [onion guide](https://docs.imprezahost.com/onion-services.html)
for permissions, customer update steps and supported limitations.