com.overlayqaPublished by overlayqa.comOfficial publisherv0.7.0Updated Oct 30, 2026
Run accessibility, contrast, and design token audits and file QA issues from your AI coding tool.
OverlayQA MCP lets an AI coding agent run accessibility, contrast and design-token audits on public URLs and file, discuss and verify QA issues in OverlayQA…
Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.
Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.
Read https://sourceweft.com/mcp/com.overlayqa%2Fmcp/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.Add this to your client's mcpServers config. The client completes OAuth sign-in on first connect.
{
"mcpServers": {
"overlayqa": {
"type": "http",
"url": "https://api.overlayqa.com/mcp"
}
}
}[Install in Cursor] [Install in VS Code] [npm] [license] [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.
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):
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 your agent can call. Each is written so the model picks the right one from natural language.
Audit
File and manage issues
AI review workflows
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.
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.
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.
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.
MIT
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.
Requires the matching issue-parity API deployment. Existing scans and status updates remain compatible with 0.2.0.
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.
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.
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_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.
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.
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.
These tools require the matching server update. create_review_issues shares the Auto Review/visual-comparison rollout gate.
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.
Source: README.md at commit 9470d4f
File 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.
jobIdrequiredcontextfindingIndexesrequiredList readable scheduled reviews in this workspace, including cadence, pause state, next run and latest saved result summary. Does not scan or send email.
contextCreate 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.
urlrequiredcadencerequiredcontextscanTyperequiredprojectIdrequiredconfirmLoginPagePause, 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.
actioncadencecontextscheduleIdrequiredDelete a scheduled review and stop its future scans and emails. Does not delete filed project issues.
contextscheduleIdrequiredRun 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.
contextrequestIdrequiredscheduleIdrequiredRead 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.
contextrequestIdscheduleIdrequiredList 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.
contextDiscover 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.
cloudIdcontextparentIdproviderrequiredaccountIdcollectionissueTypeIdExport 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.
contextissueIdsrequiredmetadataproviderrequireddestinationrequiredRead 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.
contextissueIdrequiredRun 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.
urlrequiredcontextprojectIdRun 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.
urlrequiredcontextRun 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.
urlrequiredcontextprojectIdrequiredminSeverityStart 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.
urlrequiredcontextprojectIdrequiredreferencerequestIdrequiredfigmaNodeIdfigmaFileKeymeasureSpacingStart 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.
urlrequiredcontextviewportprojectIdrequiredrequestIdrequiredbreakpointLabelRead 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.
jobIdrequiredcontextAudit 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.
urlrequiredcontextfigmaFileKeyCreate an issue in an OverlayQA project. Title is required; severity, type, and description default to medium / general / empty. Assignee defaults to you; pass null for Unassigned.
typetitlerequiredcontextseverityprojectIdrequiredassigneeIddescriptionList project issues with labels, 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, labels, 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.
pagetypestatestatuscontextpageUrllabelIdspageSizeseverityprojectIdrequiredassigneeIdcreatedById+2 moreUpdate 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.
typetitlestatuscontextignoredissueIdrequiredseverityassigneeIddescriptionRead a complete issue by UUID or display id: description, labels, assignee, ignored state, screenshot URLs, captured element/CSS and viewport evidence, its comments (the same discussion list_comments returns), and latestVerification (the newest saved check, or null). Read get_issue_verifications for history; issue status and notDetectedAt alone do not prove a fix.
contextissueIdrequiredList workspace teammates for a readable project. Use their userId for assignment and comment mentions. Returns the signed-in userId too.
contextprojectIdrequiredMove 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.
contextissueIdrequiredtargetProjectIdrequiredCheck 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.
contextissueIdrequiredrequestIdrequiredRead 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.
contextissueIdrequiredRead an issue discussion, including comment authors, audience, mentions and attachment metadata. Returns native and linked comments; edit/delete accept native comment IDs only.
contextissueIdrequiredPost a comment with explicit audience (Team only or Team and clients), optional teammate mentions and PNG/JPG/PDF files. Reuse requestId when retrying the same submission after a lost response.
contentrequiredcontextissueIdrequiredrequestIdrequiredvisibilityrequiredattachmentsmentionedUserIdsEdit your own native comment text and mention list. Audience and attached files stay unchanged. Supply the complete mention list, including retained mentions.
contentrequiredcontextissueIdrequiredcommentIdrequiredmentionedUserIdsrequiredDelete your own native comment and its attached files. This also removes it from client-visible discussions when its audience was public.
contextissueIdrequiredcommentIdrequiredRead a native comment attachment as filename and base64 bytes. Uses the same issue permissions as reading comments. Attachment IDs come from list_comments.
contextissueIdrequiredcommentIdrequiredattachmentIdrequiredList the workspace label library and your write/manage permissions. Optionally include an issue UUID to see its assigned labels.
contextissueIdprojectIdrequiredCreate a reusable workspace label. Editors can create labels; retries and case-insensitive duplicate names return the existing label. Apply it with set_issue_label.
namerequiredcontextprojectIdrequiredRename a label throughout its workspace. Requires workspace owner or admin permission. Assignments are preserved; existing shared reports keep their original names.
namerequiredcontextlabelIdrequiredprojectIdrequiredDelete a label from the workspace and all its issues. Requires workspace owner or admin permission. Issues themselves are retained.
contextlabelIdrequiredprojectIdrequiredApply (applied=true) or remove (applied=false) one workspace label on an issue. Other labels and issue text remain unchanged. Safe to retry.
appliedrequiredcontextissueIdrequiredlabelIdrequiredList all OverlayQA projects in the authenticated user's team.
contextCreate a new OverlayQA project. Returns the project id, name, slug, displayPrefix, and url.
urlnamerequiredcontextList a project’s client review links, share URLs, titles, capture status, expiry, visits, comments, doneReviewers and clients. Each client includes invitedAt, inviteFailed, 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.
contextprojectIdrequiredCreate 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 results. After a lost response, list links before creating again to avoid duplicates.
moderequiredtitlecontextpageUrlrequiredexpiresAtprojectIdrequiredwelcomeNoteclientEmailsviewportWidthviewportHeightprivateCommentsallowResponsiveViewsChange 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.
revokecontextreviewIdrequiredexpiresAtallowResponsiveViewsReplace 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.
emailsrequiredcontextreviewIdrequired100% of the applicable checks met
How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.
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): highYou: List the open criticals.Agent: list_issues(status=open, severity=critical) → 2 issues.{ "mcpServers": { "overlayqa": { "command": "npx", "args": ["@overlayqa/mcp@latest"] } }}MCP_PARITY_API=http://127.0.0.1:3241 MCP_SERVER_ENV=/path/to/server/.env npm run test:issues-liveMCP_PARITY_API=https://api.overlayqa.com npm run test:issues-live