# Fat Heron for Developers

> Fat Heron is an MCP-first control plane for AI-supported developers. Agents use it to manage isolated customer tenants across mail, DNS, projects, keys, webhooks, diagnostics, and metered domain research with explicit action scopes and tenant bindings. No UI click-ops required.

Base API: https://api.fatheron.dev
OpenAPI JSON: https://api.fatheron.dev/openapi.json
Swagger UI: https://api.fatheron.dev/docs
App (keys / projects): https://app.fatheron.dev
Portal (domainers keys): https://app.fatheron.com/developers
Docs: https://fatheron.dev/docs
**Human guides (less technical):** https://fatheron.dev/docs/guides
**Get started (humans + agents):** https://fatheron.dev/docs/agents/get-started
**Connect Grok (Custom MCP — no key in chat):** https://fatheron.dev/docs/agents/grok
**Already have a key (plain text — fetch this):** https://fatheron.dev/docs/agents/http.txt
**Already have a key (HTML):** https://fatheron.dev/docs/agents/http
Agent recipes: https://fatheron.dev/docs/agents
MCP registry manifest: https://fatheron.dev/.well-known/mcp/server.json
Remote MCP (Streamable HTTP): https://api.fatheron.dev/mcp

## Auth

- Prefer `X-API-Key: fh_live_…` (or `fh_test_…`) on every request.
- Send `X-FH-Account: <managed-account-uuid>` only when acting on a managed customer tenant. The API key must be explicitly bound to that tenant.
- Session JWT also works: `Authorization: Bearer <token>`.
- `fh_test_` enables **sandbox mode**: dry-run for aliases/DNS/billing/webhooks; `sb-` namespaced builder projects; simulate recipes; plan → promote with a live key.
- **If the user already gave you a key: call the API now.** `GET /v1/sandbox/status` with `X-API-Key`, then the matching recipe. Do not send them to the portal. Do not ask them to run curl or paste output. Never echo the full secret. A 401 without the header means the endpoint exists — send the header and retry.
- Mint keys with a **preset**, not a scope list: `domainer_full` (landers / portfolio) or `developer_full` (builders / tenants). `POST /v1/api-keys` `{ "label", "key_kind": "live", "preset": "domainer_full" }`.

## Honesty

- Agency whitelabel (your brand on your hostname) is roadmap (DV2), not live.
- Hosting, web application protection, and log-stream control-plane tools are roadmap; do not claim them as live MCP capabilities.
- Seller landers and storefronts are live; do not claim full whitelabel.
- Customer-facing copy must stay vendor-free (never name internal mail/DNS/auth stack products in landers, emails, or activity text).

## Human guides (goal-first)

- Guides hub: https://fatheron.dev/docs/guides
- Who am I? (persona picker): https://fatheron.dev/docs/guides/who-am-i
- Choose your path: https://fatheron.dev/docs/guides/choose-your-path
- Claim your inbox: https://fatheron.dev/docs/guides/claim-your-inbox
- Use your email: https://fatheron.dev/docs/guides/use-your-email
- Domainers day one: https://fatheron.dev/docs/guides/domainers-day-one
- Domainers how-to: https://fatheron.dev/docs/guides/domainers-howto
- Portfolio TCO & registrar billing: https://fatheron.dev/docs/guides/domainers-tco-billing
- Research with an AI assistant: https://fatheron.dev/docs/guides/research-with-an-assistant
- Use Research properly: https://fatheron.dev/docs/guides/use-research-properly

## Recipe index (imperative)

- Get started (domainers + builders): https://fatheron.dev/docs/agents/get-started
- Connect Grok: https://fatheron.dev/docs/agents/grok
- Already have a key (plain text): https://fatheron.dev/docs/agents/http.txt
- Already have a key (HTML): https://fatheron.dev/docs/agents/http
- VS Code + Copilot (verified): https://fatheron.dev/docs/agents/vscode
- MCP install (VS Code / Claude / Cursor): https://fatheron.dev/docs/agents/mcp
- CLI + SDK: https://fatheron.dev/docs/agents/cli
- Sandbox: https://fatheron.dev/docs/agents/sandbox
- Create project: https://fatheron.dev/docs/agents/create-project
- Mint API key: https://fatheron.dev/docs/agents/api-keys
- Manage customer tenants: https://fatheron.dev/docs/agents/managed-tenants
- Create webhook: https://fatheron.dev/docs/agents/webhooks
- Claim alias: https://fatheron.dev/docs/agents/claim-alias
- Attach DNS (NS delegation): https://fatheron.dev/docs/agents/attach-dns
- Domain research (Research SKU): https://fatheron.dev/docs/agents/domain-research
- Lander templates (static HTML on a portfolio domain): https://fatheron.dev/docs/agents/lander-templates

## MCP

Canonical registry name: `com.fatheron/fat-heron`.
Package: `@fat-heron/mcp` (monorepo `packages/mcp`).
Stdio entry: `node packages/mcp/dist/stdio.js` with env `FH_API_KEY` (+ optional `FH_API_URL`).
Tools: developer entitlement, managed customer tenants, list/create project, API keys, aliases, DNS, landers (`list_portfolio_domains`, `list_landers`, `create_lander`, `assign_lander`), billing read, webhooks, sandbox status/simulate/plan, Research SKU (`research_domain`, `research_same_owner`, `research_owner_cluster`, `search_comps`, `list_drops`, `acquire_preview`, `research_entitlement`, watchlist).
Install order (reach): **VS Code Copilot** (https://fatheron.dev/docs/agents/vscode) → Claude → Cursor. Grok: Custom MCP connector at https://fatheron.dev/docs/agents/grok (no key in chat). Other chat assistants: REST (https://fatheron.dev/docs/agents/http.txt). Hosted MCP: `https://api.fatheron.dev/mcp`.

## Developer packages

- Starter: $29/month, 100,000 requests, 10 tenants, 10 keys, 30-day diagnostics, **10 mailboxes + 10 aliases per onboarded domain** (25 GB), then $0.50/1,000 requests.
- Scale: $99/month, 1,000,000 requests, 100 tenants, 50 keys, 90-day diagnostics, **25 mailboxes + 25 aliases per onboarded domain** (50 GB), then $0.20/1,000 requests.
- Included mail is provisioned onto the developer org account and managed customer tenants (`send_receive`). Domain caps are binding; account ceilings are soft headroom.
- `GET /v1/developer/plans` is authoritative; `GET /v1/developer/entitlement` reports current usage, estimated overage, and per-domain mail quotas.
- Over-cap creates return `domain_alias_limit_reached` / `domain_mailbox_limit_reached`.

## CLI + SDK

Package: `@fatheron/sdk` (bin `fh`).
Entry: `node packages/sdk/dist/cli.js` or `/opt/fatheron/packages/sdk/dist/cli.js`.
Commands: `fh login`, `fh project`, `fh alias`, `fh dns`, `fh billing`, `fh research`, `fh webhook`, `fh sandbox`, `fh apply`, `fh promote`.
Docs: https://fatheron.dev/docs/agents/cli
Thin Python: `packages/sdk-python/fatheron_client.py`

## Quick start (already have a key)

1. Call `GET https://api.fatheron.dev/v1/sandbox/status` with `X-API-Key: $FH_API_KEY`
2. Lander / HTML on a portfolio domain → https://fatheron.dev/docs/agents/lander-templates
3. Alias → claim-alias · DNS → attach-dns · project → create-project
4. Recipe hub: https://fatheron.dev/docs/agents/http.txt

## Quick start (need a key)

1. `POST /v1/api-keys` with `{ "label": "agent", "key_kind": "live", "preset": "domainer_full" }` (or `developer_full`)
2. Or pick that preset in the Keys UI — do not tick individual scopes
3. Then follow “already have a key” above

## Core endpoints

- `POST /v1/builders/projects` — create workspace (`builders:write`); sandbox forces `sb-` slug
- `GET /v1/developer/entitlement` — developer package limits, usage, overage estimate, and reset
- `GET|POST /v1/developer/tenants` — list/create isolated managed customer environments
- `GET|POST /v1/api-keys` — list/create keys (`keys:write` to mint via API key)
- `POST /v1/notifications/webhooks` — outbound events (`notifications:write`); dry-run under `fh_test_`
- `POST /v1/aliases` — claim alias (`aliases:write`); dry-run under `fh_test_`
- `POST /v1/portfolio/domains/{domain_id}/dns/start-delegation` — FH DNS control (`domains:write`); dry-run under `fh_test_`
- `GET /v1/portfolio/domains` — list portfolio domains + lander assignment fields (`domains:read`)
- `GET|POST /v1/portfolio/landers` — list / create sanitized static HTML templates (`landers:read` / `landers:write`)
- `POST /v1/portfolio/landers/assign` — assign apex or /buy lander to domain_ids (`landers:write`); seller role required
- `GET /public/v1/apex-lander` — public serve check; send `Host: example.com` (no API key)
- `GET /v1/billing` — subscription snapshot (`billing:read`)
- `GET /v1/sandbox/status` — sandbox mode + dry-run catalog
- `POST /v1/sandbox/simulate` — failure recipes (test key)
- `POST /v1/sandbox/plan` — reviewable apply plan
- `POST /v1/sandbox/promote` — execute plan with live key
- `GET /v1/research/entitlement` — Research SKU quota (`research:read`)
- `GET /v1/domainers/research/{domain}` — research card + availability (`research:read`; metered)
- `GET /v1/domainers/comps` — owned comps search (`research:read`; metered)
- `GET /v1/domainers/drops` — drop snapshots (`research:read`; metered)
- `GET /v1/domainers/acquire/preview/{domain}` — availability / acquire bridges (`research:read`; metered)

## Research SKU

- Scopes: `research:read` / `research:write` (also satisfied by `domainers:*` or legacy `read`/`write`).
- Domainers seller/broker/domainer accounts: unlimited (bundled).
- Builders / external keys: monthly included + `research_credits_balance`; `402 research_quota_exceeded` when empty.
- Recipe: https://fatheron.dev/docs/agents/domain-research

## Discovery identifiers

- MCP Registry: `com.fatheron/fat-heron`
- npm: `@fat-heron/mcp`
- Manifest: https://fatheron.dev/.well-known/mcp/server.json
- OpenAPI: https://api.fatheron.dev/openapi.json
- DNS agents: https://fatheron.dev/capabilities/dns
- Mail agents: https://fatheron.dev/capabilities/mail
- Project agents: https://fatheron.dev/capabilities/projects
- Webhook agents: https://fatheron.dev/capabilities/webhooks
- Domain research agents: https://fatheron.dev/capabilities/domain-research
- Lander / storefront agents: https://fatheron.dev/capabilities/brand
- Roadmap (not live): https://fatheron.dev/capabilities/hosting, https://fatheron.dev/capabilities/web-application-protection, https://fatheron.dev/capabilities/log-streaming