# 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
Agent recipes: https://fatheron.dev/docs/agents
MCP registry manifest: https://fatheron.dev/.well-known/mcp/server.json

## 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.

## 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
- 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 (internal seed): see repo docs/agents/lander-templates.md

## 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, billing read, webhooks, sandbox status/simulate/plan, Research SKU (`research_domain`, `search_comps`, `list_drops`, `acquire_preview`, `research_entitlement`, watchlist).
Install order (reach): **VS Code Copilot** (https://fatheron.dev/docs/agents/vscode) → Claude → Cursor.

## Developer packages

- Starter: $29/month, 100,000 requests, 10 tenants, 10 keys, 30-day diagnostics, then $0.50/1,000 requests.
- Scale: $99/month, 1,000,000 requests, 100 tenants, 50 keys, 90-day diagnostics, then $0.20/1,000 requests.
- `GET /v1/developer/plans` is authoritative; `GET /v1/developer/entitlement` reports current usage and estimated overage.

## 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 (one key)

1. Follow https://fatheron.dev/docs/agents/get-started
2. Domainers: mint at https://app.fatheron.com/developers — Builders: https://app.fatheron.dev/keys
3. Prefer `fh_test_…` to rehearse, then `fh_live_…` to apply
4. Wire MCP (VS Code first) or `fh login`, then run a recipe

## 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/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
- Roadmap (not live): https://fatheron.dev/capabilities/hosting, https://fatheron.dev/capabilities/web-application-protection, https://fatheron.dev/capabilities/log-streaming