The ScanFree MCP server
Connect your own AI to ScanFree. It can start a free scan, wait for it and read you the result; with a paid order it can read every check. There is one address for every app:
https://app.scanfree.dev/api/mcpThe server speaks MCP over Streamable HTTP (POST, JSON answers, no sessions). Sign in with OAuth, or send a key. Test it with: “Use ScanFree: how many free scans do I have left this month?” It calls account and never spends a free scan.
Connect your AI
Apps you add a connector to sign you in with OAuth: no key. Developer tools take the address and either sign in the same way or send a key from your MCP page.
Claude: web, desktop and mobile
- In Claude, open Customize, then Connectors. Click Add, then Add custom connector.
- Name it ScanFree, paste the address, and click Continue.
- For the OAuth client, either choice works: Claude’s published identity (Claude’s recommended choice) or Register automatically.
- Click Add, then Connect, sign in to ScanFree and allow access.
- On the phone app it then shows up by itself. In a Claude Team or Enterprise workspace an Owner adds it, then each member clicks Connect. A free Claude account can add one custom connector.
ChatGPT
Business, Enterprise and Edu workspaces can add custom MCP servers in full; Pro accounts can connect with read and fetch only. OpenAI doesn’t list Plus. Your workspace admin may control who can add one. ChatGPT signs in with OAuth only: it can’t send a key.
- Open chatgpt.com/plugins, click +, then Add custom MCP server. Name it ScanFree.
- Paste the address, choose OAuth, accept the warning and create it.
- Sign in to ScanFree when asked, and allow access.
Gemini app
For personal Google accounts, 18 or over, in the US, in English, with Gemini Apps Activity on. Add it on the web; it then works on the phone too. We haven’t tested it ourselves yet.
- On gemini.google.com open Settings, then Connected apps, then Custom apps, and add one.
- Paste the address, click Next, sign in to ScanFree and allow access.
- Ask with
@ScanFreein front of your question.
Claude Code
claude mcp add --transport http scanfree https://app.scanfree.dev/api/mcp --header "Authorization: Bearer sf_live_YOUR_KEY"Add --scope user before the name to have it in every project. Leave out the header to sign in with OAuth instead.
Cursor
In ~/.cursor/mcp.json (Windows: %USERPROFILE%\.cursor\mcp.json). Leave out headers to sign in with OAuth.
{
"mcpServers": {
"scanfree": {
"url": "https://app.scanfree.dev/api/mcp",
"headers": {
"Authorization": "Bearer sf_live_YOUR_KEY"
}
}
}
}VS Code with GitHub Copilot
Run MCP: Open User Configuration and add the server. With Copilot in an organisation, the “MCP servers in Copilot” policy must be on. Copilot’s own agent can’t put stored secrets into headers, so there leave out headers and sign in with OAuth.
{
"servers": {
"scanfree": {
"type": "http",
"url": "https://app.scanfree.dev/api/mcp",
"headers": {
"Authorization": "Bearer sf_live_YOUR_KEY"
}
}
}
}Windsurf
In Cascade’s MCP settings choose Open MCP config file (~/.config/devin/mcp_config.json, Windows %AppData%\devin\mcp_config.json).
{
"mcpServers": {
"scanfree": {
"serverUrl": "https://app.scanfree.dev/api/mcp",
"headers": {
"Authorization": "Bearer sf_live_YOUR_KEY"
}
}
}
}Gemini CLI
gemini mcp add --transport http -s user --header "Authorization: Bearer sf_live_YOUR_KEY" scanfree https://app.scanfree.dev/api/mcpWithout the header it signs in with OAuth in your browser.
Perplexity
Pro, Max and Enterprise (an Enterprise admin must allow custom connectors). Open Plugins, then Add custom, then Add MCP connector. Give the name and the address; under Advanced choose OAuth and Streamable HTTP. Add it, then click its card to sign in.
Mistral Le Chat
An admin adds it (on a personal account, that’s you). Open Connectors, then Add Connector, then Custom MCP Connector. Give a name without spaces and the address, then Connect: Le Chat finds the sign-in by itself.
Zed and JetBrains
Zed: add the address under context_servers in its settings; without an Authorization header it signs in with OAuth. JetBrains AI Assistant: add the server by its address in the MCP settings with the header below; it doesn’t sign in with OAuth.
Authorization: Bearer sf_live_YOUR_KEYNot possible today
- Meta AI: there’s no way to add a server by its address.
- Microsoft Copilot, the consumer app: no documented way to add one. Copilot Studio is a different product; we haven’t tested it yet.
- Gemini Enterprise: it needs an OAuth client with a client secret, which ScanFree doesn’t issue.
Signing in
| Way | How it works |
|---|---|
| OAuth 2.1 | Your app finds the sign-in from the server’s 401 answer, then signs you in on ScanFree with PKCE (S256). It can identify itself with a Client ID Metadata Document (an https address as its client id) or register itself (dynamic client registration). Public clients only: no client secret. An access token lasts 1 hour; the app renews it for up to 30 days. openid and offline_access are accepted and ignored. |
| A key | Make one on your MCP page and send Authorization: Bearer sf_live_YOUR_KEY. The key is shown once; we keep only a fingerprint. Revoke it there and it stops working at once. |
Scopes
| Scope | What it allows |
|---|---|
scan:read | Read your scans, sites and paid orders. |
scan:write | Start scans, prepare orders and change your own data, such as the pages you published. |
order:write | Stop an order and ask for a refund. Each asks the person to confirm first. (Adding to an order needs only scan:write: it returns a Checkout link for the person to pay.) |
account:write | Change the email choices and start the data export. |
Each tool’s page says which scope it needs. Keys and app sign-ins made before a new scope existed keep the scopes they had.
Limits
| Limit | Value |
|---|---|
| Requests per key, OAuth app or agent | 60 a minute |
| Requests per account, across all its keys and apps | 60 a minute |
| Wrong keys from one network | 20 a minute, then a pause of a minute |
| Free scans | 3 a month, shared with the website and your agents |
| Question suggestions and site facts (suggest_questions, start_scan without questions) | 5 a day |
| "Can AI reach you?" (site_tools reach) | 10 runs in any 24 hours |
| robots.txt checker (site_tools robots) | 30 an hour |
| Longest wait in one call (get_scan wait_seconds) | 25 seconds; call again to keep waiting |
| Download links (get_report) | valid 10 minutes |
| New app registrations from one network | 60 an hour (the same app registering again isn’t counted) |
Over a request limit, the server answers HTTP 429 with Retry-After in seconds. A tool limit answers limited or limit_reached inside the result instead.
How answers look
Every tool answers with one text block and the same data as structured content. The text is the JSON, or the report or Markdown when that’s what was asked for. Every answer has status: ok (or a progress word such as running) when it worked, otherwise a word your AI can act on, with message in plain words. The result is marked as an error for invalid_input, invalid_questions, forbidden and not_found; the others are normal answers that say what to do next.
Errors before a tool runs
| HTTP | error | What it means |
|---|---|---|
| 401 | missing_token | No Authorization header. OAuth apps start their sign-in from this answer. |
| 401 | invalid_token | The key or token is wrong, revoked or expired, or the account is blocked or not confirmed. |
| 403 | revoked | An agent sign-in whose access was taken back. |
| 429 | rate_limited | Too many requests. Wait for Retry-After. |
| 429 | too_many_failures | Too many wrong keys from your network. Wait a minute. |
| 405 | Only POST is served: the server keeps no sessions. |
What stays off MCP
- Signing in and keys. A person makes and revokes keys and allows apps, on the website. An agent can’t give itself access.
- Deleting the account. It can’t be undone, so only the person does it, on the website.
- Paying.
create_orderreturns a checkout link; a person pays on Stripe’s page. An agent can’t pay.
Data rules
- No bulk answer text. Claims carry one short quote; downloads hold who was named and where, never the answers themselves.
- Counts first, with their totals: “named in 3 of 20 answers”, never a bare percentage.
- Review counts and dates only, never review text.
- “Since”, never “because”: a page cited after you published it was cited since, not because.
- Google search figures are never added to AI figures, and live search and training-data answers are kept apart.
- Each tool reads only your own account. An agent reads its owner’s.
ScanFree never charges for AI chat
Your AI does the thinking, on your own AI account. No tool needs ScanFree’s AI: suggest_questions in its facts mode reads your site with no AI at all, and its questions mode, written by our model, is optional and free. The ready-made prompts are filled from your data, and your AI writes the result.
The tools
| Tool | What it does |
|---|---|
start_scan | Start a free scan |
get_scan | Get a scan |
explain_result | Explain a result in plain words |
list_scans | List recent scans |
suggest_questions | Suggest questions, or read the site's facts |
get_dashboard | Paid orders at a glance |
check_status | A check in progress |
get_matrix | Results of one check |
get_pages_to_beat | Pages AI cited, per phrase |
get_brand_brief | Facts about the business |
list_actions | What to do, with hand-offs |
get_check_summary | One thing, and what moved |
get_gap | Did the work close the gap? |
create_order | Prepare a paid order |
get_order | One paid order in full |
get_report | Download a report |
order_setup | Set up a paid order |
phrases | Phrases of an order |
manage_order | Notes, stop, refund, billing |
addons | Add to this order |
published_pages | Pages you published |
claims | What AI says about the business |
programs | Directory, press and blog programs |
sites | Your businesses |
site_insights | Competitors, directories, reviews, site checks |
site_tools | Can AI reach the site? robots.txt |
share_link | Public share link |
account | Free scans left, email choices, export |