Skip to content

sites

Your businesses.

The websites (businesses) on this account. list (scan:read): each with its site_id, address and kind; use the site_id with get_brand_brief, site_insights, site_tools and published_pages. Writes (scan:write): add (url, site_type, city for a local business, name); update (site_id; name, city, site_type, trade, facts: your own facts by key, merged into what is saved, and remove_facts: a list of keys to take off, e.g. ["phone"]; an empty value in facts also removes one); save_about (site_id, entries [{field, value}], field sell, who, where, different, prices or wrong): About your business, in the person's words; set_competitors (site_id, competitors [{name, domain}] to add or [{competitor_id, active}] to switch). Write only what the person told you.

Who can use it

Access
Any account.
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: list.

actionScopeWhat it does
listscan:readThe websites on this account.
addscan:writeA write action: the description above says what it changes.
updatescan:writeA write action: the description above says what it changes.
save_aboutscan:writeA write action: the description above says what it changes.
set_competitorsscan:writeA write action: the description above says what it changes.

Inputs

NameTypeRequiredValues and limits
actionstringNolist, add, update, save_about, set_competitors. Default list
site_idstringNo
urlstringNo0 to 500 characters
site_typestringNolocal_service, local_storefront, local_professional, agency, saas, ecommerce, marketplace, creator, nonprofit, publisher, other
citystringNo0 to 80 characters
namestringNo0 to 120 characters
tradestringNo0 to 60 characters
factsobjectNoKeys: name, description, phone, email, address, services, areas, hours, prices, credentials, profiles
remove_factsarray of stringNoat most 20 items. For update: own facts to remove, by key (e.g. ["phone", "hours"])
entriesarray of objectNoat most 12 items
competitorsarray of objectNoat most 20 items

What it answers

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

FieldMeaning
sitessite_id, name, url, kind and site_url. Use site_id with get_brand_brief, site_insights, site_tools and published_pages.

Errors

statusWhat it means
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": "sites",
    "arguments": {
      "action": "list"
    }
  }
}
The answer (structured content)
{
  "status": "ok",
  "sites": [
    {
      "site_id": "00000000-0000-4000-8000-000000000004",
      "name": "example.com",
      "url": "https://example.com/",
      "kind": "local_service",
      "site_url": "https://app.scanfree.dev/app/sites/00000000-0000-4000-8000-000000000004"
    }
  ]
}