Hosted MCP server

squirrelscan runs a hosted Model Context Protocol server in the cloud. Point any MCP client at it and your agent gets tools for running cloud audits, reading and comparing reports, working the per-website issue tracker, catching up on notifications, sending product feedback, and browsing the 300+ rule catalog. Nothing to install, nothing to keep running:

https://mcp.squirrelscan.com/mcp

The transport is streamable HTTP. Authentication is OAuth 2.1 (browser login) or a squirrelscan API key as a bearer header, whichever suits the environment.

Quick connect

The fastest path is Claude Code:

claude mcp add --transport http squirrelscan https://mcp.squirrelscan.com/mcp

Then, inside a session, run /mcp, select squirrelscan, and choose Authenticate. Your browser opens, you log in to squirrelscan, pick the organization the agent should act for, and approve. That’s it: the tools are live.

Every other client is a couple of lines of config. See MCP client setup for exact snippets for Cursor, Codex CLI, VS Code, Windsurf, and Gemini CLI.

Authentication

There are two ways in. Pick one per config entry.

OAuth (browser login)

Add the server with no auth headers and the client handles everything: it discovers the authorization server at /.well-known/oauth-authorization-server, registers itself dynamically (DCR and CIMD are both supported), and runs the PKCE browser flow. You log in, choose an organization, and approve on the consent screen.

Behind the scenes the flow mints a 30-day squirrelscan API key scoped to the organization you approved, plus a rotating refresh token. A client that supports refresh renews the key on its own, so you are not prompted at 30 days. The refresh token lapses 90 days after its last use; after that the client prompts you to sign in again.

Best for: a human at an editor. No key to copy, no secret in any config file.

API key (bearer header)

Set a standard bearer header on the server entry:

Authorization: Bearer sq_xxxxxxxxxxxx

Get a key from the dashboard at app.squirrelscan.com/settings/api-keys, or without leaving the terminal:

squirrel keys create --shell

--shell offers to append export SQUIRRELSCAN_API_KEY=sq_... to your shell rc, and SQUIRRELSCAN_API_KEY is the conventional env var: most clients can interpolate it into the header so the key never lands in a config file. See squirrel keys and Authentication.

Key scopes apply to tools exactly like they do to the REST API: run_audit, add_website, delete_website, delete_websites, and comment_on_issue need audits:write; audit, report, and issue reads (compare_audits included) need audits:read; get_credit_balance and list_credit_transactions need credits:read; list_notifications needs org:read. A key missing a scope gets a structured FORBIDDEN error naming the missing scope. whoami works with any key but only includes the balance when the key has credits:read.

Best for: CI, headless machines, containers, and configs you commit and share.

Without credentials you can read the public catalog and the agent skills:

• initialize, server/discover, tools/list, resources/list, prompts/list
• skills/list and skills/get
• resources/read for skill:// URIs only
• the client notifications notifications/initialized, notifications/cancelled, notifications/progress and notifications/roots/list_changed

Everything else needs credentials: every tool call, every other resource, and every other method. Unauthenticated calls get a 401 with a WWW-Authenticate challenge that points OAuth-capable clients at the login flow. Anonymous requests share a limit of 30 per minute per IP, an anonymous batch holds at most 10 messages, and any request body over 1 MiB is refused with a 413.

Tools

All tools require authentication. Write tools are marked; everything else only reads.

A few tools deserve a closer look:

• Unknown arguments are reported, not applied. An argument a tool does not accept is dropped, and the successful result lists it in ignored_args, so you can tell a setting that took effect from one that did not.

• run_audit has a confirm rail. When the estimate is above the auto-run threshold (50 credits by default), the first call returns the estimate instead of starting; the agent shows it to you and calls again with confirm: true. An estimate at or under the threshold starts immediately, and an agent that already has your approval can pass confirm: true on the first call. A max_credits argument acts as a hard spend guard: the audit refuses to start if the estimate exceeds it.

• run_audit takes a level. Pass quick (25 pages from the start page and its sitemaps, no cloud checks, with external link checks), surface (100 pages, one per URL pattern, with the cloud checks and external link checks) or full (500 pages, every page it can reach). Without one (or the deprecated coverage below), the website’s own level applies, and a new website starts on surface. max_pages sizes a single run on top of the level. Every level is billed: 50 credits plus 2 per audited page, plus 1 per external link the cloud verifies. external_links sets this run’s external link checks (true at any level, false to skip them; default: the website’s setting), and internal_links: false skips the free internal link check for this run. On the Free plan a full request samples the way surface does instead, one page per URL pattern first, and the response says so in level_notice. Both the estimate and the started run report the level they use in level and audit_level. The older coverage argument (fast, surface, deep, full) still works for now with the meaning it always had, but it is deprecated, and passing it together with level is an error.

• delete_website and delete_websites have the same confirm rail. The first call previews what happens without deleting anything (for one site, the domain and how many audits and open issues stay attached to the old id; for a batch, the domain and kind behind every id); the agent confirms with you and calls again with confirm: true. Deletion is soft: nothing is destroyed, and re-adding the domain later registers a fresh website with a new id.

• Recurring audits switch on by themselves, and the schedule says so. After a website’s first successful cloud audit, squirrelscan re-audits it on a schedule, and every run spends credits. run_audit, get_audit_status and both settings tools carry a schedule field: pending_first_audit: true means the schedule is about to switch on, and estimated_cost gives the most it can spend per run, per week and per month. update_website_settings with schedule: "off" turns it off at once.

• update_website_settings has a confirm rail for spend. Turning recurring audits on, changing their cadence, or a change that raises the most one audit can cost (a bigger page cap, external link checks) returns confirmation_required with the estimate and changes nothing; the agent shows it to you and calls again with confirm: true. Turning the schedule off, and changes that cost nothing more (crawl scope, patterns, depth, internal_links, a cheaper level), apply straight away. A cadence your plan does not run is set to one it does, and a page cap above your plan’s ceiling is stored and held to the ceiling when audits run; the result says so in both cases.

• Your role sets what an OAuth sign-in can do. The approval screen offers only the scopes your role in the chosen organization holds: a viewer’s sign-in reads but cannot run audits or change websites, and a billing member’s holds credits:read and org:read only. A tool outside them returns FORBIDDEN with your role and the missing_scope. If your role later changes to one with less access, the sign-in ends and the client asks you to sign in again.

• create_api_key is scope-gated. It needs credentials carrying the reserved keys:write scope. OAuth login grants it to organization owners and admins (you consented on the approval screen); an editor, viewer or billing member’s sign-in works without it. The tool also checks your current role, the same rule as creating a key in the dashboard, so a member who is demoted or removed can no longer mint keys. Plain API keys never carry the scope, and keys minted by this tool can’t mint further keys. No escalation loops.

Issue provenance

After a smart audit, list_issues and get_issue return two extra fields on each issue:

• provenance: fresh means this audit re-checked the issue. carried means the issue survives only because its pages were not re-crawled this audit, so confirm it with a re-crawl before you act on it. unrendered means the issue’s page has never been rendered in any scan, so there is no earlier observation.
• last_seen_at: an ISO 8601 UTC timestamp of the crawl that last observed the issue. It is the evidence date for a carried issue, and it is absent for fresh and unrendered issues.

Both fields are omitted when the issue has no recorded provenance, for example on a website whose audits are not smart audits.

get_report returns seedRedirect only when the audited URL redirected off-site and the crawler did not follow it. Its finalUrl is null, with a note saying the redirect target was not a valid URL and is withheld, when the target was not a valid http(s) URL. The audit then graded the audited address, not the redirect target.

Tailor each website with rules

squirrelscan results are meant to be tailored to each site through rules. Not every rule applies to every site: a hobby site with no privacy, about or contact pages does not need those findings re-reported on every audit. Rules that do not apply are disabled, so the score reflects what matters for that site.

disable_rules on get_website_settings and update_website_settings is the per-website list:

{ "website_id": "...", "disable_rules": ["eeat/*", "legal/privacy-policy"] }

• What it takes. Exact rule ids (eeat/about-page) and category globs (eeat/*), the same patterns as disable in squirrel.toml. It is stored per website and applied to every cloud audit of it, whether started by run_audit, a schedule or the dashboard.
• It replaces the stored list. Send the whole list you want; an empty list clears it and every rule runs again. get_website_settings returns the list and disabled_rule_count, the number of rules it matches.
• What it refuses. * (it would switch every rule off), blank entries, entries that match no rule and lists over 500 entries. Entries already stored are kept when you send the list back. Take ids from list_rules or from get_report with format: "rule_ids", not from memory.
• Local runs read squirrel.toml, cloud runs read this list. A cloud audit cannot see your repository, so run_audit does not read a squirrel.toml. The CLI and the local MCP server do. To get the same rule set in both, set the same ids in both places. [[ignore]] waivers and enable are squirrel.toml settings and do not apply to cloud audits.
• The report says what was switched off. get_report carries rulesDisabledByConfig in the summary and rule_ids formats, and a line such as “3 rules disabled by config” at the top of the llm and markdown formats, so two scores are compared knowing they ran the same rules. It appears for a cloud run that recorded its rule selection, 0 rules included.

To build a list, run an audit, call get_report with format: "rule_ids" for the failing rule ids (each with its name, category, status and occurrences), pick the ones that do not apply to the site, and send them to update_website_settings. Run the audit again and check the rules are gone from the report.

The entity tools run one loop

The five entity tools exist to be used in order. list_entities with problem: "no-id" returns the entities a site declares on several pages with nothing tying them together, you fix the site’s JSON-LD, run_audit re-audits, and compare_entities confirms the keys you fixed come back under gainedId. That last step is the one worth insisting on: an entity that gains an @id changes key, so a naive before-and-after comparison reports the fix as one removal plus one addition and it reads as damage.

The entity map over MCP covers the loop in full, including what the coverage field on each change is claiming.

Which number to compare

Three tools report counts that look comparable and are not. The published report is the source of truth, and everything else is derived from it:

Compare runs on health_score. It is the one number rescored consistently across the whole site, so a move between two runs means the site moved.

Do not compare issues_found with the open count from list_issues. The tracker folds a rule failing on 600 pages into one issue and keeps an issue open until an audit re-checks it, so its count is legitimately much smaller and moves on its own schedule.

Credits

Cloud audits are pay-as-you-go: credits are spent while the audit runs, and nothing is charged up front. From the agent’s side a paid audit looks like this:

1. Agent calls run_audit with the URL. The response comes back with status: "confirmation_required", an upper-bound estimate (estimate.cap), and your current balance.
2. The agent shows you the estimate and asks. Actual spend is usually below the cap.
3. You approve; the agent calls run_audit again with confirm: true. The audit starts and returns a run_id.
4. The agent polls get_audit_status every 15-30 seconds, then pulls the results with get_report.

An audit costs 50 credits base plus 2 per audited page, however the page was fetched, plus 1 per distinct external link the cloud verifies when external link checking is on. If your balance can’t cover the page limit, the audit runs with a lower limit and the response’s notice says so; it is refused only when even one page is unaffordable. Check your balance with get_credit_balance, audit where the credits went with list_credit_transactions (or a single audit’s per-feature breakdown via get_report’s cost field), or top up at app.squirrelscan.com/billing.

Sample prompts

Copy-paste starters. Prompts marked spends credits run a cloud audit; prompts marked write change state in your org.

• “Audit https://example.com and fix the top 3 issues in this repo.” (spends credits, write)
• “Check my site’s open audit issues and comment on the ones this PR fixes.” (write)
• “Compare the last two audits of example.com and tell me what regressed.”
• “Create an API key for CI and add it to my GitHub Actions secrets.” (write, needs OAuth login as an organization owner or admin for keys:write)
• “What would a full audit of example.com cost, and how many credits do we have left?”
• “Run a full audit of staging.example.com, but stop if it would cost more than 200 credits.” (spends credits, write)
• “List our websites and summarize the health of each one.”
• “What does the rule crawl/canonical-chain check, and how do I fix it on a Next.js site?”

Local MCP server

The CLI ships a local stdio MCP server too:

squirrel mcp

It runs squirrelscan’s deterministic audit engine on your machine: it works offline and needs no account. Reach for it when you are auditing localhost or a private network, or have no network at all. Signed in, its audit_website is a billed cloud audit like squirrel audit, with the same confirmation step as the hosted run_audit. The hosted server is the better default for everything cloud-side: shared org state, the issue tracker, browser rendering, and zero local install.

It also serves the squirrelscan agent skills over MCP (the Skills extension), so a client that supports it gets the matching skills from the server itself: see Skills.

Full setup and tool reference: squirrel mcp.

Related

• MCP client setup - exact config for Claude Code, Cursor, Codex CLI, VS Code, Windsurf, and Gemini CLI
• Authentication - API keys, scopes, and SQUIRRELSCAN_API_KEY
• squirrel keys - mint and manage keys from the terminal
• squirrel mcp - the local stdio server
• Cloud credits - how audits are metered