Connect an AI agent with the MCP server

Let Claude Desktop or another MCP client look at your Avaloi sites and change them, with an API key as the ceiling on what it can do.

The Avaloi MCP server lets an AI agent such as Claude Desktop look at your Avaloi sites and change them. It runs on your computer over stdio and is an HTTP client of the public Avaloi API. It holds no data of its own and can do nothing your API key cannot do.

Set it up

Create an API key in the dashboard under API keys. Grant only the scopes you want the agent to have. See API keys and scopes.
Build the server from the Avaloi repository with pnpm --filter @avaloi/mcp-server build. The package is not published to npm yet, so you run the build output directly.
Add this block to the Claude Desktop config file, claude_desktop_config.json. Replace the path with the full path to apps/mcp-server/dist/bin.js on your computer.

{
  "mcpServers": {
    "avaloi": {
      "command": "node",
      "args": ["/full/path/to/apps/mcp-server/dist/bin.js"],
      "env": { "AVALOI_API_KEY": "hk_live_...", "AVALOI_API_URL": "https://api.avaloi.com/v1" }
    }
  }
}

Restart Claude Desktop. The Avaloi tools appear in the client.

The server reads two environment variables and nothing else.

Variable	Needed	Meaning
`AVALOI_API_KEY`	Yes	Your Avaloi API key. It starts with `hk_live_` or `hk_test_`.
`AVALOI_API_URL`	No	The API base URL. Default `https://api.avaloi.com/v1`. Plain `http` is allowed only for `localhost`, for tests.

Other stdio MCP clients use the same command, args, and env. See the guides for Claude Desktop, Claude Code, and Cursor.

What the agent can do

Tool	What it does	Key scope
`list_sites`, `get_site`	Look at sites and their live environment. `get_site` also shows the node status and the newest failed job, so a stuck site explains itself	`sites:read`
`create_site`	Start a new site, or a free test site	`sites:write`
`delete_site`, `reset_site`	Delete or wipe a site (needs `confirm` and the typed site name as `confirm_name`). A failed site whose server is gone is deleted at once, with no job	`danger:destroy`
`set_php_version`, `restart_php`, `clear_cache`	PHP and cache changes	`sites:write`
`search_replace`	Database search and replace, dry run by default	`sites:write`
`run_wp_cli`	Allowlisted WP-CLI commands only	`sites:write`
`get_logs`	Last lines of a log, 200 at most	`sites:read`
`list_nodes`, `get_node_capacity`	Fleet health and headroom	`nodes:read`
`get_job`, `wait_for_job`	Job state, and a blocking wait of up to 120 seconds	`sites:read`
`list_releases`, `get_build_log`	Releases, commits, and build output	`sites:read`
`deploy_to_live`, `rollback_release`	Change live code (needs `confirm`)	`sites:write`
`set_env_var`	Set an environment variable or secret	`sites:write`
`list_regions`	Every region: warm, on demand, or closed with the reason. Only open regions take sites (us-east4 at launch)	`sites:read`
`manage_sftp_accounts`	List, add, switch, and remove SFTP users	`sites:write`
`set_ssh_access`, `create_wp_admin_user`, `set_webroot`	Access and web root changes (need `confirm`)	`sites:write`

Every tool that looks up a site by name also needs sites:read.

Tools that change a site return a job. The agent calls wait_for_job, which follows the job's server-sent events and returns progress notes and the final state. search_replace dry runs and run_wp_cli wait up to 30 seconds themselves and return their output.

Guardrails

Scopes are the ceiling. At startup the server asks the API which scopes the key holds and hides every tool the key cannot use. If a client calls a hidden tool anyway, the server refuses before any request leaves.
Confirm for risky actions. delete_site, reset_site, deploy_to_live, rollback_release, set_ssh_access, create_wp_admin_user, set_webroot, and applying search_replace refuse without confirm: true. The refusal tells the agent to ask you first. deploy_to_live shows the commits that would go live.
Dry run first. search_replace changes nothing unless dry_run is false and confirm is true. A dry run reports the replacements per table.
Small answers. get_logs returns at most 200 lines.
No secrets in answers. Passwords and tokens are masked. The API key never appears in a result. A secret environment variable value is never repeated.
No raw shell. WP-CLI runs only commands on the Avaloi allowlist.
Audited. Every request carries your key, a fresh Idempotency-Key on POST, and the client name and version from the MCP handshake. The activity log records the actor as an MCP agent with that client name, so it shows "Claude Desktop" through the named key.

Revoke access

Revoke the API key under API keys, or call DELETE /v1/api-keys/{id}. The agent loses access within 5 seconds.

Limits

get_logs returns at most 200 lines.
wait_for_job waits up to 120 seconds.
search_replace dry runs and run_wp_cli wait up to 30 seconds.

Quick answers

Can the agent delete a site by accident? Only if the key has danger:destroy and the agent passes confirm: true. Leave that scope off the key if you do not want the agent to destroy anything.

Why does the agent not see a tool? The key lacks the scope. The server hides tools the key cannot use.

Can I use a test key? Yes. A key starting with hk_test_ works on preview and staging.

API

GET /v1/api-keys/current
DELETE /v1/api-keys/{id}
GET /v1/jobs/{id}/events

Still stuck?

Email [email protected] with your site name and what you tried, or send us a message.