Run accessibility, contrast, and design token audits and manage QA issues directly from your AI coding editor.
Also known as OverlayQA/mcp, mcp, @overlayqa/mcp
- Stars
- 0
- Tools
- 45
- Downloads, 30 days
- —
- Latest version
- 0.8.0
- Last commit
- Nov 13, 2026
- License
- MIT
What is OverlayQA MCP?
OverlayQA runs accessibility, contrast, and design token audits and manage QA issues directly from your AI coding editor. It exposes 45 tools, such as create_review_issues, list_scheduled_reviews, create_scheduled_review.
Summary generated from the project's README
About OverlayQA MCP server
OverlayQA provides developers with a way to perform accessibility, color-contrast, and design token audits directly through an AI coding agent. By connecting this MCP server to editors like Cursor, Windsurf, or Claude Code, users can scan live URLs for WCAG violations and design inconsistencies without leaving their development environment. The server uses axe-core for accessibility checks and can evaluate design system health by auditing font sizes, spacing, and color usage on a live page.
Beyond scanning, the tool allows for full issue management. You can create projects, file new QA issues, assign tasks to teammates, and manage labels or comments. It supports advanced workflows like visual comparisons against Figma frames or saved images. To use the server, you must connect an OverlayQA account via a browser window, which creates a 30-day connection. While basic scanning is available for free, creating issues and projects requires a trial or a paid plan.
What you can do with it
- 1Automated accessibility auditingAsk your AI agent to scan a specific URL for WCAG compliance and report any violations.
- 2Design token health checksRun an audit on a live page to find inconsistent font sizes, spacing, or border radii.
- 3Direct issue creationAutomatically generate QA tickets for critical accessibility failures found during a scan.
- 4Visual design verificationCompare a live webpage against a saved design or Figma frame to find visual discrepancies.
Written from the project's README. Every use case is checked against a quote from it.
How to install OverlayQA MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall OverlayQA MCP in Claude Code
$ claude mcp add mcp -- npx -y @overlayqa/mcpInstall OverlayQA MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"mcp": {
"command": "npx",
"args": [
"-y",
"@overlayqa/mcp"
]
}
}
}Install OverlayQA MCP in VS Code
.vscode/mcp.json
{
"servers": {
"mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@overlayqa/mcp"
]
}
}
}Install OverlayQA MCP in VS Code CLI
$ code --add-mcp '{"name":"mcp","type":"stdio","command":"npx","args":["-y","@overlayqa/mcp"]}'Install OverlayQA MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"mcp": {
"command": "npx",
"args": [
"-y",
"@overlayqa/mcp"
]
}
}
}Install OverlayQA MCP in Codex
$ codex mcp add mcp -- npx -y @overlayqa/mcpInstall OverlayQA MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.mcp] command = "npx" args = ["-y", "@overlayqa/mcp"]
Install OverlayQA MCP in Gemini CLI
$ gemini mcp add -s user mcp npx -- -y @overlayqa/mcpInstall OverlayQA MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"mcp": {
"command": "npx",
"args": [
"-y",
"@overlayqa/mcp"
]
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for @overlayqa/mcp 0.8.0 in an isolated container with no network and no keys. It answered and listed 45 tools.
OverlayQA MCP tools 45
Read from the server with tools/listcreate_review_issuesActionFile selected findings from your completed MCP Auto Review or visual comparison in its original project. Preserves saved images, page, captured context and fix guidance without scanning again. Repeating the same job and indexes recovers existing issues; inspect every finding outcome for partial completion. Old jobs without retained page provenance cannot be filed.
list_scheduled_reviewsRead-onlyList readable scheduled reviews in this workspace, including cadence, pause state, next run and latest saved result summary. Does not scan or send email.
create_scheduled_reviewActionCreate a recurring public-page review with the same plan limits and cadence as the dashboard. Enables future scans and review emails. A lost response can be recovered by listing schedules; the same project, page and scan type cannot have duplicate schedules.
update_scheduled_reviewActionPause, resume, or change a scheduled review cadence. Supply exactly one of action or cadence. Resuming enables future scans and review emails; plan and project permissions still apply. Pausing keeps previous results.
delete_scheduled_reviewActionDelete a scheduled review and stop its future scans and emails. Does not delete filed project issues.
run_scheduled_reviewActionRun an active scheduled review now using its existing settings and the dashboard run-now path. Uses scan resources; Run now does not send email. Request IDs and run results are retained for 24 hours. Reuse requestId after a lost response; poll the saved run with the same scheduleId and requestId. Does not resume paused schedules.
get_scheduled_review_resultRead-onlyRead the latest retained scheduled-review findings and evidence without rescanning, or poll a specific run by requestId. An empty result before the first successful run is not a clean scan. No longer detected, ignored and already filed are not proof that an issue was fixed.
list_export_connectionsRead-onlyList your connected issue trackers and reconnect requirements without exposing credentials. A connection does not prove export delivery or working two-way sync. Connect or reconnect in OverlayQA first.
list_export_destinationsRead-onlyDiscover and read destination choices for a connected tracker. Omit collection to learn its available collections and required parameters. Read choices before exporting; use schema collections for required destination fields. Does not create tasks or connect accounts.
export_issuesActionExport existing issues with their captured evidence and discussion to an explicitly chosen connected tracker destination. Uses the same product export and retry handlers. Inspect every result: pending or partial attachment delivery is not success. Read the saved export status after uncertain outcomes before retrying.
get_issue_export_statusRead-onlyRead persisted export destinations, attachment delivery and the latest recorded sync success/error for an issue. Does not contact trackers or force a sync. Missing or stale sync evidence is not proof of a current round trip; unsupported fields are reported.
scan_accessibilityRun an accessibility audit on a URL. Returns WCAG violations with severity, descriptions, and an overall score. Scans one page per call. Free plans include 3 scans per day; Pro is unlimited.
Show all 45 toolsShow fewer tools
scan_contrastRun a color contrast audit on a URL. Returns elements failing WCAG contrast ratios with severity and details. Scans one page per call. Free plans include 3 scans per day; Pro is unlimited.
scan_and_create_issuesRun an accessibility scan on a URL and automatically create issues in the given project for each violation at or above the minimum severity. Returns scan summary + issue IDs created. Scans one page per call. Free plans include 3 scans per day; Pro is unlimited.
compare_visualActionStart AI visual comparison of a public page against a Figma frame, saved design or uploaded image. Supply reference, or both figmaFileKey and figmaNodeId. Captures at the design’s authored width. Optional measureSpacing adds supported element measurements and tolerances. Uses your scan allowance and returns a persistent job ID; results include individual differences and screenshot evidence. Does not create issues or provide a deterministic pixel-difference build gate.
run_auto_reviewActionStart Auto Review of a public page in a readable project. Uses your scan allowance and the project’s review settings, ignored findings and already-filed issues. Returns a persistent job ID; results include findings, scores, AI status and screenshot evidence. Does not create issues. Login-required pages need the browser extension.
get_review_resultRead-onlyRead a previously started review without starting or charging for another run. Returns running progress, failed details, or the complete Auto Review or visual-comparison findings and evidence. Results are retained for 24 hours by default and require access to the original project and workspace.
audit_tokensAudit a live URL's design-system token usage. Returns a 0-100 token-health score plus findings (inconsistent font sizes, text colors, spacing, font families, border radii) with severity and evidence. Audits the live page only; the figmaFileKey argument is accepted but Figma comparison is not yet available via MCP.
create_issueCreate an issue in an OverlayQA project. Title is optional; severity, type, and description default to medium / general / empty. Assignee defaults to you; pass null for Unassigned. This does not capture a screenshot or scan a page.
list_issuesList project issues with tags, description, ownership and ignored state. notDetectedAt records when a scan stopped detecting the issue; lastDetectedAt records a detection. Neither proves a fix. Use notDetected to filter the flag. Filter by status, severity, type, tags, assignee, creator, page (pageUrl), or active/finished/ignored state, and use createdAfter to ask only for issues newer than the last one seen. Each issue carries source (client means a reviewer filed it on a share link), commentCount, lastCommentAt and lastCommentBy (reviewer or team): an issue still needs a reply when source is client and commentCount is 0, or lastCommentBy is reviewer. Returns page, pageSize, total and hasMore; continue to the next page while hasMore is true. Use get_issue for full capture evidence and the discussion.
update_issueUpdate issue status, title, description, severity, type, assignee, or ignored state. Only supplied fields change. Use null to unassign and ignored=false to restore. Accepts UUID or display id. Status verified does not run a verification scan. Use verify_issue to check a deployed fix, then inspect its evidence before deciding whether to change status.
get_issueRead a complete issue by UUID or display id: description, tags, assignee, ignored state, screenshot URLs, captured element/CSS and viewport evidence, its comments (the same discussion list_comments returns), aiAnalysis (the latest saved analysis with full findings and suggestions, or null), and latestVerification (the newest saved check, or null). Reading saved analysis does not run AI. Read get_issue_verifications for history; issue status and notDetectedAt alone do not prove a fix.
list_project_membersList workspace teammates for a readable project. Use their userId for assignment and comment mentions. Returns the signed-in userId too.
move_issueMove an issue into another project in the same workspace, preserving its identity, comments and evidence. Requires write access to both projects. Returns its new display id; use that id afterward.
verify_issueCheck whether a resolved, verified, or closed issue is fixed on its public page. Uses the existing capture and verification engine and your verification allowance. Requires an original screenshot and a verifiable issue type. Returns the saved verdict, explanation, confidence, and after-screenshot evidence; passed_with_caveat, failed, inconclusive, and error are not an unconditional pass. Does not change issue status. Login-required and localhost pages need the browser extension. Reuse requestId only when retrying the same check after a lost response. Availability follows the verification rollout.
get_issue_verificationsRead the latest 50 saved verification results for an issue, newest first. Includes verdicts, explanations, confidence, after-screenshot URLs, capture context, and timestamps. This does not run a new check. An issue status of verified or a no-longer-detected flag alone is not a verification pass.
list_commentsRead an issue discussion, including comment authors, audience, mentions and attachment metadata. Returns native and linked comments; edit/delete accept native comment IDs only.
create_commentPost a comment with explicit audience (Team only or Team and clients), optional teammate mentions and PNG/JPG/PDF or MP4/WebM recording files, at most 10 MiB combined. Attaches an existing recording; does not record a browser tab. Reuse requestId when retrying the same submission after a lost response.
update_commentEdit your own native comment text and mention list. Empty text is allowed only when an attached file remains. Audience and attached files stay unchanged. Supply the complete mention list, including retained mentions.
delete_commentDelete your own native comment and its attached files. This also removes it from client-visible discussions when its audience was public.
get_comment_attachmentRead a native comment attachment using the issue’s read permissions. Returns up to 2 MiB as base64. Start at offset 0; decode each part separately and concatenate the bytes, following nextOffset until null. totalBytes and sha256 describe the whole file. Attachment IDs come from list_comments.
list_labelsList the workspace tag library and your write/manage permissions. Optionally include an issue UUID to see its assigned tags.
create_labelCreate a reusable workspace tag. Editors can create tags; retries and case-insensitive duplicate names return the existing tag. Apply it with set_issue_label.
rename_labelRename a tag throughout its workspace. Requires workspace owner or admin permission. Assignments are preserved; existing shared reports keep their original names.
delete_labelDelete a tag from the workspace and all its issues. Requires workspace owner or admin permission. Issues themselves are retained.
set_issue_labelApply (applied=true) or remove (applied=false) one workspace tag on an issue. Other tags and issue text remain unchanged. Safe to retry.
list_projectsList all OverlayQA projects in the authenticated user's team.
create_projectCreate a new OverlayQA project. Returns the project id, name, slug, displayPrefix, and url.
list_client_reviewsRead-onlyList a project’s client review links, share URLs, titles, capture status, expiry, visits, comments, doneReviewers and clients. Each client includes invitedAt, inviteFailed, invitePending, inviteUnconfirmed, lastReminderAt, done, commented and unsubscribed. Done reviewing means that reviewer finished giving feedback, not that issues are fixed or that every client is done. invitationsEnabled reports the delivery switch; reminders follow the existing automatic schedule.
create_client_reviewActionCreate a public client review link for a website in a writable project, optionally with a title, client emails, welcome note and private guest comments. Snapshot mode starts asynchronous capture; read list_client_reviews for readiness. New client emails may receive an invitation and automatic day 3/7/10 reminders. Requires explicit intent to share and, when emails are supplied, invite those people. If invitationsEnabled is false, addresses are saved but not sent and may be invited when delivery is enabled. Inspect invites for per-address sent/skipped/pending results. Pending means the invitation is queued; do not send a duplicate while the initial saved page or delivery confirmation is pending. After a lost response, list links before creating again to avoid duplicates.
update_client_reviewActionChange a client review link’s expiry or responsive previews, or revoke/restore access. Supply only fields to change. Revoked or expired links stop scheduled reminders. This does not mark a reviewer done or change issue status.
set_client_review_recipientsActionReplace a client review link’s COMPLETE client email list. Requires explicit intent to invite or remove these people. New addresses may receive an invitation and automatic day 3/7/10 reminders; retained addresses keep their history and are not invited again. Removed addresses stop reminders; an empty list removes all recipients but leaves the public link working. If invitationsEnabled is false, addresses are saved for later delivery. Read clients and invites for actual per-address state. Reminders stop after that address comments, marks done, unsubscribes, or the link expires/is revoked.
list_client_review_versionsRead-onlyRead saved versions and capture attempts for a client review you can access, including exact-version links, feedback counts and completed reviewers. Does not capture a page or mark anyone done.
get_client_review_versionRead-onlyRead one saved client review version with its original snapshot and version identity. Version IDs must belong to this review. Reading history never fetches today’s website.
create_client_review_versionActionCapture and publish a new saved page beneath an existing client review link in a writable project. Supply the current baseVersionId and reuse requestId after a lost response. Returns a capture attempt; read history until ready or failed. Does not create invitations, restart reminders, copy feedback, resolve issues, or mark reviewers done. Finishing an initial saved page can fulfil invitations already requested for that link. Requires an explicit request to publish a new version.
Configuration
MCP_PARITY_API
Automated checks
Ran Nov 12, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSPass
- Destructive tools are labelledNot checked
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesPass
README
View on GitHubOverlayQA MCP
OverlayQA MCP is a Model Context Protocol server that gives your AI coding agent accessibility and design-QA superpowers. Ask Claude Code, Cursor, or Windsurf to audit any URL for WCAG and color-contrast issues, then read, assign, discuss, label and resolve issues in your OverlayQA projects without leaving your editor.
You: Scan staging.acme.com for accessibility issues, then open issues for the criticals.
Agent: scan_accessibility → 7 violations (2 critical, 3 high), score 71/100.
scan_and_create_issues → created 2 issues in "Acme Web":
- Buttons missing accessible names (WCAG 4.1.2): critical
- Insufficient text contrast on .cta (WCAG 1.4.3): high
You: List the open criticals.
Agent: list_issues(status=open, severity=critical) → 2 issues.
Install
One click:
Or add it to your editor's MCP config manually:
Claude Code (.mcp.json in your project root) / Cursor (~/.cursor/mcp.json) / Windsurf (~/.codeium/windsurf/mcp_config.json):
{
"mcpServers": {
"overlayqa": { "command": "npx", "args": ["@overlayqa/mcp@latest"] }
}
}
Any MCP-compatible client works the same way. On first run a browser tab opens to connect your OverlayQA account (free, no card): pick the workspace, allow access, and the connection lasts 30 days. Credentials cache at ~/.overlayqa/auth.json; the access token is short-lived and refreshes in the background. Disconnect an editor at any time from Connected AI apps in the dashboard (app.overlayqa.com/mcp/connect).
Tools
Tools your agent can call. Each is written so the model picks the right one from natural language.
Audit
| Tool | What it does |
|---|---|
scan_accessibility |
Run a WCAG audit (axe-core) on any URL. Returns violations with severity, WCAG success criteria, and an overall score. |
scan_contrast |
Check color-contrast ratios across a page. Returns the failing foreground/background element pairs. |
audit_tokens |
Audit a live URL's design-system tokens. Returns a 0-100 token-health score and findings (inconsistent font sizes, text colors, spacing, font families, border radii) with severity. Audits the live page only. |
File and manage issues
| Tool | What it does |
|---|---|
scan_and_create_issues |
Scan a URL and auto-create an issue for every violation above a severity threshold. |
create_issue |
File a QA issue with title, severity, type, description and optional assignee. |
list_issues |
Page through issues filtered by status, severity, type, labels, assignee, creator, page, creation time, or active/finished/ignored state. Each issue says who filed it and whether it still needs a reply. |
update_issue |
Edit supplied issue fields, assignment, ignored state or status. Takes a UUID or display id such as OQ-12. |
create_project |
Create a project for a site URL. |
list_projects |
List all projects on your team. |
list_labels |
Read the workspace label library, assigned labels, and your permissions. |
create_label |
Create a reusable workspace label. |
set_issue_label |
Apply or remove one label without changing issue text or other labels. |
rename_label |
Rename a workspace label (owner/admin). |
delete_label |
Delete a workspace label and its assignments; keep the issues (owner/admin). |
AI review workflows
| Tool | What it does |
|---|---|
run_auto_review |
Start Auto Review using project settings, ignored findings and already-filed issues. |
compare_visual |
Start visual comparison against a Figma frame, saved design or uploaded image, with optional measured spacing. |
get_review_result |
Retrieve progress, findings and screenshot evidence from a saved review. |
Both start tools require projectId, a public url, and a new UUID requestId. They return a jobId immediately. Read it with get_review_result until complete or failed. Reuse the same request ID and inputs after a lost response; do not start another review just to read its result. Reviews use your scan allowance and do not automatically file issues. Visual comparison captures at the design’s authored width and returns AI findings, not a deterministic pixel-difference CI verdict.
What the server records
Every tool also accepts an optional context argument: one sentence on why the agent is calling it. OverlayQA records that sentence, the tool name, your account, project and issue ids, counts and scores, the URL a scan runs on, and your editor's name and version (from the MCP handshake) as product analytics. The sentence is capped and stripped of email addresses and credential-like strings before it is stored. Nothing else travels: not your conversation, not your code, not the tool's replies. Full detail: overlayqa.com/privacy.
Example prompts
- "Scan example.com for accessibility issues."
- "Check the contrast on our pricing page and tell me what's failing."
- "Scan staging.acme.com and create issues for anything critical or high."
- "Create a high-severity accessibility issue: the login button has no focus ring."
- "List the open critical issues in the Acme Web project."
- "Create a project for shop.acme.com, then scan it."
Pricing
| Scans | Create issues & projects | |
|---|---|---|
| Free | 3 / day, forever | no |
| 14-day trial | 30 / day | yes |
| Paid | 10-30 / day by plan, unlimited on Pro | yes, with export to Linear / Jira / Asana / Notion |
FAQ
Which editors does it work with? Claude Code, Cursor, Windsurf, and any MCP-compatible client (it speaks standard stdio MCP).
Is it free? Yes to start: 3 accessibility/contrast scans per day with no card. A 14-day trial raises that to 30 scans per day and unlocks issue and project creation. After that, creating issues and projects needs a paid plan (Pro has unlimited scans).
What does it actually scan? Any public URL. Accessibility uses axe-core mapped to WCAG success criteria; contrast checks foreground/background ratios and returns the failing element pairs.
Do I need an account? Yes, a free OverlayQA account. On first run a browser tab opens to connect it; the connection lasts 30 days and can be disconnected from the dashboard at any time.
Does it work with the OverlayQA Chrome extension? Yes. The MCP server and the extension share the same projects and issues, so anything you file from your editor shows up in the extension and the dashboard, and vice versa.
Prefer clicking to typing? Meet the extension
The MCP server is one way into OverlayQA. The Chrome extension is the other: click any element on a live page and it captures a screenshot plus the CSS, DOM, and metadata into a dev-ready issue in seconds, and runs AI accessibility and design-system audits right on the page. Same projects, same issues, shared with this server.
Links
- Website: overlayqa.com
- Chrome extension: Chrome Web Store
- Free accessibility checker (no account): overlayqa.com/accessibility-checker
- Free color-contrast checker (no account): overlayqa.com/color-contrast-checker
- Pricing: overlayqa.com/pricing
- Model Context Protocol: modelcontextprotocol.io
License
MIT
Custom issue labels
Use list_labels with a project UUID to see that workspace's labels and your permissions. create_label creates a reusable label; set_issue_label applies or removes it from one issue without changing its other labels or text. Workspace owners and admins can use rename_label and delete_label; deletion removes the label's assignments, not its issues. list_issues accepts labelIds (match any), including unlabeled. Shared reports preserve the names present when shared.
Local verification can set OVERLAYQA_API_BASE and an isolated OVERLAYQA_AUTH_FILE; neither changes the default production endpoint or normal saved login.
Issue management in 0.3.0
Requires the matching issue-parity API deployment. Existing scans and status updates remain compatible with 0.2.0.
| Tool | What it does |
|---|---|
get_issue |
Read description, ownership, labels, ignored state, screenshots, captured element/CSS, viewport evidence, and the issue's comments. |
list_issues |
Filter by one or more statuses, severities or types; labels; assignee (me, unassigned, or user ID); creator; and active/finished/ignored state. Follow hasMore with the next page. |
list_project_members |
Find teammate user IDs for assignment and mentions in a readable project's workspace. |
create_issue |
Choose an assignee, use null for Unassigned, or omit to assign to yourself. Default type is General. |
update_issue |
Change any supplied title, description, severity, type, status, assignee or ignored flag. Omitted fields remain unchanged. Ignoring never resolves an issue. Setting verified records a status; it does not run a scan. |
move_issue |
Move by stable issue UUID into another writable project in the same workspace; retain comments and evidence. Read the returned display ID afterward. |
list_comments |
Read the discussion, audience, mentions and attachment metadata. |
create_comment |
Post with explicit internal (Team only) or public (Team and clients) audience, mentions, and optional PNG/JPG/PDF files. |
update_comment / delete_comment |
Edit or delete your own native comments. Edits preserve audience and files. |
get_comment_attachment |
Read a native comment file as filename and base64 bytes under the issue's access rules. |
For mentions, use @[userId] in the text and include the same ID in mentionedUserIds. Comment creation requires a UUID requestId: reuse it when retrying that same submission after a lost response, so a retry does not post twice. Attachments are base64 bytes with filename and MIME type, up to ten PNG/JPG/PDF files and 10 MiB total per comment.
list_issues defaults to all states for compatibility. Use state: "active" for open/in-progress issues that are not ignored. finished includes resolved/verified/closed issues that are not ignored; ignored selects the independent ignore flag. All supplied filters intersect. Pages start at 1 and contain up to 100 issues; an empty filtered page is not a complete-project result unless hasMore is false.
To poll for new feedback, pass createdAfter with the createdAt of the newest issue you have already seen (an ISO-8601 time with a zone, such as 2026-10-05T22:00:00Z); only issues created after it come back. pageUrl narrows the list to one page and ignores the query string. Each listed issue carries source (client means a reviewer filed it on a share link), commentCount, lastCommentAt and lastCommentBy (reviewer or team), so an issue still needs a reply when source is client and commentCount is 0, or lastCommentBy is reviewer. If the server has not been updated for a filter yet, the tool answers FILTER_NOT_SUPPORTED instead of an unfiltered list.
The label tools listed above were included in 0.3.0. The later review workflows, client review tools and scheduled reviews are described below and require their matching server updates. Saved-design discovery is not included.
Verify before release
Run npm test and npm run build. The live journey drives the built client over the real stdio protocol against a local API or production using designated fixture accounts; it creates and removes its own projects and produces JSON and HTML evidence.
MCP_PARITY_API=http://127.0.0.1:3241 MCP_SERVER_ENV=/path/to/server/.env npm run test:issues-live
MCP_PARITY_API=https://api.overlayqa.com npm run test:issues-live
Release order: deploy and verify the server endpoints, then publish npm 0.3.0 and update the MCP registry. A local build or version bump is not a publication.
Verify a deployed fix
verify_issue({ issueId, requestId }) runs the same fix-verification engine as the dashboard on the issue’s saved public URL. The issue must be resolved, verified, or closed, have original screenshot evidence, and have a verifiable type (General and Improvement cannot be checked). Use a new UUID for each check; reuse that UUID only when retrying the same request after a lost response. Verification uses the workspace’s existing permissions and verification allowance and follows the server rollout setting.
The result contains a saved check ID, verdict, explanation, confidence, after-screenshot URL, capture context, and timestamps. A check can pass, pass with a caveat, fail, be inconclusive, or report an error. It never updates issue status. Inspect the evidence before deciding whether to change status with update_issue. Private or localhost pages require the browser extension’s signed-in capture.
get_issue_verifications({ issueId }) reads the latest 50 saved checks, newest first, without running another check. get_issue also includes latestVerification, or null when none exists. On an older server, an absent field means this capability has not been deployed; it does not mean the issue has never been checked.
list_issues accepts notDetected: true for issues flagged “No longer detected”, or false for issues without that flag (including issues never checked). It combines with status, state, page and other filters before pagination. The returned notDetectedAt and lastDetectedAt timestamps describe scan detection, not proof of a fix. A server that ignores this filter is refused as FILTER_NOT_SUPPORTED.
These additions need the matching server deployment before the client release. Both local and hosted MCP offer verification and saved history; hosted verification needs scan and write permission. This change does not enable verification in production.
Client review links and progress (next release)
These tools require the matching server deployment before publishing this client. The guest-options database migration must be applied before deploying that server. They are available on local and hosted MCP connections and use the app's project permissions.
| Tool | What it does |
|---|---|
list_client_reviews |
Read a project's client links, titles, share URLs, capture status, visits, comments, completed reviewers, and each client's invitation/reminder state. |
create_client_review |
Create a live or snapshot review link, optionally with a title, client email addresses, a welcome note and private guest comments. Snapshot capture finishes asynchronously; read the list for readiness. |
update_client_review |
Revoke or restore a link, change its expiry, or change responsive previews. |
set_client_review_recipients |
Replace the complete client email list. Retained addresses keep their history; removed addresses stop reminders. An empty list removes all recipients while preserving the link. |
Creating a public link requires the user's intent to share. Adding email addresses requires their intent to invite those people. A new address may receive an invitation and automatic day 3/7/10 reminders. Read invitationsEnabled and the returned per-address invites: when delivery is off, addresses are saved with sent: false, skipped: true and may be invited after it is enabled. One failed invitation does not undo the link or successful invitations.
The list returns doneReviewers and clients with email, invitedAt, inviteFailed, lastReminderAt, done, commented, and unsubscribed. Done reviewing means a client finished giving feedback; it does not certify fixes or mean everyone is done. Only the client can perform that gesture. Reminder timing and stop conditions remain owned by the existing scheduler; there is no MCP send-now tool.
After an uncertain recipient-update response, retry the same complete list and reopen it; retained addresses are not invited twice. Creating a review does not have a retry key: after a lost response, use list_client_reviews to check for the saved link before creating another. Project viewers and read-only hosted connections can read progress but cannot change links or invite people.
Retained findings, scheduled reviews, and tracker exports
These tools require the matching server update. create_review_issues shares the Auto Review/visual-comparison rollout gate.
| Tools | What they do |
|---|---|
create_review_issues |
File selected zero-based indexes from a completed review, preserving saved screenshots, page context and fix guidance. Repeating the same job and indexes recovers existing issues. |
list_scheduled_reviews, create_scheduled_review, update_scheduled_review, delete_scheduled_review |
Manage recurring public-page reviews under the dashboard's existing project permissions, plan limits and cadence rules. |
run_scheduled_review, get_scheduled_review_result |
Start a run with a request UUID, then poll that same UUID. Run now sends no email. IDs/results are retained for 24 hours; without a request ID, read the latest saved baseline and available full evidence. |
list_export_connections, list_export_destinations |
Discover connected trackers and explicit destinations. Omit collection to see the provider's available collections and required inputs. |
export_issues, get_issue_export_status |
Export existing issues with their evidence and read saved delivery/sync state. Inspect every result; partial attachments and pending work are not success. |
Exports support Jira, Linear, Asana, Trello, Notion, ClickUp, GitHub and Basecamp through the product's existing adapters. Destination fields are required; the client never chooses the first project or list. Notion lists the database retained at connection, without arbitrary database search. An already-exported issue keeps its original destination. Images, discussion, and supported field synchronization follow the same provider limits as the app; a stored sync timestamp is not proof of a fresh round trip.
Example: call list_export_destinations with { "provider": "trello" }, then list boards and lists for the chosen board. Pass both boardId and listId in export_issues.destination. Scheduling future scans and sharing issues require the user's request. After uncertain results, read saved state before starting new work.
OverlayQA MCP questions
How do I add OverlayQA MCP to Claude Code?
Run claude mcp add mcp -- npx -y @overlayqa/mcp in your terminal. Add --scope user to make it available in every project.
How do I add OverlayQA MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does OverlayQA MCP provide?
It exposes 45 tools, including create_review_issues, list_scheduled_reviews, create_scheduled_review, update_scheduled_review, delete_scheduled_review.
Which editors does it work with?
It works with Claude Code, Cursor, Windsurf, and any MCP-compatible client.
Is it free?
Yes, you can start for free with 3 accessibility or contrast scans per day. A 14-day trial increases this to 30 scans per day and enables issue and project creation.
What does it actually scan?
The server can scan any public URL for WCAG accessibility violations using axe-core and check color-contrast ratios for failing element pairs.
Do I need an account?
Yes, a free OverlayQA account is required. You connect it via a browser tab on the first run, and the connection lasts for 30 days.