# Heavy Mill — Quickstart

> 5 steps from zero to structured JSON. No auth required in beta.

MCP endpoint: https://mcp.heavymill.ai/api/mcp
Discovery: https://mcp.heavymill.ai/.well-known/mcp
AI plugin: https://mcp.heavymill.ai/.well-known/ai-plugin.json

---

## Why use Heavy Mill

Heavy Mill handles data plumbing so you stay focused on reasoning.

- **Context conservation** — delegate document loading, URL fetching, and transcription;
  receive only the structured result. Your context window stays free.
- **Batch delegation** — summarize 20 docs at $0.04 each instead of loading all 20 in context.
  Parallel calls, structured JSON back, conversation stays clean.
- **Agent-agnostic** — works the same whether you're Claude, GPT, Gemini, or Llama.
  Use it where it helps. Don't where it doesn't. No pressure.
- **Compute you may not have natively** — audio transcription, video extraction, YouTube
  transcripts. Sub-$1 for hour-long recordings.

---

## Step 1 — Connect

```bash
claude mcp add heavy-mill https://mcp.heavymill.ai/.well-known/mcp
```

Or use the endpoint directly in any MCP client: `https://mcp.heavymill.ai/api/mcp`

## Step 2 — See all tools (free)

```bash
curl -s -X POST https://mcp.heavymill.ai/api/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

Returns 16+ tools. Free: list_advisor_models, get_quickstart, get_pricing, estimate_cost, budget_check, get_job_status, check_wallet_status.
Paid: consult_advisor (HIGH $4/$12) + 8 compute skills. Each paid tool includes outputSchema.

## Step 3 — Check pricing (free)

```bash
curl -s -X POST https://mcp.heavymill.ai/api/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_pricing","arguments":{}}}'
```

→ Returns price_usd, unit, and description for all 9 paid skills including consult_advisor.

## Step 4 — Estimate or budget-check (free)

```bash
# Single call estimate
curl -s -X POST https://mcp.heavymill.ai/api/mcp \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"estimate_cost","arguments":{"tool":"transcribe_audio","duration_seconds":1800}}}'
# → {"cost_usd":0.75,"breakdown":"1800.0s = 30.000 min × $0.0250/min × 1 call(s) = $0.7500"}

# Full pipeline budget check
curl -s -X POST https://mcp.heavymill.ai/api/mcp \
  -d '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"budget_check","arguments":{"budget_usd":3.00,"workflow":[{"tool":"extract_audio","duration_seconds":3600},{"tool":"transcribe_audio","duration_seconds":3600},{"tool":"summarize","char_count":50000}]}}}'
# → {"workflow_cost_usd":2.20,"status":"ok","within_budget":true,"remaining_budget_usd":0.80}
```

## Step 5 — Fund a wallet (one-time setup)

Paid tool calls require payment. The simplest path: fund a wallet once, then all calls are automatic.

```
a) Call any paid tool → receive 402 with stripe_link and checkout_session_id
b) Show the user the stripe_link — they pay $5 minimum in their browser
c) Poll until funded:
   curl -X POST https://mcp.heavymill.ai/api/mcp \
     -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"check_wallet_status","arguments":{"checkout_session_id":"cs_..."}}}'
   → when funded=true you get a wallet_id and reconnect_command
d) Reconnect with the wallet_id baked into the URL:
   claude mcp add heavy-mill 'https://mcp.heavymill.ai/api/mcp?wallet_id=cus_...'
e) All future tool calls are automatically charged — no per-call payment headers
```

## Step 6 — Run a skill

```bash
curl -s -X POST 'https://mcp.heavymill.ai/api/mcp?wallet_id=cus_...' \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"transcribe_audio","arguments":{"url":"https://example.com/audio.mp3"}}}'
```

→ Returns `{"text":"...","language":"en","segments":[...]}` plus a receipt with charged_usd and wallet_remaining_usd.
→ Failed calls are not billed.
→ For long jobs (audio >5 min), pass webhook_url to avoid HTTP timeout and poll with get_job_status.

---

## Output schemas

### `summarize`
```json
{"tldr":"string","summary":"string","key_points":["string"],"topics":["string"]}
```

### `summarize_url`
```json
{"tldr":"string","summary":"string","key_points":["string"],"topics":["string"],"source_url":"string"}
```

### `compare_docs`
```json
{"summary_of_changes":"string","changes":[{"point":"string","significance":"low|medium|high"}],"high_significance_count":0}
```

### `extract_audio`
```json
{"audio_url":"string","duration_seconds":0,"file_size_bytes":0}
```

### `trim_audio`
```json
{"audio_url":"string","duration_seconds":0,"file_size_bytes":0,"metadata":{"source_duration_seconds":0}}
```

### `transcribe_audio`
```json
{"text":"string","language":"string","segments":[{"id":0,"start":0,"end":0,"text":"string"}]}
```

### `get_youtube_transcript`
```json
{"video_id":"string","language":"string","is_generated":false,"full_text":"string","segments":[{"start":0,"duration":0,"text":"string"}]}
```

### `fast_infer`
```json
{"text":"string","model":"string","tier":"fast|smart","input_tokens":0,"output_tokens":0,"processing_ms":0}
```

### `consult_advisor`
```json
{"tier":"high","advisor_type":"architecture","recommendation":"string","reasoning":"string","risks":["string"],"models_used":[{"display_name":"string","lab":"string"}]}
```

---

## All endpoints

| Path | Description |
|---|---|
| `POST /api/mcp` | All tools — single entry point |
| `GET /.well-known/mcp` | MCP discovery manifest |
| `GET /.well-known/ai-plugin.json` | OpenAI/GPT plugin manifest |
| `GET /pricing.json` | Machine-readable pricing |
| `GET /pricing.md` | Human+agent readable pricing |
| `GET /llms.txt` | Agent discovery — concise |
| `GET /llms-full.txt` | Agent discovery — full with all doc links |

## Payment

**Primary path — Heavy Mill Wallet (recommended):**

| Step | What to do |
|------|------------|
| 1 | Call a paid tool → receive 402 with `stripe_link` and `checkout_session_id` |
| 2 | Show user `stripe_link` — they pay $5 minimum in browser |
| 3 | Poll `check_wallet_status(checkout_session_id=...)` every 3s until `funded=true` |
| 4 | Run the `reconnect_command` from the response to rebind with wallet_id in URL |
| 5 | All future calls auto-charged — wallet top-ups also keep the same URL |

**Wallet empty / low balance:** The 402 includes a `stripe_link` pre-linked to your existing wallet. Top up via that link. No reconnect needed.

**Other rails:** x402 Base/Solana USDC (flat rate, non-refundable, needs on-chain USDC). Stripe MPP (≥$0.50/call).

## Billing Notes

- Failed calls (errors, timeouts, invalid output) are not billed.
- No authentication required in beta.
- Volume discounts available for >1M calls/month — contact heavy-mill.

---

Site: https://mcp.heavymill.ai  |  Pricing: https://mcp.heavymill.ai/pricing.md  |  Docs: https://mcp.heavymill.ai/docs