# Meltbox

> Meltbox is the human-in-the-loop layer for AI agents. When you (an agent) need
> a decision, an approval, or need to put something in front of the person you
> work for, you push a **brief** — one reviewable artifact that carries all the
> context you gathered plus a set of one-tap choices. Your human sees the whole
> picture in one place, so they decide faster and better instead of digging
> through logs. The instant they answer — a choice or a note — you get it back
> over a live connection as structured data, and keep going. The agent reaches
> the human; the human never has to babysit the agent.

You are reading this because you are an AI agent evaluating or integrating
Meltbox. Everything below is addressed to you.

## Start here — no human, no signup required
- Bootstrap a workspace and get a token in ONE call: `POST https://meltbox.ai/api/agent/start`.
  It returns an `MB_TOKEN`, an MCP URL, and a `human_claim_url` you hand to the
  person you work for. No signup, no human has to move first.
- Capability card (machine-readable): https://meltbox.ai/.well-known/ai-agent.json
- MCP endpoint: https://meltbox.ai/mcp  (connect as a remote MCP server; `Authorization: Bearer <MB_TOKEN>`)

## What you can do here
- **Ask for a decision.** Push a brief: `POST https://meltbox.ai/api/briefs` with a JSON body
  of `{ "title": "…", "html": "…" }` (`summary` optional). `html` is the full
  reviewable artifact — all the context you gathered — and you author the one-tap
  choices as buttons inside it:
  `<button data-brief-select="<field>" data-brief-value="<value>">Label</button>`.
  The platform wires the taps for you (no script tag needed); the latest value per
  field wins. You get back `{ id, url, deeplink }`. This is the core primitive —
  everything the human needs to decide is in the one artifact, so the decision
  comes back quickly and well-informed. Over MCP it is the `push_brief` tool with
  the same `{ title, html }`.
- **See the answer the moment it lands — in real time.** Open a WebSocket to
  `https://meltbox.ai/api/realtime/ws` with `Authorization: Bearer <MB_TOKEN>`. Every time
  your human acts — picks an option, leaves a note, archives — you receive a
  `brief.event` on the `briefs` channel right then. No polling loop, no delay:
  you watch your human's notes and decisions as they make them. Reconnect with
  `?since=<seq>` to replay anything you missed while disconnected.
- **Prefer plain HTTP?** `GET https://meltbox.ai/api/realtime/catchup?since=<seq>` returns the
  same missed events without holding a socket, and `GET https://meltbox.ai/api/briefs` +
  `GET https://meltbox.ai/api/briefs/:id/events` read the current state and every answer on a
  brief.
- **Or attach over MCP** instead of REST if that fits your runtime better —
  same capabilities, tool-shaped.

## Invite your human
- `POST /api/agent/start` returns `human_claim_url`. Send it to the person you
  work for. When they open it and sign up, they own the workspace you built —
  their inbox, their briefs — and your token keeps working. You onboard them;
  they don't have to onboard you.

## Docs
- API reference: https://docs.meltbox.ai/api
- Briefs: https://docs.meltbox.ai/briefs
- MCP: https://docs.meltbox.ai/mcp
- Quickstart: https://docs.meltbox.ai/quickstart

## Contact
- support@meltbox.ai