@awesomate/hosting-mcp/skill/awesomate-hosting/references/rest-fallback.md

Awesomate MCP server — lets Claude manage your Awesomate WordPress hosting, plan, limits, n8n automations, and build Node/static apps + databases

# REST fallback — no MCP tools in the session

If this skill is loaded but **no `awesomate_*` tools exist in the session at
all**, the MCP server was registered after Claude Code started (the bootstrap
just ran). Don't investigate settings files or reinstall anything — and don't
make a restart the precondition for showing the user their own data. The
skill works right now over REST.

## Resolve the PAT first

Run `node ~/.claude/skills/awesomate-hosting/scripts/resolve-account.mjs
--api` to get `API`/`PAT`/`ACCT` for the ACTIVE profile. Never read top-level
`pat` directly when a `profiles` map exists, and never echo the pat into the
conversation.

## Endpoint map

GET with `Authorization: Bearer <pat>`:

| MCP tool | REST equivalent |
|---|---|
| `awesomate_get_context` | `GET {apiBase}/api/hosting-access/context` |
| `awesomate_get_hosting_status` | `GET {apiBase}/api/client-hosting/status` |
| `awesomate_get_hosting_account` | `GET {apiBase}/api/client-hosting/account` |
| `awesomate_list_sites` | `GET {apiBase}/api/client-hosting/sites` |
| `awesomate_list_domains` | `GET {apiBase}/api/client-hosting/domains` |
| `awesomate_get_limits` | `GET {apiBase}/api/client-hosting/limits` |

## Creating a site over REST

`POST {apiBase}/api/client-hosting/sites` (JSON, same bearer) is the fallback
for `awesomate_site_create`. Three things about it trip people up:

- **The body field is `siteTitle`, not `title`.** An unknown key is ignored
  silently, so the site ends up titled after its domain. `domain`, `themeSlug`,
  `adminEmail` and `intent` are the other accepted keys; all are optional.
- **Omit `domain` and the server picks the next free `siteN.{primary}`** —
  the first install takes the bare primary domain, then `site2`, `site3`, and
  so on. Pass `domain` explicitly if the user named one.
- **The response is bare `{"success":true}`** — no domain, no id. It does not
  tell you what got built, so read the name back from `GET /sites`.

Refusals are specific and worth relaying verbatim: `403` means the plan's site
cap is reached (staging clones are excluded from the count), `409` means
WordPress already exists at that domain.

## Provisioning is async — do not call it broken

The POST returns as soon as the install is queued. Poll
`GET {apiBase}/api/client-hosting/sites` until the new hostname appears rather
than assuming the call failed.

Then expect a **gap of a minute or two where HTTPS does not answer at all**
while AutoSSL issues the certificate. During that window the symptom looks
alarming but is normal and self-resolving:

| Check | During issuance | Meaning |
|---|---|---|
| `curl https://…` | `000` / connection failed | Cert not issued **yet** |
| `curl http://…` | `200`, real WordPress HTML | The site is genuinely built |
| `dig +short` | resolves to the hosting IP | DNS is fine |
| `/sites` `sslActive` | may already say `true` | Reports intent, not the live cert |

So: an HTTPS failure straight after creation is not a failed build. Confirm
over plain HTTP, tell the user the certificate is still issuing, and poll
HTTPS until it answers. Do not delete and recreate the site, and do not go
hunting through DNS or Cloudflare — `sslActive: true` alongside a dead HTTPS
port is the expected intermediate state, not a contradiction.

New sites come up on the host's default theme (currently
`hello-elementor`). If the user asked for a custom theme, that is still ahead
of you — the fresh install is not evidence their theme shipped.

Serve the request with these now, then suggest restarting Claude Code at a
natural break so the richer MCP integration loads.