start_scan
Start a free scan.
Start a free ScanFree scan of one website. Local types (local_service, local_storefront, local_professional) need `city`. Pass 1 to 10 `questions` a customer would ask an AI (no business name); if you omit them you get 12 suggestions and must call again. Needs a verified account; uses one of the monthly free scans (shared with the website).
Who can use it
- Access
- Any verified account. Uses one of the free scans of the month, shared with the website.
- Scope
scan:write- Changes anything
- Yes.
Inputs
| Name | Type | Required | Values and limits |
|---|---|---|---|
url | string | Yes | The business website, for example example.com |
site_type | string | Yes | local_service, local_storefront, local_professional, agency, saas, ecommerce, marketplace, creator, nonprofit, publisher, other |
city | string | No | City and state for local types, e.g. Boise, Idaho |
questions | array of string | No | 1 to 10 items |
What it answers
Every answer has status and, where useful, message in plain words.
| Field | Meaning |
|---|---|
status | running when the scan started; queued when free scans are busy (it runs by itself); needs_questions when you passed no questions. |
scan_id | The scan, for get_scan and explain_result. |
estimated_seconds | About how long it takes. |
report_url | The report page (the person signs in to see it). |
suggestions | With needs_questions: twelve questions to choose from. Call again with up to ten of them in questions. |
position, eta_seconds | With queued: the place in the queue and an estimate. |
message | What to do next, in one sentence. |
Errors
| status | What it means |
|---|---|
invalid_input | The address is refused (not a public website, or a kind of site we don't check), site_type isn't one of the list, too many questions, or city is missing for a local type. |
invalid_questions | Some questions won't make AI list businesses, or aren't allowed (for example they name the business). problems says which, by number. |
verify_email | The account hasn't confirmed its email. link goes to sign-in. |
limit_reached | No free scans left this month. account (action get) says when they reset. |
already_running | A scan of this site is running already; scan_id is that scan. |
daily_limit | Today's free scans are used up for everyone. Try tomorrow. |
limited | Too many scans from this network, or too many suggestion runs today. |
needs_review | This scan waits for a person at ScanFree to look at it first. |
paused | Free scans are paused for now. |
forbidden | The account is blocked, or the credential lacks scan:write. |
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": "start_scan",
"arguments": {
"url": "example.com",
"site_type": "local_service",
"city": "Boise, Idaho",
"questions": [
"Who is a good plumber in Boise?",
"Best emergency plumber near Boise"
]
}
}
}{
"status": "running",
"scan_id": "00000000-0000-4000-8000-000000000001",
"estimated_seconds": 30,
"report_url": "https://app.scanfree.dev/scan/00000000-0000-4000-8000-000000000001",
"message": "Call get_scan with this scan_id (wait_seconds up to 25) until status is complete."
}