Connect an AI tool to Impreza Host

Talk to your infrastructure in plain language: "what do I have running?", "deploy this project to my Impreza server and give me the URL". Impreza speaks MCP (Model Context Protocol — the "USB standard" AI tools use to gain new abilities), so the AI can act for you without leaving the chat. There are two ways to connect — start with the easy one.

The idea in one sentence #

Impreza exposes your whole account through MCP — the deploy platform (servers, app catalog, custom apps, domains, Tor, git-push auto-deploy) plus domains & DNS, VPS lifecycle (power, backups, reinstall) and crypto balance top-ups. Connect once and your AI gains Impreza tools it can call on its own, mid-conversation. How you connect depends on whether you just want to look (any AI client, zero setup) or also act (a coding agent with the full toolset).

Two ways to connect #

A · Remote connector + one-click OAuth easiest #

If your AI client supports remote MCP connectors (Claude does), this is the fastest path: no install, no API key, no IP whitelist. You paste one URL, the AI sends you to your Impreza clientarea to sign in and approve, and you're connected. Authorization happens entirely inside your own account — the AI never sees a password or a secret.

Connect in 4 steps

1. In your AI client, open the connector settings. In Claude: Settings → Connectors → Add custom connector. (Other MCP-capable clients have an equivalent "add remote MCP server" option.)
2. Give it a name (e.g. Impreza) and paste the server URL:

   https://mcp.imprezahost.com/mcp

3. Click Connect. The client registers itself automatically and opens an Impreza page — sign in to your clientarea if you aren't already.
4. You land on a consent screen showing the app name and what it's allowed to do. Click Authorize. Done — the AI now has the Impreza tools.

What you can ask

Anything the scopes you granted allow — the same toolset as the local server. For example:

• "List my Impreza servers and what's deployed." read
• "Deploy this GitHub repo to my VPS at app.example.com with a .onion mirror." deploy
• "Tail the logs for app X and restart it." deploy
• "Uninstall the old staging app." manage

Manage & disconnect

Every app you authorize shows up in clientarea → Impreza API → Connected Apps, with its scope and last-used time. Click Disconnect to revoke its token instantly (the AI client loses access on its next call). You can also remove the connector from the AI client's own settings.

B · Local impreza-mcp — the full deploy toolset #

For coding agents — Claude Code, Cursor, Codex CLI, Continue, Zed — install the impreza-mcp server next to the tool. It runs on your machine (not the VPS) and gives the AI all 31 tools, including deploy. This is the AI-native path for shipping code.

The 3 prerequisites (read this first)

Most beginner problems come from skipping one of these three. The AI will complain with "no servers on your account" or 403 IP_NOT_WHITELISTED, and it is always one of them:

1 — A server

Three ways to get one:

• Buy a VPS from Impreza — provisions in ~3 minutes (Proxmox). At checkout you pick what comes installed (see the box below).
• Buy a dedicated from Impreza — bare metal, manual provisioning (24–48h). Our team installs the agent for you.
• Bring your own (BYO) — any Debian / Ubuntu / RHEL / Alpine works. You just install the agent (next step).

2 — The agent running on the server

If you bought from Impreza and chose "Impreza Agent" / "Agent + MCP" / a catalog app, the agent is already installed — skip to the API key. Otherwise:

1. Sign in to portal.imprezahost.com → My Apps.
2. Click + Add another server (or the Custom App tile, shown when you have a server but no online agent). The panel mints a 10-minute bootstrap token and prints a one-liner:

   curl -fsSL https://raw.githubusercontent.com/imprezahost/agent-public/main/install.sh \
     | IMPREZA_BOOTSTRAP=<token-from-panel> sh

3. Run it on the VPS as root. Either SSH in yourself and paste it, or grant the AI SSH access and let it run the one-liner for you.
4. Within ~10 seconds the agent appears in My Apps as status: online. Done.

3 — API key (IP whitelist is now optional)

This is the credential the local MCP uses (different from the agent's own credential, issued automatically at bootstrap).

1. Portal → Impreza API.
2. Give it a label (laptop, claude, ci…), pick an IP mode (next paragraph), and click Generate New Key.
3. Copy the secret immediately. It is shown once; if you close the modal you cannot retrieve it (delete + recreate). The imp_… prefix stays visible. (Or skip the copy entirely — pair with a code.)

Choose how the key's second factor (IP) works — per key:

Install the local MCP (one command)

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

The wizard writes the MCP config for that tool, prints the exact config file path, and tells you to restart the tool.

Manual config (same shape for Claude Code, Cursor, Codex CLI)

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

Fill IMPREZA_API_KEY / IMPREZA_API_SECRET with the key/secret from the step above and restart the AI tool. The only machine prerequisite is Node.js (it ships with npx).

Pair with a code (no secret to copy)

Don't want to copy-paste a secret into a config file? Pair the tool instead:

1. Clientarea → Impreza API → Connect an AI assistant. Pick what the assistant may do (read / deploy / manage) and generate a one-time pairing code (valid 10 minutes).
2. On the machine running the tool:

   npx -y impreza-mcp login --code <code-from-clientarea>

3. The CLI exchanges the code for a key and stores it in ~/.impreza/credentials.json (permissions 0600). The secret is never printed. The MCP server reads it automatically — no env vars to set.

The 31 tools the AI gains #

You never have to memorize these — just talk in plain language and the AI picks the right one. The remote connector exposes the same set; each call is gated by the scope you granted — • needs only read, unmarked needs deploy, and ⚠ needs manage (destructive or financial — opt-in on the consent screen):

Using it in practice #

Some prompts that work well (the AI understands plain English):

• Ship the current project: "Deploy this project to my Impreza server and give me the URL." → impreza_list_servers to find the agent_id, then impreza_deploy_custom.
• Install a catalog app: "Install Vaultwarden on my VPS at vault.example.com with a .onion mirror." → impreza_deploy_catalog_app with onion: true.
• Investigate: "Is app X down? Show me the last logs and restart it if needed." → impreza_list_deployments → impreza_get_logs → impreza_restart_deployment.
• Turn on auto-deploy: "Connect git auto-deploy so every push to main ships a new version." → impreza_git_webhook_connect.
• Point a domain: "Add an A record for app.example.com pointing at my VPS's IP." → impreza_list_dns to see what's there → impreza_add_dns_record.
• Manage a VPS: "Is my VPS up? Take a backup, then reboot it." → impreza_vps_status → impreza_vps_create_backup → impreza_vps_power.
• Top up in crypto: "Add $50 to my balance in Monero." → impreza_topup returns a payment link; impreza_topup_status confirms once paid.

Troubleshooting #

Under the hood #

• Remote connector (OAuth 2.1): the AI client talks to https://mcp.imprezahost.com/mcp and authorizes via standard OAuth — you consent in your clientarea, the client gets a scoped, revocable access token (no password or API secret ever leaves Impreza). Tokens are short-lived and refreshed automatically; revoke instantly under Connected Apps.
• Customer ↔ API (local MCP): headers X-API-Key: imp_… + X-API-Secret: …. The second factor (IP) is per-key: whitelist (default), trust-on-first-use, or key-only. The MCP reads the key from IMPREZA_API_KEY / IMPREZA_API_SECRET or from ~/.impreza/credentials.json (after pairing).
• Agent ↔ API: headers X-Agent-Id: agt_… + X-Agent-Secret: …, issued at bootstrap and stored in /etc/impreza-agent/credentials.toml. You never touch this.
• Domains: empty domain auto-allocates <app>-<6hex>.imprezaapps.com. Own domain? Point its A record at the agent IP before calling so Let's Encrypt can issue.
• Other paths (no AI): the impreza CLI (Tutorial 4) and the REST API (Tutorial 3).