Impreza Host

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 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. An endpoint other than the official API or a local address also needs IMPREZA_ORIGIN_AUTHORIZED set to that exact origin (for example the API's .onion origin); without it the pairing code is never sent there. 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.

Add a server you already have (0.53.0)

• `impreza_add_server` connects a server the customer already has (any Linux machine with root access and outbound HTTPS, at any provider) and returns a one-line install command with a one-time token valid for 10 minutes. The first external server is free on every account, with no plan and no balance; any active Impreza VPS moves the account to Bundled (5 external servers). The token is shown once and only its hash is kept: if it is lost or expires, call the tool again. An unused token holds the free slot until it expires, and new servers are limited per day. label is optional plain text of up to 120 characters, counted as Unicode code points, the same way the API counts them. For a managed Impreza VPS, use impreza_install_agent. Requires deploy scope.
• The start-from-nothing skill asks first whether the customer already has a server, and describes the anonymous lobby of the hosted connector: account creation plus reads of public information (docs search, the VPS offer and quote, products, apps, manifest check, domain availability and prices).
• Tool titles and descriptions follow the current API guidance: secret values are typed by the account owner in the portal, VPS orders stay bare unless the agent is requested, and retained archives and watched Git refs are described as the API applies them.

Inbound access for non-HTTP ports (0.52.0)

• `impreza_get_ingress` reads which address ranges may reach each non-HTTP port an application publishes (databases, game servers, RustDesk...). Every deployment starts open. The answer carries the revision, the status (open, pending, enforced, not_enforced with a reason, or agent_update_required with the minimum agent version) and, per port, open or restricted with its sources. Requires read scope.
• `impreza_set_ingress` replaces the allowlist with the complete desired state: rules lists only the restricted ports, each with its IPv4 or IPv6 CIDR sources, and rules=[] opens every port again. Restricting can block your own access, so it needs confirm: true; opening does not. Pass the base_revision you read; a stale one is refused with REVISION_CONFLICT. The agent applies it within about a minute. If a restriction cannot be applied, the ports stay open, the status says not_enforced with the reason, and an alert fires on the app. Requires manage scope.
• HTTP and HTTPS are not covered: they go through the proxy and the Shield. Enforcement needs agent 0.6.26 or later.

Exact top-up amounts and checked IDs in API paths (0.51.0)

• Exact top-up amounts. impreza_topup accepts the amount as an exact decimal string (for example "25.50") and sends it to the API unchanged, without converting it to a binary floating-point number. A JSON number is still accepted. Strings with an exponent, a sign, spaces or more than two decimal places are refused.
• Every ID placed in an API path is checked. The 0.50.0 guard for deployment_id now covers every identifier the package places in an API URL path: task, backup, VPS, image, invoice, command, read and run IDs, agent IDs, onion client names, the domain in tools that route by domain, and the dedicated IP for reverse DNS. A value that would add or change path segments (., .., /, \, %, whitespace or control characters) is refused before any request leaves the process. Valid IDs are sent exactly as before.

Protect an app, safer deployment IDs and bare VPS orders (0.50.0)

• Protect an app, as a guided prompt. prompts/list adds impreza_protect_app. Starting from one of your running apps, it walks the assistant through a cold standby on a server you own in another country: choose the target with the human, create the standby (impreza_deploy_catalog_app with standby: true), pair it and run the first restore drill, each step behind its own explicit human confirmation. After a verified drill it reports the measured copy age and drill duration; these are measurements, not a guaranteed RPO or RTO. It never buys a server, promotes the standby, switches traffic or changes DNS, and it covers the reviewed failover apps (Memos 0.31.0 and Uptime Kuma 2.5.5). Like every prompt, it grants no authority.
• Server locations: impreza_list_servers returns each server's failover_location in its structured output: country_code, country_basis (verified, operator_verified or declared; a country you declared for an external server is not verified by Impreza) and country_notice.
• Deployment IDs cannot add path segments. A deployment_id that would add or change path segments in an API URL (., .., /, \, %, whitespace or control characters) is refused before any request leaves the process. Valid IDs are sent exactly as before.
• A VPS ordered through the API is bare by default. impreza_order_vps and impreza_vps_offer now describe what the API does: without app, the VPS is born with app: "none" (bare OS, no agent). Pass app: "@agent" explicitly when the customer wants it deployable, or offer impreza_install_agent later with the customer's confirmation. After ordering, poll impreza_list_services; impreza_list_servers lists only servers with an installed agent.
• Exact direct dependencies. The package pins its direct runtime dependencies to the exact versions it was tested with (see Dependency versions).

Install the agent, enter secrets outside the chat, and protect custom apps (0.49.0)

• `impreza_install_agent` offers the Impreza agent on a managed VPS that does not have it yet, only with the customer's explicit agreement: the first call installs nothing and returns a short-lived confirm_token; the second call, with the same arguments plus that token, starts the install. `impreza_get_agent_install` says whether a VPS can take it and follows the install until the agent is online.
• Secrets never pass through the chat. impreza_prepare_secret_entry returns a ten-minute, single-use portal link for a secret variable of an existing app or variable group; the account owner opens it, signs in and types the value there. impreza_get_secret_entry reports only pending, stored, expired or cancelled — never the value or a hash of it. Tools now refuse secret values (passwords, Git tokens, onion private keys, build secrets) in their arguments and point to the portal instead; the REST API is unchanged.
• Jurisdiction failover for custom projects: impreza_deploy_custom accepts standby: true to create a cold standby on another server, from the same pinned source (image digest, exact git commit, or the frozen Compose upload). The project must declare every persistent volume, and a custom pair cuts over only after a verified drill.

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 explic