Escalation Host — agent integration reference

Hosting for AI-generated apps

Build your app with Claude / GPT / Codex / Cursor — then hand it off to your agent to host it on Escalation Host. The agent signs the user up, takes payment, deploys, watches for incidents, and writes itself notes for future sessions. This page is the reference for agent authors and MCP integrators.

Contents

MCP server (recommended)
REST API
Authentication
Transport encryption
Scope catalog
Plans
Error model

MCP server recommended

Single endpoint, JSON-RPC 2.0 over HTTP. All tools auto-discovered + scope-filtered. The initialize handshake surfaces open incidents and the LLM's notes index in _metadata so a fresh session has context immediately.

Claude Code

{
  "mcpServers": {
    "escalation-host": {
      "transport": "http",
      "url": "https://ai.escalation.tech/mcp",
      "headers": {
        "Authorization": "Bearer ahk_live_<your-key>"
      }
    }
  }
}

Codex CLI

codex mcp add escalation-host \
    --url https://ai.escalation.tech/mcp \
    --header "Authorization: Bearer ahk_live_<your-key>"

Tool catalog

Scope-filtered per call — agents without a key see only pre-auth tools (catalog + onboarding + access requests). With a key, they see the full surface based on what scopes were granted.

Group	Tools	Required scopes
catalog	get_service_catalog, get_pricing	none
onboarding	create_account, get_account_status, cancel_pending_account	none
access	request_access, get_access_request_status	none
account	get_account	account:read
apps	list_apps, get_app, create_app, delete_app	app:read, app:write
deploys	deploy_from_tarball, deploy_from_git, get_deploy_status, list_deploys	deploy:write
diagnostics	get_attention, get_incident, acknowledge_incident, resolve_incident, list_recent_incidents	app:read / app:write
notes	list_notes, read_note, write_note, append_to_note, delete_note	notes:read / notes:write

REST API

Equivalent to the MCP surface; useful for non-MCP clients or testing. Base: https://ai.escalation.tech

Agent intake (pre-auth)

Method + path	Purpose
`POST /api/agent/provisional-accounts`	Create signup; returns onboarding URL
`GET /api/agent/provisional-accounts/{pa_id}`	Status poll
`POST /api/agent/access-requests`	Magic-link key issuance
`GET /api/agent/access-requests/{areq_id}`	Pickup poll (needs pickup_secret)

Control plane (post-auth)

Method + path	Scope
`GET /api/v1/account`	account:read
`GET/POST/DELETE /api/v1/apps[/{app_id}]`	app:read / app:write
`POST /api/v1/apps/{app_id}/deploys`	deploy:write
`GET /api/v1/apps/{app_id}/logs`	logs:read
`GET /api/v1/attention`	app:read
`GET/POST/PUT/DELETE /api/v1/notes`	notes:read / notes:write

Authentication

API keys are issued either at signup (Stripe success page) or via the magic-link access request flow. Keys look like ahk_live_<8 hex prefix>_<48 hex secret>. Pass via Authorization: Bearer ahk_live_….

Lost your key? Call the request_access MCP tool — we email the user and they approve via magic link. The fresh key is released on your next poll.

Transport encryption

HTTPS is the baseline. On top, every endpoint accepts sealed-box body encryption to a published server key — so even Cloudflare cannot read your request bodies.

Public key discovery: GET /.well-known/ai-host-crypto.json

Current server public key:

7W9maijWuxnUsp9ul98a0cHCadumvkwsnnmHmOoAx0k=

Encrypt the body with sodium_crypto_box_seal to the server pubkey. Send with Content-Type: application/ai-host+sealed. For encrypted responses, supply your ephemeral pubkey in X-Ai-Host-Recipient-Pubkey.

Scope catalog

Scopes granted at key issuance. The user picks which to allow; the agent's tools/list is filtered to what the key holds.

Scope	Description
`account:read`	Read your account profile, current plan, and which scopes this key holds. Required for the agent to know what it can do.
`account:write`	Upgrade or downgrade your plan, change billing details. Typically gated behind an approval email.
`app:read`	See what apps exist on the account.
`app:write`	Create new apps. Deleting apps with data may require approval per your policy.
`deploy:write`	Upload tarballs or trigger git deploys. The core "ship code" capability.
`logs:read`	Read live tail and historical logs. Required to debug.
`secrets:read`	Decrypt environment variables for inspection. Off by default — the agent can SET secrets without being able to READ them back.
`secrets:write`	Set + delete environment variables. Includes secrets the agent generates or pastes in.
`domains:write`	Add or remove custom domains on your apps. Off by default; the user usually wants to confirm domain changes.
`domains:purchase`	Look up domain availability and initiate a one-time Stripe Checkout to register a domain on the user's behalf. The user pays at Stripe; we never charge a saved card without their explicit click. Off by default — spending real money is the kind of thing users want to opt into deliberately.
`billing:read`	View invoices and usage. Read-only — agents cannot move money.
`keys:write`	Let this agent grant scopes to OTHER agents. Always off by default — granting this is rare.
`notes:read`	Read your persistent notes / READMEs the agent (or prior sessions) wrote down. Cheap context the agent picks up at session start.
`notes:write`	Create + update persistent notes — the agent's "memory" so future sessions remember decisions, preferences, gotchas.
`tickets:read`	See the status + responses on tickets the agent (or prior sessions) opened. Required so future agent instances can pick up operator responses to earlier requests.
`tickets:write`	Submit a ticket on the user's behalf — typically "we don't support framework X" or "feature request". The user gets an email when the agent files one, so they're always in the loop.

Plans

Plan	Price (USD/mo)	Status
`builder` — Builder	$25	available
`hobby` — Hobby	$9	coming_soon

Error model

JSON envelope. request_id is on every response (mirror it on X-Request-Id) so support can correlate.

{
  "error": {
    "code": "insufficient_scope",
    "message": "Tool list_apps requires scope(s): app:read. This key holds: account:read. Ask the user to grant additional scopes at https://ai.escalation.tech/account/keys.php",
    "request_id": "req_..."
  }
}

Errors are actionable — the message tells you what to do next. MCP tool errors follow the same shape inside the JSON-RPC error field.

Rate limits

Token-bucket per minute, keyed by IP (pre-auth) or API key (post-auth). Exceeding returns 429 with Retry-After + X-RateLimit-Limit headers. Reads are generous (600/min); writes are tighter (30-60/min). Deploys are the most expensive.

Questions or issues — [email protected]