Web MCP Server

Purpose

The Evinced Web MCP Server is a Model Context Protocol (MCP) server that enables AI agents and developers to integrate automated web accessibility testing directly into their workflows. Built on Evinced's industry-leading accessibility scanning technology, this server empowers AI assistants to analyze web pages for WCAG compliance issues and provide actionable remediation guidance.

Key value propositions

• AI-Native Accessibility Testing: Seamlessly integrate accessibility analysis into AI-driven development workflows through the standardized MCP protocol
• Automated Issue Detection: Identify accessibility violations including keyboard navigation issues, semantic role problems, missing accessible names, and more
• Intelligent Remediation Guidance: Receive context-aware, LLM-optimized remediation instructions for each detected issue type
• Flexible Analysis Modes: Support for both SDK-based analysis (headless browser automation) and browser extension-based analysis (for authenticated pages)
• Enterprise-Grade Scanning: Powered by Evinced's commercial-grade accessibility engines with support for iframes and complex web applications

Use cases

1. Development Workflow Integration: Enable AI coding assistants to proactively identify and fix accessibility issues during feature development
2. Remediation Orchestration: Leverage AI agents to systematically analyze, prioritize, and remediate accessibility issues detected by Evinced technology across entire applications

System Requirements

Software dependencies

• Node.js: Version 18 or higher (required)
• MCP Client: Compatible MCP host application such as:
  • Visual Studio Code
  • Cursor IDE
  • Any MCP-compatible AI client
• Operating System: Windows, macOS, or Linux
• Browser: Google Chrome (Required for extension mode), Chromium (automatically installed via Playwright)

Access to the web MCP server package

The Evinced web MCP server package is distributed via the Evinced repository. Please ensure that your .npmrc file contains the following template:

1@evinced:registry=https://evinced.jfrog.io/artifactory/api/npm/restricted-npm
2///evinced.jfrog.io/artifactory/api/npm/restricted-npm/:_authToken=<your-jfrog-token>
3//evinced.jfrog.io/artifactory/api/npm/restricted-npm/:always-auth=true

Your Evinced JFROG token should be provided to you by your Evinced contact.

Authentication

The Evinced Web MCP Server supports two authentication flows. Choose the one that fits your environment before proceeding to installation.

• User authentication (recommended): Uses Evinced web login form authentication. No credentials need to be configured in advance. Suitable for interactive development environments.

  • Option A — Device flow: The MCP server will respond with a link to a login form on the first request. No setup required.
  • Option B — CLI login: Run a login command after configuring your MCP client. See Step 1 of the Installation section for details.

• Token authentication: Set credentials via environment variables for non-interactive authentication. Recommended for CI/CD, automated workflows, and headless environments. Requires EVINCED_SERVICE_ID and EVINCED_API_KEY, which must be added to your MCP client configuration. See Step 1 of the Installation section for details.

The Token authentication flow takes priority over User authentication. Note: Contact Evinced support to obtain your credentials if you don't have them.

Browser extension

For analyzing pages behind authentication or pages requiring specific browser state, install the companion browser extension to enable analysis of the active browser tab.

Download the extension from the Chrome Web Store.

Capabilities

Accessibility issue detection

The Evinced Web MCP Server detects a comprehensive range of accessibility violations across multiple WCAG success criteria.

Analysis features

• Automated Page Scanning: Complete accessibility analysis of web pages via URL
• Issue Prioritization: Automatic sorting by severity (Critical, Serious, Moderate, Minor) and issue type
• Remediation Instructions: Contextual, LLM-optimized guidance for fixing each issue type
• DOM Context: Detailed element information including selectors, DOM snippets, and bounding boxes
• Iframe Support: Analysis of accessibility issues within nested iframe content
• Summary Statistics: Issue counts grouped by severity and type

Analysis modes

1. Chromium Mode (Default):

   • Launches headless Chromium browser
   • Navigates to specified URL
   • Performs comprehensive accessibility scan
   • Suitable for public pages and automated workflows

2. Extension Mode (Recommended):

   • Analyzes the currently active browser tab
   • Supports authenticated pages and complex browser state
   • Requires Evinced browser extension installation
   • Provides two sub-modes:
     • active_tab: Scan the currently visible page
     • new_tab: Open and scan a specified URL in a new tab

Installation

Step 1: Configure Your MCP Client

Authentication setup

Before or after configuring your client, complete the setup for your chosen authentication flow:

• User authentication — Option A (device flow): No action needed at this stage. You will be prompted with a login link on the first request after setup.

• User authentication — Option B (CLI login): After configuring your client below, run:

1npx @evinced/mcp-server-web --login

To log out at any time:

1npx @evinced/mcp-server-web --logout

• Token authentication: Add an env block with your credentials to your client configuration. See the token authentication configuration example at the end of this step.

The configuration varies depending on your MCP client. Below are examples for Visual Studio code.

The configuration for other IDEs (Cursor, Windsurf, etc) is identical with the following exceptions:

• The primary key is called "mcpServers" and not "servers"
• The key "type":"stdio" is not required.

Configuration examples (Visual Studio Code)

Edit your Visual Studio configuration file directly from the IDE by opening the Visual Studio Code command palette and selecting “MCP.JSON”

Basic Configuration (Chromium Mode)

1{
2  "servers": {
3    "evinced-web-mcp": {
4      "command": "npx",
5      "args": ["-y", "@evinced/mcp-server-web"],
6      "type":"stdio"
7    }
8  }
9}

With Browser Extension Support (Recommended)

1{
2  "servers": {
3    "evinced-web-mcp": {
4      "command": "npx",
5      "args": ["-y", "@evinced/mcp-server-web", "--extension"],
6      "type":"stdio"
7    }
8  }
9}

With Custom Configuration File

1{
2  "servers": {
3    "evinced-web-mcp": {
4      "command": "npx",
5      "args": [
6        "-y",
7        "@evinced/mcp-server-web",
8        "--config",
9        "/path/to/config.json"
10      ],
11      "type":"stdio"
12    }
13  }
14}

Headless Mode (Optional)

1{
2  "servers": {
3    "evinced-web-mcp": {
4      "command": "npx",
5      "args": ["-y", "@evinced/mcp-server-web", "--headless"],
6      "type":"stdio"
7    }
8  }
9}

Token Authentication Configuration

If you selected token-based authentication (see the Authentication section), add an env block with your credentials to your configuration. The examples below show how to apply it to each of the configurations above.

Basic Configuration (Chromium Mode)

1{
2  "servers": {
3    "evinced-web-mcp": {
4      "command": "npx",
5      "args": ["-y", "@evinced/mcp-server-web"],
6      "type": "stdio",
7      "env": {
8        "EVINCED_SERVICE_ID": "your-service-id",
9        "EVINCED_API_KEY": "your-api-key"
10      }
11    }
12  }
13}

With Browser Extension Support (Recommended)

1{
2  "servers": {
3    "evinced-web-mcp": {
4      "command": "npx",
5      "args": ["-y", "@evinced/mcp-server-web", "--extension"],
6      "type": "stdio",
7      "env": {
8        "EVINCED_SERVICE_ID": "your-service-id",
9        "EVINCED_API_KEY": "your-api-key"
10      }
11    }
12  }
13}

With Custom Configuration File

1{
2  "servers": {
3    "evinced-web-mcp": {
4      "command": "npx",
5      "args": ["-y", "@evinced/mcp-server-web", "--config", "/path/to/evinced.jsonc"],
6      "type": "stdio",
7      "env": {
8        "EVINCED_SERVICE_ID": "your-service-id",
9        "EVINCED_API_KEY": "your-api-key"
10      }
11    }
12  }
13}

Headless Mode (Optional)

1{
2  "servers": {
3    "evinced-web-mcp": {
4      "command": "npx",
5      "args": ["-y", "@evinced/mcp-server-web", "--headless"],
6      "type": "stdio",
7      "env": {
8        "EVINCED_SERVICE_ID": "your-service-id",
9        "EVINCED_API_KEY": "your-api-key"
10      }
11    }
12  }
13}

Step 2: Restart Your MCP Client

After configuring the server, it is recommended to restart your MCP client (Claude Desktop, Cursor, etc.) to load the new server configuration. In certain IDEs it is required to explicitly start the MCP server; for detailed instructions regarding how to restart MCP servers please refer to your IDE's documentation.

Step 3: Verify Installation

Test the installation by asking your AI assistant:

1"Use the Evinced web MCP server to analyze https://example.com for accessibility issues"

If configured correctly, the AI will invoke the evinced_analyze_webpage tool and return accessibility findings.

Advanced Configuration

Configuration file

The server reads configuration from a JSONC file (evinced.jsonc). JSONC is standard JSON with support for comments and trailing commas.

The server resolves the configuration file in the following order:

1. --config <path> — use the specified file (auto-created with defaults if it doesn't exist)
2. Auto-discover — look for evinced.jsonc in the current working directory
3. No file found — use all defaults

All fields are optional. Omitted fields use sensible defaults. Errors in the configuration produce warnings — the server always continues with defaults.

Configuration file schema

The configuration file has two top-level sections:

1{
2    // Passed through to the Evinced engine SDK as-is. No validation.
3  "analysis": { ... },
4
5  // Controls AI remediation behavior. Validated at startup.
6  "mcp": { ... }
7}

`analysis` section

Engine configuration passed through to the SDK without validation.

Available toggles:

• USE_AXE_NEEDS_REVIEW: Include axe-core "Needs Review" issues (default: false)
• USE_AXE_BEST_PRACTICES: Include Axe best-practice rules, non-WCAG (default: false)
• USE_EVINCED_BEST_PRACTICES: Include Evinced best-practice rules, non-WCAG (default: false)

Note: RUN_VALIDATION_ON_IFRAMES and rootSelector are controlled via the mcp section (mcp.analyzeIframes and mcp.defaultComponentSelector respectively). Setting them directly in analysis will produce a configuration error.

`mcp` section

Controls AI remediation behavior. Invalid values produce a warning and fall back to the field's default.

Configuration examples

Skip validation for specific elements

1{
2  "analysis": {
3    "skipValidations": [
4      {
5        "urlRegex": "https://myapp.com/.*",
6        "validationTypes": "COLOR_CONTRAST",
7        "selector": ".third-party-widget"
8      }
9    ]
10  }
11}

Disable iframe scanning (Iframe scanning is on by default)

1{
2  "mcp": {
3    "analyzeIframes": false
4  }
5}

Limit analysis to a specific component

1{
2  "mcp": {
3    "defaultComponentSelector": "#main-content"
4  }
5}

Complete configuration example

1{
2  "analysis": {
3    "toggles": {
4      "USE_AXE_NEEDS_REVIEW": false
5    },
6    "skipValidations": [
7      {
8        "urlRegex": "https://myapp.com/.*",
9        "validationTypes": "COLOR_CONTRAST",
10        "selector": ".third-party-widget"
11      }
12    ]
13  },
14  "mcp": {
15    "analyzeIframes": true,
16    "defaultComponentSelector": "#app",
17    "verification": {
18      "disabled": false,
19      "requireUserStateSetup": false
20    },
21    "remediationMaxAttempts": 3
22  }
23}

Tools

The Evinced Web MCP Server exposes the following tools and prompts to AI agents:

Tool: evinced_analyze_webpage

Analyzes a web page for accessibility issues and returns a report identifier along with a summary and simplified issue list.

Parameters

Chromium Mode (default):

• url (string, required): The URL of the page to analyze
• componentSelector (string, optional): CSS selector that defines the DOM subtree to analyze. When set, only accessibility issues within the matching element and its descendants are returned. Set to an empty string to analyze the entire page. Overrides mcp.defaultComponentSelector from the configuration file.

Extension Mode (when --extension flag is set):

• tabMode (enum, optional): Analysis mode
  • "active_tab" (default): Analyze the currently active browser tab
  • "new_tab": Open and analyze a new tab with the specified URL
• url (string, optional): Required when tabMode is "new_tab", ignored for "active_tab"
• componentSelector (string, optional): Same as Chromium Mode

Priority sorting

Issues are automatically sorted with the following priority:

1. Highest Priority (regardless of severity):

   • WRONG_SEMANTIC_ROLE (Interactable role issues)
   • NOT_FOCUSABLE (Keyboard accessibility issues)

2. Critical Severity (for all other issue types)

3. Other Severities (Serious, Moderate, Minor) in descending order

This prioritization ensures that foundational accessibility issues affecting interactive behavior are addressed first.

Example usage

SDK Mode - Analyze Public Page:

1Analyze https://example.com for accessibility issues using Evinced

Extension Mode - Analyze Active Tab:

1Analyze the current page I have open in my browser for accessibility issues

Extension Mode - Analyze Specific URL in New Tab:

1Use Evinced extension mode to analyze https://internal-app.company.com in a new tab

Remediation instructions

The issues_details section provides LLM-optimized remediation instructions for each unique issue type encountered. These instructions include:

• Cause: Technical explanation of why the issue occurs
• Effect: Impact on users, particularly those with disabilities
• Suggested Solutions: Step-by-step remediation guidance prioritized by effectiveness
• Critical Implementation Notes: Best practices and common pitfalls to avoid

For critical issue types (NOT_FOCUSABLE, WRONG_SEMANTIC_ROLE, NO_DESCRIPTIVE_TEXT), specialized sub-prompts provide enhanced remediation guidance. All other issue types receive standardized remediation instructions.

Prompt: evinced_fix_webpage_issues

A comprehensive guidance prompt that provides AI agents with a systematic workflow for analyzing and remediating accessibility issues.

Purpose

This prompt template enables AI assistants to:

• Follow a structured, step-by-step remediation workflow
• Prioritize issues based on severity and impact
• Identify UI component patterns for targeted fixes
• Apply remediation one issue at a time for quality assurance
• Validate fixes and prevent regression

Key workflow phases

1. Understand the Scope: Clarify what needs to be analyzed (page, component, section)
2. Run Initial Analysis: Execute evinced_analyze_webpage to get baseline report
3. Prioritize Critical Issues: Focus on keyboard and semantic role issues first
4. Identify Component Patterns: Match elements to ARIA Authoring Practices Guide patterns
5. Apply Targeted Remediation: Fix one issue at a time using remediation instructions
6. Address Remaining Issues: Continue through all issues in priority order
7. Validate Fixes: Re-run analysis to confirm issues are resolved

Accessing the prompt

The prompt is automatically available to AI assistants through the MCP protocol. To use it, you can press the '/' key inside your IDE's agent section and select the prompt from the list, alternatively you can use this prompt:

1Use the Evinced 'fix webpage issues' prompt to guide the accessibility remediation process.

The AI will then follow the structured workflow defined in the prompt template, ensuring systematic and thorough accessibility remediation.

Special features

• Pattern-Based Remediation: Leverages ARIA Authoring Practices Guide patterns for consistent fixes
• One-Issue-at-a-Time: Prevents batch fixing that can introduce new issues
• Validation Checkpoints: Mandatory stops after critical issues to verify fixes before proceeding

Best Practices

1. Integrate Early in Development Workflow

Recommendation: Run accessibility scans during active development, not just before deployment.

1After implementing [feature], analyze the page with Evinced to identify any accessibility issues introduced

This proactive approach catches issues when they're easiest and cheapest to fix.

2. Follow the Remediation Priority

Recommendation: Always address issues in the order provided by the tool.

The automatic prioritization ensures:

• Foundational accessibility (keyboard access, semantic roles) is fixed first
• Critical issues blocking users are prioritized
• Efficient remediation path with minimal rework

3. Fix One Issue at a Time

Recommendation: Use the 'evinced_fix_webpage_issues' prompt's one-issue-at-a-time approach rather than batch fixing.

Why: Batch fixes often introduce new issues or conflicts. Sequential fixing with validation ensures:

• Each fix is thoroughly tested
• Root causes are properly addressed
• No regression is introduced

Example workflow:

11. Use the 'evinced_fix_webpage_issues' to analyze the page
22. Let the AI fix the first critical issue
33. Validate the fix works
44. Move to the next issue
55. Re-scan after all fixes to verify

4. Leverage Remediation Instructions

Recommendation: The remediation_instructions field returned by the evinced_get_webpage_issue_details tool is the single source of truth for fixing issues.

These instructions are:

• LLM-optimized for AI comprehension
• Pattern-based for consistent fixes
• Tested and validated by accessibility experts

Instruct your AI:

1Use the remediation_instructions from the Evinced report to fix this issue, do not use general accessibility knowledge

5. Understand Component Patterns

Recommendation: For critical issues (keyboard, semantic roles), always identify the UI component pattern.

Reference the ARIA Authoring Practices Guide patterns:

• Accordion, Alert, Breadcrumb, Button, Carousel, Checkbox, Combobox, Dialog (Modal)
• Grid, Listbox, Menu, Radio Group, Slider, Switch, Tabs, Toolbar, Tooltip, Tree View
• And more...

This ensures fixes align with established accessibility patterns rather than creating custom solutions.

6. Use Extension Mode for Authenticated Pages

Recommendation: When analyzing pages behind login or requiring specific browser state, use extension mode with active_tab.

Setup:

1. Install the Evinced browser extension
2. Configure MCP server with --extension flag
3. Navigate to the page manually in your browser
4. Instruct AI: "Analyze the current page using Evinced extension mode"

7. Configure for Your Environment

Recommendation: Use configuration files to customize analysis for your application's needs.

Common scenarios:

• Skip validation for third-party widgets you can't modify
• Disable iframe scanning for performance on pages with many iframes
• Configure custom validation rules specific to your design system

8. Re-scan After Fixing

Recommendation: Always run a second analysis after applying fixes to verify:

• The original issues are resolved
• No new issues were introduced
• The fix was applied correctly

1After fixing accessibility issues, re-analyze the page with Evinced to confirm all issues are resolved

Troubleshooting

Authentication errors

Error: "No service ID provided" or "Cannot authenticate to Evinced" when using the token authentication method.

Solution:

1. Verify your EVINCED_SERVICE_ID is correctly set in the environment configuration
2. Ensure you've provided either EVINCED_API_KEY or EVINCED_AUTH_TOKEN
3. Check that credentials are valid and not expired
4. Confirm no extra spaces or quotes in credential values

MCP client cache

MCP clients may cache tool definitions and server metadata, which can cause the client to refer to outdated server information after an update or configuration change.

Solution:

1. Clear the cache of your MCP client (Instructions can be found in your IDEs documentation), or
2. Rename the MCP server entry in your configuration (e.g., from evinced-web-mcp to evinced-web-mcp-1)

This ensures the MCP client does not refer to stale cached data.

Extension connection issues

Error: "Failed to connect to extension"

Solution:

1. Verify the Evinced browser extension is installed and enabled
2. Ensure the MCP server was started with the --extension flag
3. Check if your IT department has a policy in place that blocks the Evinced extension.
4. Try restarting both the browser and the MCP client

Navigation timeout

Error: Navigation timeout or page load failures

Solution:

1. The server allows partial page analysis even if full page load times out
2. For slow-loading pages, consider using extension mode with active_tab (navigate manually first)
3. Check network connectivity and URL accessibility
4. Verify the page is publicly accessible (or use extension mode for authenticated pages)

Chromium browser issues

Error: Browser launch failures in headless mode

Solution:

1. Run npx playwright install to ensure Chromium is installed
2. Try non-headless mode by removing --headless flag
3. Check system permissions for browser execution
4. Review system requirements (sufficient memory, disk space)

Support

For technical support, questions, or feature requests please reach out to your Evinced contact.