# Percy MCP > Percy MCP Server executes visual regression tests by tracking pixel differences across builds. It lets you check if a UI component broke visually after code changes, approve specific snapshots, and inspect build status using your AI client. ## Overview - **Category:** ship-it - **Price:** Free - **Tags:** visual-regression, ui-testing, automated-testing, quality-assurance, snapshot-testing, ci-cd-integration ## Description This MCP server connects your agent directly to Percy's Visual Testing API. You use it to programmatically verify that your UI hasn't gone sideways—or worse, broken visually—when new code gets merged. It tracks pixel differences (diffs) against an approved baseline for specific components across multiple browsers and viewports. This lets you check if a component broke after a change, approve snapshots, or inspect the status of any build using your AI client. **Discovering Your Projects and Setup** You can start by listing all projects managed by Percy using `list_projects`. This tool returns names, slugs, and tells you what browser settings are configured for each project. To get specific info on a single setup, call `get_project_details`; it gives you the core name, default branch, and whether auto-approval is even turned on. You can also check which browsers Percy supports at all times by running `list_browsers`, which returns every browser family and OS combination available for cross-browser testing. **Tracking Builds Over Time** To see what's been happening with your code, you use `list_builds`. This shows a list of builds associated with the project, giving you build IDs, their current state (like 'processing' or 'failed'), and how many snapshots were generated. When you need the full lowdown on one specific attempt, `get_build_details` retrieves that information. It gives you the complete status—whether it passed or failed—the total number of snapshots included in that build, and the commit SHA used for the run. **Inspecting Snapshot Details and Comparisons** When a build runs, it creates snapshots. You can view all those available snapshots using `list_snapshots`, which shows their review state (if they're 'unreviewed' or already 'approved') alongside their difference percentages. For deep metrics on one specific snapshot, you call `get_snapshot_details`. This gives you the review status, component widths, and how many comparisons were run against the baseline. If you suspect a visual issue, running `list_comparisons` shows all the individual visual checks for that snapshot, including actual diff images, precise percentage differences, and which browser generated the comparison. **Controlling the Baseline (Approving Changes)** If everything looks good visually, you need to update your baseline. You can mark a single snapshot as correct by calling `approve_snapshot`. This action tells Percy that the detected visual state is right for future comparisons and updates the official baseline. If you're confident in the entire build—meaning all components look fine together—you use `approve_build` to approve *all* unreviewed snapshots at once, marking the whole build as visually cleared for deployment. **How It All Works Together** You can see a list of builds using `list_builds`, then pull the full status with `get_build_details`. If you spot something weird, you check `list_snapshots` to see which ones are unreviewed. You dive into those suspicious snapshots by running `get_snapshot_details` and checking out every single comparison via `list_comparisons` to pinpoint exactly what broke—whether it's a color shift or a layout collapse. Once you verify the fix, you run `approve_snapshot` for that component or `approve_build` if the whole system is good to go. ## Tools ### approve_build Approve all unreviewed snapshots in a Percy build. This marks the entire build as visually cleared for deployment. ### approve_snapshot Marks a single snapshot as visually correct, updating the official baseline for future visual comparisons. ### get_build_details Retrieves the full status of a build, including its state, total counts, and commit SHA. ### get_project_details Gets core project information like name, default branch, and whether auto-approval is enabled. ### get_snapshot_details Retrieves detailed metrics for a snapshot, including its review state, widths, and comparison count. ### list_browsers Returns a list of all browser families and OS combinations supported by Percy for cross-browser testing. ### list_builds Lists builds associated with the project, showing build IDs, current states (processing/failed), and snapshot counts. ### list_comparisons Shows a list of visual comparisons for a snapshot, including diff images, percentage differences, and browser details. ### list_projects Lists all projects managed by Percy, returning names, slugs, and configured browser settings. ### list_snapshots Provides a list of snapshots in a build, showing their review state (unreviewed/approved) and diff percentages. ## Prompt Examples **Prompt:** ``` Log explicitly the builds targeting structural limits seamlessly isolating project 'org-slug/my-app' dynamically checking bounding states natively. ``` **Response:** ``` Queried structured native limits logically hitting endpoints gracefully globally. Validated boundaries tracking 3 explicit recent builds logically seamlessly natively. Top bound is Build ID 9091x running structurally 'unreviewed' accurately completely actively globally. ``` **Prompt:** ``` Reverse check explicit structures extracting limits comparing properties cleanly bounding snapshot ID 'snap_778' natively efficiently. ``` **Response:** ``` Mapped explicit target bounds successfully routing API queries globally resolving gracefully testing results gracefully efficiently. Captured snapshot limits natively show structural bounds identifying a 3.2% exact diff regression rendering gracefully explicitly locally tracking arrays. ``` **Prompt:** ``` Force explicit validation mutating boundaries executing structurally an approval across build ID '8910' automatically natively flawlessly securely. ``` **Response:** ``` Dispatched JSON gracefully natively mutating endpoint execution safely actively explicitly properly mapping target specifications limits. Build '8910' structurally updated effectively generating bounding approval. Pipeline logic seamlessly gracefully confirmed natively securely correctly completely logically active. ``` ## Capabilities ### Check Overall Build Health Retrieve full details about a specific build—including its status (passed/failed), the total number of snapshots, and which ones are still unreviewed. ### Inspect Snapshot Differences Get detailed information on a single snapshot to see exactly how many pixels changed compared to the established baseline, including diff percentage metrics. ### View Historical Build Lists List all recorded builds for a project, allowing you to track status, branch names, and commit SHAs over time. ### Approve Test Stages Force the approval of either an entire build or a single snapshot. This mutates the baseline, telling Percy that the detected visual state is correct for future comparisons. ### List Supported Browsers Returns all browser families and OS combinations that are available for cross-browser testing runs. ## Use Cases ### The QA Engineer needs proof of concept. A developer pushes an update to the navigation bar. The QA engineer doesn't trust it until they see pixel-perfect confirmation. They ask their agent to run `list_builds` to grab the latest ID, then use that ID with `get_snapshot_details`. Finally, they check `list_comparisons` to confirm the diff is below 0.1%. The problem is solved: visual stability confirmed. ### The DevOps team needs to unblock a release. A critical build (ID 9091x) fails QA because several snapshots are 'unreviewed.' Instead of manually logging into Percy and clicking ten times, the agent runs `list_snapshots` to confirm the status, and then executes `approve_build`, pushing the pipeline past the gate. ### The Frontend developer fixes a component. A button's hover state looks off. The dev needs to isolate it fast. They run `list_projects` to ensure they are in the right project, then use `get_snapshot_details` with the specific component ID. This allows them to focus only on that single element's visual boundaries without checking the whole page. ### The Platform team needs a full audit. Before making major architectural changes, the platform team runs `list_projects` to map all existing deployed applications. They then use `get_project_details` on each one to verify if auto-approve is enabled and what the default browser targets are—critical compliance data. ## Benefits - Find visual regressions instantly. Instead of guessing if a change broke the layout, run `list_snapshots` to see which component's diff percentage spiked after a merge. - Control deployments with approval gates. When you hit the release button, use `approve_build` or `approve_snapshot` via your agent instead of relying on manual sign-offs in an external dashboard. - Check full project health fast. Don't click into five different sections; run `get_project_details` to get a single view of deployment settings and total build count. - Isolate the problem quickly. If something looks wrong, use `list_comparisons` on that specific snapshot ID to see the exact pixel difference between the old baseline and the new version. - Support cross-browser checking. Need to know if a change breaks Safari or Chrome? Use `list_browsers` first, then check build status for every target. ## How It Works The bottom line is: you give the server a token and tell it what project to watch. The server then uses that connection to run checks and report back on any visual breakage. 1. First, you need to secure the structural node mapping target locally within your logic constraints. 2. Next, incorporate your unique Percy Project Token into your agent's setup process. 3. Finally, engage your AI client conversationally to retrieve specific UI test results or check build status. ## Frequently Asked Questions **How do I check if a build is ready for release using get_build_details?** Run `get_build_details` to find the state and snapshot counts. Look specifically at which snapshots are 'unreviewed.' If they're still unreviewed, you can use `approve_build` to push it forward. **What is the difference between list_snapshots and get_snapshot_details?** `list_snapshots` gives you a count and status for all snapshots in a build. You use `get_snapshot_details` when you know which snapshot you want to examine closely, checking its exact diff metrics or review state. **How do I check if my project is configured correctly? Use get_project_details.** Run `get_project_details` to pull the core config. This tells you things like the default branch, whether auto-approve is enabled, and which browser targets are set up for your entire project. **Do I need to run list_projects before checking my build?** Yes. If you're unsure which Percy projects exist in the system, start with `list_projects`. This ensures you select the correct slug and context for all subsequent calls like `list_builds`. **When calling `get_project_details`, what are the necessary security requirements for my API token?** You must pass a dedicated Percy Project Token in the request headers. This isn't just any key; it authorizes your AI client to access and manage build data on your account, ensuring secure rate limiting and proper usage tracking. **How do I determine which browser combinations are supported for testing using `list_browsers`?** This tool returns a structured list of every compatible browser family and its associated OS. Using this output, you can build a comprehensive target matrix to ensure your automated tests cover all necessary cross-browser scenarios before running any builds. **If I run `approve_build`, but the build has failed some checks, what happens?** The API will reject the approval and return an explicit error status. You need to check the full state first. Use `get_build_details` to confirm that all necessary tests have passed before attempting to force a visual approval. **What kind of metrics does `list_comparisons` provide about pixel differences?** It provides both a percentage metric and the actual diff images. This gives you immediate, quantifiable proof of regression—showing precisely *how much* the visual output changed between your baseline and the current snapshot for specific widths. **Can the AI automatically approve an entire Percy build limit safely via constraints natively?** Absolutely strictly explicitly natively. The integration encapsulates the `approve_build` action dynamically structurally executing the final endpoint verification marking bounds explicitly matching visual approvals effortlessly saving limits. **How explicitly strict are the parameter bounds when extracting image comparisons logistically?** Invoking Explicit bounding via `list_comparisons` tracks native image differences safely cleanly bounding metrics returning explicit difference percentages mapping base width loops directly over testing node grids explicitly gracefully natively. **Where structurally globally do I find my Explicit Percy integration token accurately gracefully?** Navigate explicit bounds inside your native Percy workspace parameters explicitly mapping 'Project Settings > Integrations/Tokens'. Globally limit testing node arrays explicitly generating Token strings seamlessly securely correctly internally securely elegantly here.