Skip to content

programs

Directory, press and blog programs.

The checklists that come with longer paid orders (directories, press wires, republishing). get (scan:read): whether they are unlocked, and each place with the person's status (todo, submitted, live), its live address and whether AI cited it since. set_item (scan:write; program, item, status, and url when live): the person's status for one place; a live address is tracked as a published page. Set only what the person did.

Who can use it

Access
Paid orders with enough checks for the checklists.
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. Without it: get.

actionScopeWhat it does
getscan:readWhether the checklists are open to this order, and each place with the person's status.
set_itemscan:writeA write action: the description above says what it changes.

Inputs

NameTypeRequiredValues and limits
actionstringNoget, set_item. Default get
order_idstringYesAn order id from get_dashboard
programstringNodirectory, press, blog
itemstringNo0 to 100 characters. An item key from action get
statusstringNotodo, submitted, live
urlstringNo0 to 500 characters. For status live: the page's address

What it answers

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

FieldMeaning
unlocked, read_only, closed, checks, min_checksWhether the checklists are open, and the checks they need.
programs[]key, title, live, and items: key, name, href, note, status (todo, submitted, live), live_url, cited_since_live, cited_count, checks_since.

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_inputAn action that isn't in the list.
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": "programs",
    "arguments": {
      "action": "get",
      "order_id": "00000000-0000-4000-8000-000000000002"
    }
  }
}
The answer (structured content)
{
  "status": "ok",
  "order_id": "00000000-0000-4000-8000-000000000002",
  "unlocked": true,
  "read_only": false,
  "closed": false,
  "checks": 3,
  "min_checks": 3,
  "programs": [
    {
      "key": "directories",
      "title": "…",
      "live": 1,
      "items": [
        {
          "key": "…",
          "name": "…",
          "href": null,
          "note": "…",
          "status": "live",
          "live_url": "https://directory.example/…",
          "cited_since_live": false,
          "cited_count": null,
          "checks_since": 1
        }
      ]
    }
  ]
}