MCP Server

Last updated: October 2, 2026

The OverlayQA MCP server (@overlayqa/mcp on npm) connects your AI coding agent to your OverlayQA workspace over the Model Context Protocol. From Claude Code, Cursor, Windsurf, or any MCP-compatible client, the agent can scan a URL for accessibility and design-system issues, then create, read, label, comment on, assign, and update issues in the same projects your team uses in the dashboard and the Chrome extension. This guide installs the server, connects your account, and walks through the tools it exposes.

Prerequisites

An OverlayQA account. Scanning works without a plan (3 scans a day); creating issues and projects needs an active trial or a paid plan.
Node.js, so your editor can run npx @overlayqa/mcp@latest.
An MCP-compatible client: Claude Code, Cursor, Windsurf, or another editor or agent that reads an MCP server config.

Install the Server

Add the server to your editor's MCP config. The same block works everywhere; only the file location differs.

Client	Config file
Claude Code	`.mcp.json` in the project root
Cursor	`~/.cursor/mcp.json`
Windsurf	`~/.codeium/windsurf/mcp_config.json`

Paste this into the file (merge it with any servers you already have): { "mcpServers": { "overlayqa": { "command": "npx", "args": ["@overlayqa/mcp@latest"] } } }. Cursor and VS Code also accept a one-click install link from the MCP server page.

Connect Your Account

The first time the agent calls an OverlayQA tool, a browser tab opens so you can sign in and connect the server to your account. There is no card step. The token caches locally for 30 days, so you connect once and keep working. Every issue the agent creates lands in your projects with your account as the creator and default assignee.

Tools Your Agent Can Call

Twenty-two tools are live, grouped by what the agent is doing. Each is described so the model picks the right one from a plain-language request such as "scan staging.example.com for accessibility issues and file the criticals".

Group	Tools
Audit	`scan_accessibility` runs a WCAG audit (axe-core) on a URL and returns violations with severity and an overall score. `scan_contrast` returns the element pairs failing WCAG contrast ratios.
Design system	`audit_tokens` returns a 0-100 token-health score with findings on font sizes, colors, spacing, font families, and border radii.
Issues	`scan_and_create_issues`, `create_issue`, `get_issue`, `list_issues`, `update_issue`, `move_issue`. List and filter by status, severity, type, labels, assignee, creator, or active, finished, and ignored state; update status, title, description, severity, type, assignee, or ignored state; accept a UUID or a display id such as OQ-12.
Labels	`list_labels`, `create_label`, `set_issue_label`, `rename_label`, `delete_label`. Rename and delete follow the same owner-or-admin rule as the dashboard.
Comments	`list_comments`, `create_comment`, `update_comment`, `delete_comment`, `get_comment_attachment`. Comments carry an audience (Team only or Team and clients), teammate mentions, and PNG, JPG, or PDF files.
Projects	`create_project`, `list_projects`, `list_project_members`.

Note: One more tool, compare_visual, is listed but not implemented yet; it returns a notice pointing to the extension. Use the Visual Comparison workflow in the extension or Team Review for Figma comparison today.

A Typical Session

Ask the agent to scan a URL: "Run an accessibility and contrast scan on https://staging.example.com/pricing." It calls scan_accessibility and scan_contrast and summarises the violations.
File the ones worth fixing: "Create issues for the critical and high violations in the Pricing project." It calls scan_and_create_issues with a severity threshold, or create_issue for a hand-picked set.
Work the backlog: "List active issues assigned to me with the release label." It calls list_issues with filters, then get_issue for the selector, CSS, and screenshot evidence on each one.
Close the loop: after the fix, "Mark OQ-12 resolved and leave a comment for the team." It calls update_issue and create_comment, and the change shows up in the dashboard and the extension immediately.

Limits by Plan

Scanning is available without a paid plan: 3 scans per day. Freelancer allows 10 scans per day, Starter 30, and Pro has no daily cap. Creating issues and projects needs an active trial or paid plan; when the cap is reached the server replies with the limit and a link to overlayqa.com/pricing. Every scan covers one page per call.

Frequently Asked Questions

Which editors work with the OverlayQA MCP server?

Claude Code, Cursor, Windsurf, and any MCP-compatible client. The server speaks standard stdio MCP, so the install block is the same everywhere; only the config file location changes.

Do issues created by my agent show up for my team?

Yes. The MCP server, the dashboard, and the Chrome extension share the same projects and issues. Anything the agent files appears in the dashboard and the extension, and anything your team changes is visible to the agent on its next call.

Can the agent use OverlayQA as the bug tracker?

Yes. With the issue, label, and comment tools the agent can create, read, label, assign, comment on, and update issues, and your team can export the same issues two ways to Jira, Linear, Notion, Asana, or Trello. See Labels, Assignees, and Filters for how the fields behave.

Does the MCP server run Visual Comparison?

Not yet. compare_visual is reserved and returns a not-implemented notice. Run Visual Comparison in the extension or Team Review for Figma comparison.