npm package: @hostatlas/mcp-server
Description: MCP server for HostAtlas infrastructure monitoring — works with Claude Code, Cursor, Windsurf, and any MCP client
Author: Akyros Labs LLC
Latest version: 1.0.0

# HostAtlas MCP Server

MCP (Model Context Protocol) server for [HostAtlas](https://hostatlas.app) — connect your infrastructure monitoring to Claude Code, Cursor, Windsurf, and any MCP-compatible AI client.

Manage servers, check alerts, tail logs, run recipes, and defend against attacks — all through natural language.

**[Sign up free](https://my.hostatlas.app/register)** — no credit card required.

---

## Quick Start

### Claude Code

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

Set your API key:

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

### Cursor / Windsurf / Other MCP Clients

Add to your MCP configuration:

```json
{
  "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 HostAtlas CLI)

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

## Configuration

| Variable | Required | Default | 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 CLI login.

## Available Tools (21)

### 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` | Get detailed server info including services, metrics, tags |
| `restart_service` | Restart a service on a server (nginx, mysql, redis, etc.) |
| `run_audit` | Run service audit with optimization 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 restore of an offsite backup |

### Attack Mode

| Tool | Description |
|------|-------------|
| `get_attack_mode_status` | Check if attack mode is active, get live metrics |
| `activate_attack_mode` | Activate attack mode (enhanced monitoring + DDoS defense) |
| `deactivate_attack_mode` | Deactivate attack mode |

## Resources (3)

MCP resources provide read-only context that AI clients can pull into their context window.

| 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?"**
→ AI calls `get_status`, sees 2 alerts firing, calls `list_alerts` for details

**"Restart nginx on prod-01"**
→ AI calls `list_servers` to find UUID, then `restart_service`

**"Are we under attack?"**
→ AI calls `get_attack_mode_status` for each critical server

**"Show me the last 200 lines of nginx error log on web-02"**
→ AI calls `request_logs` with file `/var/log/nginx/error.log` and lines 200

**"Run the system update recipe on all staging servers"**
→ AI calls `list_servers` to find staging servers, `list_recipes` to find the recipe, then `run_recipe` for each

## Requirements

- Node.js 18+
- HostAtlas account with API key

## Security

- API key is transmitted via `Authorization: Bearer` header over HTTPS only
- No credentials are stored by the MCP server
- Config file (`~/.hostatlas/cli.json`) has `0600` permissions (set by CLI)
- All tools that modify state (restart, attack mode, etc.) require explicit user confirmation in the AI client

## License

MIT License

---

Built by [Akyros Labs LLC](https://akyroslabs.com) — hello@akyroslabs.com

[HostAtlas](https://hostatlas.app) | [Sign up free](https://my.hostatlas.app/register)