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:readfor reading; each write action's scope is below.- Changes anything
- Its write actions do; see below.
Actions
Pass one in action. Without it: get.
| action | Scope | What it does |
|---|---|---|
get | scan:read | Whether the checklists are open to this order, and each place with the person's status. |
set_item | scan:write | A write action: the description above says what it changes. |
Inputs
| Name | Type | Required | Values and limits |
|---|---|---|---|
action | string | No | get, set_item. Default get |
order_id | string | Yes | An order id from get_dashboard |
program | string | No | directory, press, blog |
item | string | No | 0 to 100 characters. An item key from action get |
status | string | No | todo, submitted, live |
url | string | No | 0 to 500 characters. For status live: the page's address |
What it answers
Every answer has status and, where useful, message in plain words.
| Field | Meaning |
|---|---|
unlocked, read_only, closed, checks, min_checks | Whether 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
| 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 | An action that isn't in the list. |
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": "programs",
"arguments": {
"action": "get",
"order_id": "00000000-0000-4000-8000-000000000002"
}
}
}{
"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
}
]
}
]
}