Last updated July 2, 2026

MCP Server

@hostatlas/mcp-server is a Model Context Protocol server that connects your HostAtlas infrastructure to any MCP-compatible AI client — Claude Code, Cursor, Windsurf, OpenCode, and more. It exposes the HostAtlas platform API as MCP tools and resources so you can manage servers, check alerts, tail logs, run recipes, and defend against attacks through natural language.

Requirements

Node.js 18+
A HostAtlas account with an API key

The server is distributed as an npm package. There’s no separate install step — the standard config launches it via npx, which fetches and runs the current version on demand.

Configuration

Claude Code

claude mcp add hostatlas -- npx @hostatlas/mcp-server

Set your API key:

export HOSTATLAS_API_URL=https://my.hostatlas.app
export HOSTATLAS_API_KEY=ha_your_api_key_here

Cursor / Windsurf / OpenCode / other MCP clients

Add to your MCP configuration:

{
  "mcpServers": {
    "hostatlas": {
      "command": "npx",
      "args": ["@hostatlas/mcp-server"],
      "env": {
        "HOSTATLAS_API_URL": "https://my.hostatlas.app",
        "HOSTATLAS_API_KEY": "ha_your_api_key_here"
      }
    }
  }
}

Auto-config (if you use the desktop CLI)

If you’ve already run hostatlas login from the desktop CLI, the MCP server reads your config from ~/.hostatlas/cli.json automatically — no environment variables needed.

Environment variables

Variable	Required	Description
`HOSTATLAS_API_URL`	Yes*	Your HostAtlas URL (e.g. `https://my.hostatlas.app`)
`HOSTATLAS_API_KEY`	Yes*	API key from Settings → API Keys

* Not required if ~/.hostatlas/cli.json exists from a prior desktop-CLI login.

Available tools

Platform

Tool	Description
`get_status`	Platform overview: server counts, firing alerts, open incidents

Servers

Tool	Description
`list_servers`	List all servers with hostname, IP, status, health score
`get_server`	Detailed server info including services, metrics, tags
`restart_service`	Restart a service on a server (nginx, mysql, redis, …)
`run_audit`	Run a service audit with optimisation recommendations

Alerts & Incidents

Tool	Description
`list_alerts`	List firing and recent alert events
`acknowledge_alert`	Acknowledge a firing alert
`list_incidents`	List open incidents
`create_incident`	Create a manual incident

Domains & Monitors

Tool	Description
`list_domains`	List domains with SSL status, HTTP health, response time
`list_monitors`	List uptime monitors with status and response time
`list_heartbeats`	List heartbeat / cron monitors with last-ping time

Operations

Tool	Description
`request_logs`	Request log lines from a remote server
`list_recipes`	List available automation recipes
`run_recipe`	Execute a recipe on a server

Backups

Tool	Description
`list_backup_paths`	List backup watch paths for a server
`update_backup_paths`	Set backup watch paths
`list_offsite_backups`	List completed offsite backups
`restore_offsite_backup`	Trigger the restore of an offsite backup

Attack Mode

Tool	Description
`get_attack_mode_status`	Check whether Attack Mode is active + live metrics
`activate_attack_mode`	Activate Attack Mode (enhanced monitoring + DDoS defence)
`deactivate_attack_mode`	Deactivate Attack Mode

Resources

MCP resources provide read-only context that AI clients can pull into their context window directly (without a tool call).

Resource	URI	Description
Platform Status	`hostatlas://status`	Server counts, alert / incident counts
Server List	`hostatlas://servers`	All servers with health and status
Active Alerts	`hostatlas://alerts`	Currently firing alerts

Example conversations

“How are my servers doing?” → The agent calls get_status, sees 2 alerts firing, calls list_alerts for details.

“Restart nginx on prod-01” → The agent calls list_servers to find the UUID, then restart_service.

“Are we under attack?” → The agent calls get_attack_mode_status for each critical server.

“Show me the last 200 lines of nginx error log on web-02” → The agent calls request_logs with file /var/log/nginx/error.log and lines 200.

“Run the system-update recipe on all staging servers” → The agent calls list_servers to find staging servers, list_recipes to find the recipe, then run_recipe for each.

Security

API key is transmitted via Authorization: Bearer header over HTTPS only
No credentials are stored by the MCP server — every call re-uses the key from env or from the desktop CLI’s config
The desktop CLI’s config file (~/.hostatlas/cli.json) has 0600 permissions when written by the CLI
All tools that modify state (restart_service, activate_attack_mode, create_incident, run_recipe, …) require explicit user confirmation in the AI client before running

License

MIT — the npm package is open-source. Source lives at github.com/akyroslabs/hostatlas-mcp-server.

CLI — the same platform operations from a shell
MCP Tailnet Manager — MCP surface for direct SSH access to a host, not the platform API

Was this page helpful?

Report issue ↗