# BorealHost MCP Server

<!-- mcp-name: ai.borealhost/mcp -->

Agent-native web hosting tools for the [Model Context Protocol](https://modelcontextprotocol.io).

Connect any MCP-compatible AI agent to [BorealHost.ai](https://borealhost.ai) — purchase hosting, deploy sites, manage DNS, register domains, and scale infrastructure, entirely through tool calls.

## Quick Start

### Remote Server (Recommended)

No installation needed. Connect directly to the hosted server:

```json
{
  "mcpServers": {
    "borealhost": {
      "type": "streamable-http",
      "url": "https://borealhost.ai/mcp/"
    }
  }
}
```

### Local Installation (pip)

```bash
pip install borealhost-mcp
```

Then run:

```bash
borealhost-mcp
```

Or add to your MCP client config:

```json
{
  "mcpServers": {
    "borealhost": {
      "command": "borealhost-mcp"
    }
  }
}
```

### Environment Variables

| Variable | Description |
|----------|-------------|
| `BOREALHOST_BASE_URL` | API base URL (default: `https://borealhost.ai`) |
| `BOREALHOST_API_KEY` | Pre-configured API key (optional — you can also call `register()` or `set_api_key()` at runtime) |

## What Can It Do?

BorealHost MCP exposes **47 tools** across the full hosting lifecycle:

### Authentication & Identity
- `register` — Create an agent account and get an API key (no auth needed)
- `set_api_key` — Activate an existing key for the session
- `whoami` — Verify your key and check account info
- `request_api_key` / `claim_api_key` — Challenge-response auth for on-site agents

### Plan Discovery & Checkout
- `list_plans` — Browse hosting plans with pricing (CAD)
- `create_checkout` / `update_checkout` / `complete_checkout` / `get_checkout_status` — Full purchase flow with Stripe

### Site Management
- `get_site_status` — Check site health, resources, and configuration
- `manage_dns` — Create and delete DNS records (A, AAAA, CNAME, MX, TXT, SRV)
- `deploy` — Trigger site deployment
- `scale` — Upgrade or downgrade hosting plan
- `decommission` — Delete site (7-day grace period)

### Applications
- `install_app` — Install from templates: Django, Laravel, Next.js, Node.js, Nuxt.js, Rails, static
- `get_app_status` / `list_apps` — Monitor installations

### File Management
- `list_files` / `read_file` / `write_file` / `upload_file` / `delete_file` — Full filesystem access

### Snapshots & Backups
- `list_snapshots` / `create_snapshot` / `delete_snapshot` / `rollback_snapshot` — Local snapshots
- `create_b2_snapshot` — Cloud-backed snapshots (Backblaze B2)
- `schedule_snapshot` / `cancel_scheduled_snapshot` — Scheduled snapshots
- `get_snapshot_usage` — Check quota
- `list_backups` / `create_backup` / `restore_backup` — Automatic and manual backups

### Domains
- `search_domain` — Check availability and pricing
- `register_domain` — Register with WHOIS info (supports .ca, .com, .net, etc.)
- `list_domains` / `domain_detail` — Manage owned domains

### SSH & Logs
- `get_ssh_info` / `add_ssh_key` — SSH access for VPS plans
- `get_logs` — Retrieve error, access, and PHP logs

### Modules
- `list_modules` / `toggle_module` — Enable/disable AI modules (SEO, translation, content)

### Account & Billing
- `update_account` / `delete_account` — Profile management
- `list_subscriptions` / `get_billing_portal` — Billing info and Stripe portal
- `rotate_key` — Rotate API keys
- `get_metrics` — Traffic and performance metrics

## Resources

The server exposes 5 MCP resources for structured reference data:

| URI | Description |
|-----|-------------|
| `borealhost://api/errors` | Error codes with HTTP status and recovery guidance |
| `borealhost://api/scopes` | API key scope hierarchy and tool requirements |
| `borealhost://api/enums` | Valid enum values (checkout status, DNS types, log types, etc.) |
| `borealhost://api/response-format` | API response envelope documentation |
| `borealhost://plans` | Live plan catalog with current pricing |

## Prompts

5 guided workflow prompts for common operations:

- **`purchase_hosting`** — Step-by-step plan purchase flow
- **`setup_site`** — Post-purchase site configuration
- **`manage_dns`** — Common DNS operations
- **`register_domain`** — Domain registration with WHOIS checklist
- **`claim_site_key`** — Challenge-response key claiming

## Example Workflow

```
Agent: register()
→ {"api_key": "bh_...", "scopes": ["read", "write"]}

Agent: list_plans()
→ [{"slug": "starter", "price_monthly": 9.99, ...}, ...]

Agent: create_checkout("bh_site_starter_monthly")
→ {"checkout_id": "chk_...", "checkout_secret": "..."}

Agent: update_checkout("chk_...", requested_slug="my-new-site")
→ {"status": "ready"}

Agent: complete_checkout("chk_...")
→ {"payment_url": "https://borealhost.ai/pay/chk_.../?s=...",
   "confirmation_url": "https://borealhost.ai/pay/chk_.../confirmation/?s=..."}
  # show payment_url to the human; paying provisions the site

Agent: get_checkout_status("chk_...")  # poll until completed
→ {"status": "completed", "api_key": "bh_...",   # shown ONCE
   "site": {"slug": "my-new-site", "status": "active"}}

Agent: get_site_status("my-new-site")
→ {"status": "active", "url": "https://my-new-site.borealhost.ai"}
```

## Authentication

- **API key format:** `bh_` + 48 hex characters
- **Scopes:** `read` (view) → `write` (modify) → `admin` (delete/scale)
- **No auth needed** for: `list_plans`, `create_checkout`, `update_checkout`, `complete_checkout`, `get_checkout_status`
- Keys are shown **once** on creation — store immediately

## Requirements

- Python 3.10+
- Dependencies: `mcp[cli]>=1.2.0`, `httpx>=0.27.0`

## Links

- [BorealHost.ai](https://borealhost.ai)
- [API Documentation](https://borealhost.ai/api/)
- [Full LLM Reference](https://borealhost.ai/llms-full.txt)

## License

Proprietary. Copyright 2025-2026 BorealHost.ai. All rights reserved.