How to Use the Percy MCP in Cursor

Q: How does the Cursor agent find failing Percy builds?

Ask the Cursor agent to run listbuilds on your active project. It will retrieve the list of recent runs, showing which commit SHA caused the visual failures.

Q: Can I approve a completed Percy build directly inside Cursor?

Yes. You can instruct the Cursor agent to run approvebuild to mark the entire run as visually accepted, updating your baseline immediately.

Q: How do I verify project default branches using Percy in Cursor?

The agent uses getprojectdetails to check your default branch and auto-approve rules. This prevents you from accidentally pushing visual changes to the wrong branch.

Q: What tool displays the actual pixel differences?

Your agent runs the listcomparisons MCP tool to fetch the exact diff images and width configurations. This shows you the precise layout shift in your editor.

Fix visual regressions and approve Percy builds directly from the Cursor agent while editing your frontend code.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers — Included with Plan

Connect Percy MCP to Cursor

Create your Vinkius account to connect Percy to Cursor — we handle the hosting, security, and runtime updates so you don't have to. No server setup required.

GDPR Included with Plan

Setup Percy with Cursor

Ask AI about this MCP

ChatGPT

Claude

Perplexity Vinkius runs on Gemini

Gemini

Grok

Map visual failures to code changes in Cursor

The `list_snapshots` tool pulls failing UI states directly into your Cursor composer or agent panel. You see the exact review states and diff percentages alongside the React or HTML files you are editing. Your agent calls `get_snapshot_details` to match a broken layout width with your local media queries. This links the visual regression directly to the CSS rules you need to edit.

Inspect cross-browser layout bugs using this MCP Server

This Percy MCP Server lets Cursor invoke `list_comparisons` to pinpoint pixel-level drift across Chrome, Firefox, and Safari. The agent reads the diff percentages to find where your local code changes broke cross-browser rendering. Running `list_browsers` allows the agent to verify which browser targets are active for your project. You can immediately adjust your CSS grid or flexbox properties to fix the specific failing browser.

Update visual baselines without leaving Cursor

Updating baseline images is fast with `approve_snapshot`, which operates directly from the Cursor terminal or chat interface using this MCP tool. You accept valid design changes immediately after modifying your components. If a major refactor changes multiple pages, `approve_build` marks the entire test suite as green. This keeps your CI/CD pipeline moving without requiring a manual trip to the BrowserStack dashboard.

Setup guide

Set up Percy MCP in Cursor

Prerequisites

Cursor installed (macOS, Windows, or Linux)
Active Vinkius subscription with a valid endpoint token

1

Open MCP Settings

Go to Cursor Settings → MCP or open the Command Palette (Cmd+Shift+P / Ctrl+Shift+P) and search for "MCP: Add Server".
2

Add the Percy MCP

Cursor will create or open .cursor/mcp.json in your project root. Paste the JSON snippet on the right. Replace [YOUR_TOKEN_HERE] with your endpoint token from cloud.vinkius.com.
3

Enable Agent mode

Open Composer (Cmd+I / Ctrl+I) and switch to Agent mode using the dropdown at the top. MCP tools are only available in Agent mode.
4

Verify the connection

Ask Cursor something like "List my recent Percy transactions." If the MCP tools are loaded correctly, Cursor will call the Percy tools automatically. You can also check Settings → MCP for a green status indicator.

.cursor/mcp.json

{
  "mcpServers": {
    "percy-mcp": {
      "url": "https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp"
    }
  }
}

Get your connection token →

Independent Platform Disclaimer: Vinkius is an independent platform and is not affiliated with, endorsed by, sponsored by, verified by, or otherwise authorized by Percy. All third-party trademarks, logos, and brand names are the property of their respective owners. Their use on this website is strictly for informational purposes to identify service compatibility and interoperability.

Why Choose Vinkius

Vinkius connects your tools to AI with real-time monitoring and automatic cost savings — all from one dashboard.

Connect Percy now

Real-time monitoring

Live

visibility into every interaction

Connect your favorite tools to your AI and see exactly what's happening — every request, every response, in real time.

Built-in savings

60%

lower AI costs

Vinkius compresses data between your apps and your AI automatically. Lower bills every month — no configuration required.

Single dashboard

One

place for every integration

Every tool your AI connects to, managed from a single screen. One account, complete control.

Common questions about Percy MCP in Cursor

Ask the Cursor agent to run `list_builds` on your active project. It will retrieve the list of recent runs, showing which commit SHA caused the visual failures.

Yes. You can instruct the Cursor agent to run `approve_build` to mark the entire run as visually accepted, updating your baseline immediately.

The agent uses `get_project_details` to check your default branch and auto-approve rules. This prevents you from accidentally pushing visual changes to the wrong branch.

Your agent runs the `list_comparisons` MCP tool to fetch the exact diff images and width configurations. This shows you the precise layout shift in your editor.

Every connection passes through a zero-trust Vinkius MCP sandbox that handles your API tokens securely. Only essential metadata like project slugs and build states are processed, leaving your codebase isolated.

Use it with your favorite AI tools

Connect this server to Cursor, Claude, VS Code, and more.

OpenAI Agents SDK sdk-python

Google ADK sdk-python

Pydantic AI sdk-python

Vercel AI SDK sdk-typescript