Skip to content

addons

Add to this order.

Add to one paid order, any time: kind phrases (count), engine (route_key: another AI), checks (count: more checks at the order's cadence), recheck (route_keys optional: every active phrase now, on those AIs or all), research (competitors a month), backlinks (competitors, cadence), keywords (size 100 or 500, keywords optional), upgrade (months: a one-off order checked monthly, its first check is month 1). quote (scan:read): the price at the order's own rates, the minimum-order line and the fill-up suggestions; nothing is charged. apply (scan:write): a Stripe Checkout link for just the extra, for the person to pay; an agent never pays and nothing is charged by the call. On a monthly-billed order an AI, phrases, backlinks or keywords go on the monthly payments from the next one instead: apply then answers needs_confirmation with the new monthly total and a confirm_token; show it to the person and only if they agree call again with the same arguments plus confirm_token. set_backlink_competitors (scan:write; domains): the competitors the backlinks add-on checks. No credit or balance exists.

Who can use it

Access
A paid order: a running one, or (for a recheck, more checks or monthly checks) one that finished in the last 30 days.
Scope
scan:read for reading; each write action's scope is below.
Changes anything
Its write actions do; see below.

Actions

Pass one in action.

actionScopeWhat it does
quotescan:readThe price of one addition at the order's own rates: its lines (the addition, the pay-once discount if the order had one, the minimum line), what is charged, how it is paid, and the fill-up suggestions under the minimum.
applyscan:writeA write action: the description above says what it changes.
set_backlink_competitorsscan:writeA write action: the description above says what it changes.

Inputs

NameTypeRequiredValues and limits
actionstringYesquote, apply, set_backlink_competitors
order_idstringYesAn order id from get_dashboard
kindstringNophrases, engine, checks, recheck, research, backlinks, keywords, upgrade. For quote and apply: what to add
countintegerNo1 to 200. For phrases and checks
route_keystringNo0 to 120 characters. For engine: an AI key (create_order's routes)
route_keysarray of stringNoat most 20 items. For recheck: AIs of this order (default all)
competitorsintegerNo0 to 100. For research (competitors a month) and backlinks (competitors besides your site)
cadencestringNomonthly, every_check. For backlinks
sizeintegerNo-9007199254740991 to 9007199254740991. For keywords: 100 or 500
keywordsarray of stringNoat most 600 items. For keywords: your own list (optional)
monthsintegerNo2 to 24. For upgrade: months in all
domainsarray of stringNoat most 20 items. For set_backlink_competitors
confirm_tokenstringNoOnly for a ⚠ action, on the second call: the confirm_token from the first answer, after the person agreed

What it answers

Every answer has status and, where useful, message in plain words.

FieldMeaning
lines, charge_usd, minimum_usdquote and apply: what the addition costs and what is charged (never less than the minimum order).
paid_bycheckout (one Stripe Checkout now), or next_monthly_payments (a monthly-billed order: per_month_usd, next_payment_usd, payments_left).
fill_upUnder the minimum: the message and up to three bigger versions of the same addition that still fit, each with its args for apply.
checkout_urlapply: the Stripe Checkout link for the person to pay. Nothing is charged until they do; an agent never pays.
status, summary, confirm_tokenapply for next_monthly_payments: needs_confirmation with the new monthly total; the second call with the token applies it.
competitorsset_backlink_competitors: the sites the backlinks add-on checks.

Errors

statusWhat it means
invalid_inputorder_id isn't an order id. Take one from get_dashboard.
not_foundNo order with that id on this account.
invalid_inputNo kind, a count out of range, something the order already has, or an AI that isn't sold now (the message says which).
not_availablePaid orders aren't open yet (the price still shows), or the account can't buy.
forbiddenapply and set_backlink_competitors need scan:write; apply on a monthly-billed order that raises the monthly payment also needs order:write (missing_scope and grant_url say where to tick it).
forbiddenThe credential lacks the tool's scope, or an agent's owner has no ScanFree account yet (the owner signs in on the website once).
Input validation errorAn argument doesn't match the schema below. The call fails with MCP error -32602, naming the field.

Errors before the tool runs (a missing key, too many requests) are on the MCP page.

Example

Example shape; values are illustrative.

The call
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "addons",
    "arguments": {
      "action": "quote",
      "order_id": "00000000-0000-4000-8000-000000000002",
      "kind": "phrases",
      "count": 5
    }
  }
}
The answer (structured content)
{
  "status": "ok",
  "order_id": "00000000-0000-4000-8000-000000000002",
  "kind": "phrases",
  "label": "5 more phrases",
  "lines": [
    {
      "label": "5 more phrases",
      "usd": "…"
    },
    {
      "label": "Minimum order: …",
      "usd": "…"
    }
  ],
  "charge_usd": "…",
  "minimum_usd": "…",
  "paid_by": "checkout",
  "fill_up": {
    "message": "This addition is … The minimum is …, so you'll pay … either way: you have … left to use.",
    "suggestions": [
      {
        "label": "Add 20 phrases instead",
        "usd": "…",
        "args": {
          "kind": "phrases",
          "count": 20
        }
      }
    ]
  },
  "note": "…",
  "message": "Nothing is charged by a quote. apply returns the Checkout link for the person to pay."
}