OverlayQA MCP

What OverlayQA/mcp does

OverlayQA/mcp MCP server gives MCP-compatible coding agents access to OverlayQA’s live-page auditing and QA issue workflows. It can inspect a public URL with axe-core-based WCAG checks, evaluate color-contrast ratios, and review live design-system token consistency. Audit results include findings, severity, relevant WCAG success criteria where applicable, and scores.

The server also connects audit results to project work. Agents can create projects for site URLs, file individual issues, create issues automatically from scan findings above a chosen severity, and manage existing issues by status, severity, type, labels, assignment, creator, time, or active state. Workspace labels can be listed, created, applied, removed, renamed, or deleted according to permissions.

This belongs in the Developer Tools category for teams that want accessibility and design QA handled through natural-language requests in an editor rather than a separate issue-management workflow.

How it works

The server uses standard stdio MCP. An agent calls named tools with the URL, project, issue, or filter information required for the task. scan_accessibility returns WCAG violations and an overall score, while scan_contrast reports failing foreground and background element pairs. audit_tokens checks live-page values such as font sizes, text colors, spacing, font families, and border radii, producing a token-health score and severity-based findings.

scan_and_create_issues combines scanning with issue creation. Other tools handle issue updates, project listing and creation, and label administration. Optional context supplied to a tool is recorded with operational details such as the tool name, account, project and issue IDs, scan URL, counts, scores, and editor name and version. The context is capped and filtered for email addresses and credential-like strings; conversations, code, and tool replies are not recorded according to the README.

Setup and configuration

Install the npm package through an MCP client using npx and @overlayqa/mcp@latest. The documented configurations use the command npx with the package as an argument. Cursor and VS Code provide one-click installation links, and Claude Code, Cursor, and Windsurf have example configuration paths.

On the first launch, a browser tab opens so the user can connect an OverlayQA account. The authentication token is stored at ~/.overlayqa/auth.json for 30 days. A free OverlayQA account is required. The README also documents OVERLAYQA_API_BASE and OVERLAYQA_AUTH_FILE for local verification with an alternate API base or isolated authentication file; these do not change normal production defaults.

Tools and capabilities

• Audit public URLs for WCAG violations, contrast failures, and design-token inconsistencies.
• Create issues from scan findings or from manually supplied QA details.
• Filter and update issues using statuses, severities, types, labels, assignees, creators, and time-related fields.
• Create and list projects associated with site URLs.
• Manage reusable workspace labels, subject to workspace permissions.

Limitations and notes

Scans target public URLs, and the token audit covers the live page only. Free accounts receive three accessibility or contrast scans per day and cannot create issues or projects. A 14-day trial provides up to 30 scans per day and enables issue and project creation; paid-plan limits and features depend on the selected plan.

The README lists compare_visual as coming soon, so it should not be treated as an available capability. Export to Linear, Jira, Asana, and Notion is described as a paid-plan feature rather than a core local configuration option. The MCP server and OverlayQA’s Chrome extension share projects and issues, but the extension is a separate interface.