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 browser extension–based analysis (recommended, works on authenticated pages) and headless-capable Chromium analysis
• 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 22.13 or higher (required)
• MCP Client: Compatible MCP host application such as:
  • Claude Code
  • Visual Studio Code
  • Cursor
  • Windsurf (Devin)
  • Kiro
  • Codex
  • Any MCP-compatible AI client
• Operating System: Windows, macOS, or Linux
• Browser: A Chromium-based browser — Google Chrome, Microsoft Edge or Brave — with the Evinced extension (extension mode). Chromium is installed automatically for Chromium mode.

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.

To verify access to the registry, run:

1npm view @evinced/mcp-server-web version

The command should print a version number. If it fails, re-check the JFrog token in your .npmrc file.

Authentication

The Evinced Web MCP Server authenticates you with your Evinced user account through the Evinced web login form. No credentials need to be configured in advance. Choose one of the following options:

• Option A — Device flow: On the first tool call, the MCP server responds with a login link and a verification code. Open the link, confirm the code and log in. The server detects the completed login automatically — no restart is needed.
• Option B — CLI login: Run a login command from your terminal after configuring your MCP client. See Step 1 of the Installation section for details.

CI/CD and headless environments: interactive login is not possible in CI pipelines. Contact your Evinced representative to obtain service credentials for automated environments.

Browser extension (Recommended)

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

The server runs in one of two modes, chosen by the --extension argument:

• Extension mode analyzes pages in your own browser through the Evinced extension.
• Chromium mode launches a separate Chromium browser that the server controls.

1. Extension Mode (Recommended, enabled with --extension):

   • Analyzes pages in your own Chromium-based browser through the Evinced extension
   • 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

2. Chromium Mode (used when --extension is not set):

   • Launches a Chromium browser (visible by default; pass --headless to hide it)
   • Navigates to specified URL
   • Performs comprehensive accessibility scan
   • Suitable for public pages and automated workflows

Installation

Step 1: Configure Your MCP Client

Authentication setup

Before or after configuring your client, complete the setup for your chosen login option:

• Option A (device flow): No action needed at this stage. You will be prompted with a login link and verification code on the first tool call after setup.

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

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

To log out at any time:

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

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

The configuration for other JSON-configured clients (Claude Code, Cursor, Windsurf, Kiro, 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)

Open your Visual Studio Code MCP configuration from the command palette (Cmd+Shift+P on macOS, Ctrl+Shift+P on Windows/Linux) and run MCP: Open User Configuration.

With Browser Extension Support (Recommended)

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

Chromium Mode

1{
2    "servers": {
3        "evinced-web-mcp": {
4            "command": "npx",
5            "args": ["-y", "@evinced/mcp-server-web@latest"],
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@latest",
8                "--config",
9                "/path/to/evinced.jsonc"
10            ],
11            "type": "stdio"
12        }
13    }
14}

evinced.jsonc holds Evinced-specific settings for the server, such as analysis scope, iframe scanning and proxy settings. See Configuration file for its format and options.

The @latest tag makes npx fetch the newest release instead of reusing a cached older version. For all available server arguments, see Command-line options.

Step 2: Restart Your MCP Client

After configuring the server, it is recommended to restart your MCP client (VSCode, Claude Code, 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

Command-line options

Pass these options in the args array of your MCP client configuration:

Note: An unknown option stops the server from starting.

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. Machine-level fallback — ~/.evinced/web/config.jsonc in your home directory (a project file always takes precedence)
4. No file found — use all defaults

All fields are optional. Omitted fields use sensible defaults. Invalid values, unknown keys or malformed JSONC stop the server from starting; the error shown in your MCP client's output panel names the field to fix. The one exception is remediationMaxAttempts, which logs a warning and falls back to its default.

Configuration file schema

The configuration file has two top-level sections:

1{
2  // Passed through to the Evinced engines.
3  "analysis": { ... },
4
5  // Controls AI remediation behavior. Validated at startup.
6  "mcp": { ... }
7}

`analysis` section

Configuration passed through to the Evinced engines.

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 stop the server from starting (except remediationMaxAttempts, which warns and falls back to its 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}

Proxy Support

Proxy support is opt-in. Pass --useProxy in the server args to enable it. Without this flag, no proxy code runs — environment variables, system proxy settings, and mcp.proxy config are all ignored.

The MCP server can route all outbound traffic through an HTTP/HTTPS proxy. This covers:

• All outbound HTTP requests from the server (authentication, analytics)
• Chromium mode browser traffic (page loads, analysis by the Evinced engines)

In extension mode, pages are loaded by your own browser, which uses its own proxy settings.

Enabling proxy support

Add --useProxy to the server args in your MCP client configuration:

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

Without --useProxy, the server starts without any proxy configuration. Setting mcp.proxy in evinced.jsonc without passing --useProxy logs a warning at startup and has no effect.

Proxy resolution priority

When --useProxy is enabled, the server resolves proxy configuration using the following priority chain:

1. Explicit config — mcp.proxy in evinced.jsonc
2. System auto-detection — native OS proxy settings (macOS, Windows, Linux)
3. Standard environment variables — HTTPS_PROXY, https_proxy, HTTP_PROXY, http_proxy

If none of the above are set, the server connects directly without a proxy.

Configuration options

Option 1 — evinced.jsonc config file:

1{
2    "mcp": {
3        "proxy": {
4            "server": "http://proxy.corp.example.com:8080",
5            "username": "proxyuser",
6            "password": "proxypass"
7        }
8    }
9}

The username and password fields are optional — omit them for unauthenticated proxies.

Option 2 — System proxy auto-detection:

The server detects your operating system's proxy settings automatically. No configuration needed.

Option 3 — Standard environment variables:

1{
2    "servers": {
3        "evinced-web-mcp": {
4            "command": "npx",
5            "args": [
6                "-y",
7                "@evinced/mcp-server-web@latest",
8                "--extension",
9                "--useProxy"
10            ],
11            "type": "stdio",
12            "env": {
13                "HTTPS_PROXY": "http://proxy.corp.example.com:8080",
14                "NO_PROXY": "localhost,127.0.0.1"
15            }
16        }
17    }
18}

Supported environment variables (in priority order): HTTPS_PROXY, https_proxy, HTTP_PROXY, http_proxy. Use NO_PROXY / no_proxy to bypass the proxy for specific hosts.

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

Chromium 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

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. For pages behind login or with specific state, 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: The login link is not clickable in your MCP client.

Solution: Copy the URL from the message and open it in your browser, then enter the verification code shown next to it.

Error: You need to log in with a different Evinced account.

Solution:

1. Run npx -y @evinced/mcp-server-web@latest --logout to clear the stored login
2. Retry the tool call (device flow) or run npx -y @evinced/mcp-server-web@latest --login (CLI login)

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 Chromium 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.