Skip to main content

Quickstart

This page takes you from "no Clone account" to "first prediction" in roughly five minutes. Pick one path:

  • REST — curl the public API directly. Best for languages without an MCP client and for understanding the underlying surface.
  • MCP — drop Clone into Claude Code, Cursor, or Claude Desktop and let your agent call it. Best for everyday use.

Both paths assume you already have an account on clone.is (or a self-hosted instance — see Self-hosting).

Path A — REST​

1. Issue an API key​

API keys are long-lived bearer credentials starting with clone_…. Issue one from POST /api/auth/keys/ (see Authentication) or from the API Keys page in the web dashboard. Treat it like a password — anyone holding the key can act as you.

export CLONE_API_TOKEN="clone_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
export CLONE_API_URL="https://api.clone.is"

2. Push a few events into Recording​

Predictions get markedly better once Clone has seen how you actually reply, so seed the Recording layer first. The wire shape is CloneEvent (see Schema):

curl -sS -X POST "$CLONE_API_URL/api/recording/events/" \
  -H "X-Clone-API-Key: $CLONE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "id": "evt-1",
      "session_id": "demo-session",
      "occurred_at": "2026-05-05T12:00:00Z",
      "source": "agent",
      "source_detail": "claude-code",
      "type": "agent.prompt",
      "agent": "Claude Code",
      "prompt": "Test finished. What next?"
    }
  ]'

Expected response: { "accepted": 1, "duplicates": 0, "invalid": [] }. The endpoint is idempotent on id, so re-sending returns duplicates: 1 rather than recording it twice.

Common ingest mistake

source is an enum — desktop | cli | mobile | smartglass | agent | integration. Free-form strings like "claude-code" go in source_detail, not source. See FAQ and Schema.

3. Ask Clone to predict​

curl -sS -X POST "$CLONE_API_URL/api/predictions/predict/" \
  -H "X-Clone-API-Key: $CLONE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "Claude Code",
    "agent_input": "Test finished. What next?",
    "k": 3,
    "threshold": 0.8
  }'

The response includes predicted_response, calibrated confidence, the model's reasoning, and a ranked candidates list. status is server-decided:

  • auto — top candidate's confidence ≥ threshold. Your client should act on the prediction without paging the human.
  • escalated — confidence below threshold. Route to the human.

Cold-start predictions usually return escalated with mid-band confidence (~0.3–0.5); confidence rises as Memory accumulates real history.

Once you know what the user actually typed, write it back so Clone can compute precision and improve calibration:

curl -sS -X POST "$CLONE_API_URL/api/predictions/<prediction-id>/feedback/" \
  -H "X-Clone-API-Key: $CLONE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status":"edited","actual_response":"…what they actually typed…"}'

status is one of accepted (used Clone's prediction as-is), edited (typed something different — actual_response required), or rejected (discarded).

Path B — MCP​

1. Issue an API key​

Same as Path A step 1 — either via the dashboard or POST /api/auth/keys/.

2. Install the MCP server​

From a Claude Code session:

claude mcp add clone -- npx -y @clone/mcp \
  -e CLONE_API_URL=https://api.clone.is \
  -e CLONE_API_TOKEN="$CLONE_API_TOKEN"

Cursor, Claude Desktop, and other MCP-aware clients use the same shape — point them at the @clone/mcp package and pass the two env vars. Tokens that start with clone_ are sent as X-Clone-API-Key automatically; anything else is treated as a JWT and sent as Authorization: Bearer ….

If you'd rather use the multi-tenant hosted endpoint, install it via Smithery — see Self-hosting → Smithery.

3. Verify the install​

In your agent, ask it to call the predict_next_prompt tool with any agent prompt. The tool returns the same shape as POST /api/predictions/predict/ — see predict_next_prompt for the full input/output reference.

Where to go next​

  • Architecture — the layered model behind these endpoints.
  • MCP Server reference — tool-by-tool detail with verified payloads.
  • API Reference — full REST surface, auth, error codes.
  • FAQ — every gotcha new self-hosters trip over (DNS, schema enums, 504s, cold-start confidence).