Fat Heron
API v1Stable major · additive within v1

Fat Heron MCP

Contract-first REST for builders and agents. Same control plane as Fat Heron products — documented here for the developer surface.

Open live SwaggerVersioning policyAgent recipesHuman guidesGet startedGet API keys

Fat Heron is an MCP-first control plane for AI-supported developers. The official server (com.fatheron/fat-heron, npm @fat-heron/mcp) maps tools to the live /v1 API. Auth with an account API key — never put secrets in chat logs. New here? Start at Get started.

Env on every install: FH_API_KEY (required), optional FH_API_URL (default https://api.fatheron.dev).

1. Mint a key

Create a key at app.fatheron.dev/keys (builders) or app.fatheron.com/developers (portal / domainers). Use fh_test_ for sandbox rehearsal.

2. VS Code + GitHub Copilot

Largest installed base — preferred default. Full walkthrough + verify checklist: /docs/agents/vscode.

  1. Install GitHub Copilot Chat (agent/MCP capable build).
  2. Copy .vscode/mcp.json.example → .vscode/mcp.json (root key servers; use inputs for the API key).
  3. Command Palette → MCP: List Servers → start fat-heron.
  4. Copilot Agent: call sandbox_status, then create a sandbox project.

Workspace (recommended)

{
  "inputs": [
    {
      "type": "promptString",
      "id": "fh-api-key",
      "description": "Fat Heron API key (fh_test_… or fh_live_…)",
      "password": true
    }
  ],
  "servers": {
    "fat-heron": {
      "type": "stdio",
      "command": "node",
      "args": ["${workspaceFolder}/packages/mcp/dist/stdio.js"],
      "env": {
        "FH_API_KEY": "${input:fh-api-key}",
        "FH_API_URL": "https://api.fatheron.dev"
      }
    }
  }
}

Build once: npm run build -w @fat-heron/mcp. On the app VM: /opt/fatheron/packages/mcp/dist/stdio.js.

3. Claude Desktop / Claude Code

  1. Claude Desktop: Settings → Developer → Edit Config → open claude_desktop_config.json.
  2. Claude Code: add the same server block to project .mcp.json (or user MCP config).
  3. Restart Claude / reload MCP, then ask for sandbox_status.
{
  "mcpServers": {
    "fat-heron": {
      "command": "node",
      "args": ["/absolute/path/to/packages/mcp/dist/stdio.js"],
      "env": {
        "FH_API_KEY": "fh_live_…",
        "FH_API_URL": "https://api.fatheron.dev"
      }
    }
  }
}

4. Cursor

  1. Project .cursor/mcp.json or user ~/.cursor/mcp.json.
  2. Cursor Settings → MCP → refresh / enable fat-heron.
  3. In Agent chat, verify tools appear (projects, aliases, sandbox_*).
{
  "mcpServers": {
    "fat-heron": {
      "command": "node",
      "args": ["/absolute/path/to/packages/mcp/dist/stdio.js"],
      "env": {
        "FH_API_KEY": "fh_live_…",
        "FH_API_URL": "https://api.fatheron.dev"
      }
    }
  }
}

VM path example: /opt/fatheron/packages/mcp/dist/stdio.js.

5. Tools

  • get_developer_entitlement — package limits, usage, overage estimate, and reset
  • list_managed_tenants / create_managed_tenant / revoke_managed_tenant
  • list_projects / create_project
  • list_api_keys / create_api_key
  • list_aliases / check_alias / claim_alias
  • start_dns_delegation / verify_dns_ns / get_dns
  • get_billing
  • list_webhooks / create_webhook
  • sandbox_status / sandbox_simulate / sandbox_plan

Tenant-aware tools accept target_account_id. The key must also have an explicit binding to that managed customer tenant; action scopes alone never grant tenant access. Omitting the target uses the key owner's account.

6. Remote HTTP (optional)

Streamable HTTP for hosts that prefer HTTP over stdio: PORT=3104 node packages/mcp/dist/http.js. The /mcp endpoint accepts an API key or OAuth access token and publishes protected-resource metadata at /.well-known/oauth-protected-resource. Hosted remote URL comes next.

7. Machine discovery

Canonical MCP Registry name: com.fatheron/fat-heron. Agents and directories can read the server manifest, llms.txt, and the OpenAPI document.

Hosting, web application protection, and log-stream tools are not advertised until their control-plane APIs are operational.

Get started · All agent recipes · llms.txt

MCP server · Fat Heron Developers