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:readfor reading; each write action's scope is below.- Changes anything
- Its write actions do; see below.
Actions
Pass one in action.
| action | Scope | What it does |
|---|---|---|
quote | scan:read | The 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. |
apply | scan:write | A write action: the description above says what it changes. |
set_backlink_competitors | scan:write | A write action: the description above says what it changes. |
Inputs
| Name | Type | Required | Values and limits |
|---|---|---|---|
action | string | Yes | quote, apply, set_backlink_competitors |
order_id | string | Yes | An order id from get_dashboard |
kind | string | No | phrases, engine, checks, recheck, research, backlinks, keywords, upgrade. For quote and apply: what to add |
count | integer | No | 1 to 200. For phrases and checks |
route_key | string | No | 0 to 120 characters. For engine: an AI key (create_order's routes) |
route_keys | array of string | No | at most 20 items. For recheck: AIs of this order (default all) |
competitors | integer | No | 0 to 100. For research (competitors a month) and backlinks (competitors besides your site) |
cadence | string | No | monthly, every_check. For backlinks |
size | integer | No | -9007199254740991 to 9007199254740991. For keywords: 100 or 500 |
keywords | array of string | No | at most 600 items. For keywords: your own list (optional) |
months | integer | No | 2 to 24. For upgrade: months in all |
domains | array of string | No | at most 20 items. For set_backlink_competitors |
confirm_token | string | No | Only 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.
| Field | Meaning |
|---|---|
lines, charge_usd, minimum_usd | quote and apply: what the addition costs and what is charged (never less than the minimum order). |
paid_by | checkout (one Stripe Checkout now), or next_monthly_payments (a monthly-billed order: per_month_usd, next_payment_usd, payments_left). |
fill_up | Under the minimum: the message and up to three bigger versions of the same addition that still fit, each with its args for apply. |
checkout_url | apply: the Stripe Checkout link for the person to pay. Nothing is charged until they do; an agent never pays. |
status, summary, confirm_token | apply for next_monthly_payments: needs_confirmation with the new monthly total; the second call with the token applies it. |
competitors | set_backlink_competitors: the sites the backlinks add-on checks. |
Errors
| status | What it means |
|---|---|
invalid_input | order_id isn't an order id. Take one from get_dashboard. |
not_found | No order with that id on this account. |
invalid_input | No kind, a count out of range, something the order already has, or an AI that isn't sold now (the message says which). |
not_available | Paid orders aren't open yet (the price still shows), or the account can't buy. |
forbidden | apply 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). |
forbidden | The 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 error | An 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.
{
"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
}
}
}{
"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."
}