impreza-mcp

Model Context Protocol server for Impreza Host. 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 [email protected] or [email protected], 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.

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.

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.

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.

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.

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.

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.

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.

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.47.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 — 196 tools on both sides. 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); impreza_list_approvals, impreza_get_approval and impreza_get_credential_policy are hosted-first (locally, the same reads are REST calls through impreza_api_call); 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

npm install -g impreza-mcp

Get a ready-to-paste config snippet

The fastest path: ask the binary itself.

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):

{
  "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:

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

Zed — add to your settings:

{
  "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:

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

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.

Build

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, 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 [email protected] 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.

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 and deployment safety.

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 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 for availability and verification. This option is separate from using Tor to connect the MCP client itself and from publishing an inbound onion address.

Account overview, playbooks and safer operations (0.47.0)

Twelve new tools and five prompts:

• Account overview: impreza_get_account_overview situates an assistant on the account in one read-only call: servers, apps and environments, domains, open alerts, recent deployment failures and the suggested next actions. A credential confined to some resources sees every section filtered to them.
• Playbooks as prompts: prompts/list offers five guided procedures: impreza_publish_git, impreza_change_domain, impreza_diagnose_deployment, impreza_restore_backup and impreza_update_agent. They grant no authority; every step still goes through the tools and their confirmations.
• Pause and resume a server's agent: impreza_pause_agent stops new command dispatch and suspends credentials confined to that server; impreza_resume_agent brings them back. Work already dispatched may finish. Both need an unrestricted credential with manage scope and confirm: true.
• Host plans with human approval: impreza_host_permissions, impreza_prepare_host_plan, impreza_get_host_plan and impreza_apply_host_plan prepare a VPS reinstall that a person approves in the dashboard (exact server, template, digest and deadline) before it runs. An AI cannot approve its own plan.
• Zero-downtime redeploys: impreza_get_zero_downtime explains whether an app qualifies and every reason why not; impreza_set_zero_downtime turns it on for a custom app and sets the readiness check. Needs agent 0.6.27 or later.
• Reads: impreza_get_shield (Shield policy and the last 24 hours of WAF findings, no visitor identity), impreza_privileged_audit (the admission audit of privileged operations on the account) and impreza_get_host_inventory (allowlisted host facts; it needs agent 0.6.28, not yet released, and says so).
• Structured output: read tools declare an outputSchema and return structuredContent; one-time secrets stay in the text and never in the structured result.

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.

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.

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 for permissions, customer update steps and supported limitations.