API Tools
borealhost.ai
Manages BorealHost API keys for agent accounts and container-based authentication.
ENDPOINT 1
https://borealhost.ai/mcp
MCP server metadata
- Name
- BorealHost
- Version
- 1.27.0
# BorealHost — Agent Instructions You are connected to BorealHost.ai, an agent-native web hosting platform based in Quebec, Canada. All prices are in **CAD**. You can purchase hosting, deploy sites, manage DNS, register domains, and scale infrastructure — entirely through these tools, without human intervention. ## Quick Start Workflow 1. **Discover plans** — call `list_plans()` to see available hosting plans with pricing and resources 2. **Create checkout** — call `create_checkout(sku)` with a SKU like `bh_site_starter_monthly` 3. **Set buyer info** — call `update_checkout(checkout_id, requested_slug="my-site")` to pick a site name 4. **Pay** — call `complete_checkout(checkout_id)` and show the human `payment_url` 5. **Poll provisioning** — call `get_checkout_status(checkout_id)` until status is `completed` 6. **Manage your site** — use `get_site_status`, `manage_dns`, file tools, etc. Paying is what provisions the site. There is no step between 4 and 5, and `create_site` is not one — it reports, it does not create. ## Authentication - **API key format:** `bh_<48 hex chars>` — pass as `Authorization: Bearer <key>` - **Session-based:** Call `set_api_key("bh_...")` to activate an existing key for this session — all subsequent tools will use it automatically - **Auto-activation:** Keys are automatically activated when returned by `register()`, `complete_checkout()`, or `get_checkout_status()` — no extra step needed - **Environment variable:** Optionally set `BOREALHOST_API_KEY` before connecting (used as default if no session key is set) - **Scopes:** `read` (view data), `write` (modify resources), `admin` (delete/scale) - **One-time display:** API keys are shown **exactly once** on creation or rotation — store immediately - **New agents:** Call `register()` — no auth needed, returns a fresh read+write key and activates it - **Existing users:** Call `set_api_key()` with the owner's key from the BorealHost panel - **On-site agents (challenge-response):** If you are running on a BorealHost container and need an API key, use the two-step claim flow: 1. Call `request_api_key("your-site-slug")` — a claim token is written to your container 2. Read the token file from the container filesystem 3. Call `claim_api_key(token)` — the API key is returned and auto-activated This proves you have access to the container without storing secrets on disk. - Some tools require no authentication: `list_plans`, `create_checkout`, `update_checkout`, `complete_checkout`, `get_checkout_status`, `request_api_key` ## SKU Format Plan SKUs follow the pattern: `bh_{plan_slug}_{billing_period}` Examples: - `bh_site_starter_monthly` / `bh_site_starter_annual` - `bh_site_pro_monthly` / `bh_site_pro_annual` - `bh_site_managed_monthly` / `bh_site_managed_annual` - `bh_site_business_monthly` / `bh_site_business_annual` Call `list_plans()` to discover all current plan slugs. ## Payment Methods Two options in `complete_checkout()`: 1. **`stripe_checkout`** (default) — Returns `payment_url`, a short BorealHost redirect. Present **that** to the human, not `stripe_checkout_url`: chat UIs strip the `#fragment` the raw Stripe URL needs. After paying they land on a confirmation page showing the order. Then poll `get_checkout_status()` until status becomes `completed`. The API key is included in the first poll response after completion (shown once, then cleared — `api_key_pending` says whether it is still waiting). 2. **`stripe_payment_method`** — Charges a Stripe PaymentMethod directly. Requires `payment_method_id` parameter. On success, the response includes the API key immediately. No polling needed. ## Polling Strategy When waiting for checkout completion or provisioning: - **First 60 seconds:** Poll every **5 seconds** - **After 60 seconds:** Poll every **15 seconds** - **Timeout:** Stop after **10 minutes** — if still not completed, something went wrong Terminal checkout statuses: `completed`, `canceled`, `failed` Immediately after `completed`, `site` may still be `null` — provisioning runs a few seconds behind payment. Keep polling until `site.status` is `active`. Abandoned attempts are yours to clean up: `list_checkouts()` shows your account's checkouts, `cancel_checkout(id)` retires an unpaid one and expires its payment link. ## Error Handling All API responses use a consistent envelope: ```json {"ok": true, "data": {...}, "meta": {"request_id": "uuid", "timestamp": "iso8601"}} {"ok": false, "error": {"code": "ERROR_CODE", "message": "Human-readable message"}, "meta": {...}} ``` Tools unwrap this envelope — you receive the `data` directly on success, or an exception on error. ### Error Codes and Recovery | Code | HTTP | Meaning | Recovery | |------|------|---------|----------| | `VALIDATION_ERROR` | 422 | Invalid input (bad email, slug, SKU, etc.) | Fix the input and retry | | `NOT_FOUND` | 404 | Resource doesn't exist | Check the identifier (slug, domain, key ID) | | `UNAUTHORIZED` | 401 | Missing or invalid API key | Set `BOREALHOST_API_KEY` or call `register()` | | `FORBIDDEN` | 403 | Insufficient scope or wrong owner | Check that your key has the required scope | | `RATE_LIMITED` | 429 | Too many requests | Wait for the duration in the `Retry-After` header, then retry | | `INTERNAL_ERROR` | 500 | Server error | Retry with exponential backoff (1s, 2s, 4s) up to 3 times | ## Slug Rules Site slugs must match: `^[a-z0-9][a-z0-9-]{1,48}[a-z0-9]$` - 3–50 characters - Lowercase alphanumeric and hyphens only - Cannot start or end with a hyphen - Must be globally unique — if taken, try a different one ## Best Practices - **Store API keys immediately** — they are shown only once and cannot be retrieved - **Create snapshots before destructive operations** — call `create_snapshot()` before scaling down or decommissioning - **Check site status after provisioning** — call `get_site_status()` to confirm the site is ready before managing it - **Use `whoami()` to verify your key** — confirms scopes, account info, and active site count - **Domain registration requires complete WHOIS contact info** — have all fields ready before calling `register_domain()` - **For .ca domains**, always provide `ca_legal_type` (CCT for corporation, CCO for citizen, RES for resident) ## Available Resources Read these MCP resources for detailed reference data: - `borealhost://api/errors` — Full error code catalog with recovery guidance - `borealhost://api/scopes` — API key scope descriptions and tool requirements - `borealhost://api/enums` — All 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 ## Available Prompts Use these MCP prompts for guided workflows: - `purchase_hosting` — Step-by-step hosting purchase flow - `setup_site` — Post-purchase site configuration (DNS, modules) - `manage_dns` — Common DNS operations guide - `register_domain` — Domain registration with WHOIS field checklist
Known tools 152
request_api_keyRequest an API key for a site YOU ARE RUNNING ON (challenge-response).
Inferred read-onlyget_site_statusGet detailed status of a hosted site including resources, domains, and modules.
Inferred read-onlylist_subscriptionsList all subscriptions with plan details, pricing, status, and site slug.
Inferred read-onlyget_billing_portalGet a Stripe billing portal URL for managing payment methods and invoices.
Potential side effectsadd_ssh_keyInject your SSH public key into a site's container for direct SSH access.
Inferred read-onlyget_stack_infoGet detailed system stack information (OS, PHP, DB, web server versions).
Inferred read-onlyget_resource_snapshotGet current resource usage (CPU, memory, disk, load average).
Inferred read-onlydelete_subdomainRemove a subdomain: its DNS record, nginx vhost and certificate.
Potential side effectsget_site_nginx_snippetRead the custom nginx config for a domain on the BorealHost host proxy.
Inferred read-onlyset_site_nginx_snippetSet custom nginx config on the BorealHost host proxy — WebSocket, timeouts, headers.
Inferred read-onlyset_domain_usageSet what a registered domain points at — a site, someone else's nameservers, our DNS with no site, or a redirect to another URL.
Inferred read-onlydomain_settingsUpdate domain settings (auto-renew, WHOIS privacy, registrar lock).
Potential side effectslist_compute_instancesList your on-demand compute instances with month-to-date spend.
Inferred read-onlyget_compute_instanceGet live details for a compute instance (state, public IP, accrued cost).
Inferred read-onlyterminate_compute_instancePermanently terminate a compute instance — this stops hourly billing.
Inferred read-onlylist_compute_volumesList your compute volumes — machines that survive instance termination.
Inferred read-onlyget_compute_volumeGet a volume's live state, its instance, and its monthly storage cost.
Inferred read-onlyadopt_compute_instanceTurn an instance you are ALREADY running into a persistent volume.
Inferred read-onlydetach_compute_volumeQueue: snapshot the machine, verify it, then destroy the instance.
Potential side effectsattach_compute_volumeRestore a detached volume onto a fresh instance — optionally a new type.
Inferred read-onlysnapshot_compute_volumeQueue a checkpoint snapshot without detaching — before a risky change.
Inferred read-onlyreset_mailbox_passwordReset a mailbox password (generated when omitted, returned ONCE).
Inferred read-onlyCONNECT WITH APPROVAL
Client installation
Review this server and its permissions before adding it. Secret placeholders must be set locally.
Codex
~/.codex/config.toml
[mcp_servers.borealhost]
url = "https://borealhost.ai/mcp"
enabled = trueClaude Code
.mcp.json
{
"mcpServers": {
"borealhost": {
"type": "http",
"url": "https://borealhost.ai/mcp"
}
}
}Claude Desktop
Settings → Connectors → Add custom connector
Name: borealhost
Remote MCP URL: https://borealhost.ai/mcpAdd this remote URL as a custom connector in Claude Desktop. Availability depends on the user plan and workspace policy.
Cursor
.cursor/mcp.json
{
"mcpServers": {
"borealhost": {
"url": "https://borealhost.ai/mcp"
}
}
}Visual Studio Code
.vscode/mcp.json
Add to Visual Studio Code{
"servers": {
"borealhost": {
"type": "http",
"url": "https://borealhost.ai/mcp"
}
}
}Generic MCP
Client-specific MCP configuration
{
"name": "borealhost",
"transport": "streamable-http",
"url": "https://borealhost.ai/mcp"
}MCP Inspector
Run the official MCP Inspector locally and enter the indexed Streamable HTTP endpoint.
TRUST AND VERIFICATION EVIDENCE
Trust Data Available
BuiltWith Trust API v2 evidence for borealhost.ai was fetched 2026-08-30T20:50:41.248Z.
borealhost.ai is assessed as Trusted: Domain runs a meaningful technology spend, consistent with a real business.
Evidence is source-attributed and does not guarantee that a third-party server is safe. Risk labels are conservative metadata heuristics.