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.

Pair the local CLI

Generate a one-time code in clientarea under Impreza API → Connect an AI assistant, choosing the permissions the assistant needs. Run npx -y impreza-mcp login --code <code-from-clientarea> on the machine running the local MCP server. Codes expire after 10 minutes and can be used once.

The CLI exchanges the code at POST /v1/mcp/pair without sending any existing API credentials. It saves the returned key, secret, scopes and expiry in ~/.impreza/credentials.json; the code and secret are never printed. The directory uses mode 0700 and the file 0600 on POSIX. Windows uses a protected ACL granting access only to your account. The server reads this file automatically when neither credential environment variable is set. Explicit IMPREZA_API_KEY and IMPREZA_API_SECRET take precedence together; partial environment credentials never use a saved counterpart.

Set IMPREZA_BASE_URL before pairing for a different API endpoint. HTTPS is required; a v3 onion endpoint requires IMPREZA_PROXY with an explicit SOCKS5 proxy and never falls back to a direct connection. The endpoint and proxy are saved with the credential. A different API URL refuses the saved credential. Pairing never follows redirects or retries a code automatically.

An existing credential file is never overwritten. Revoke an old paired key in clientarea before removing its file and pairing again. If an exchange or disk write fails, the code may already have been consumed: check and revoke the new key in clientarea before generating another code. Restart the AI client after pairing.

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.

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