Configuration Reference

This page documents the environment variables the axe MCP Server reads, and the recommended custom instructions for your AI agent. These apply to both the Docker and npm distributions. For where to place these values, see your client setup guide.

Configuration Options

The axe MCP Server supports several environment variables for customization:

AXE_SERVER_URL

The default value (https://axe.deque.com) is correct for most users — those on Deque's shared US SaaS instance. If your organization uses any of the following, you must set AXE_SERVER_URL to your instance's base URL:

• A regional SaaS instance (EU, Australia, Frankfurt, etc.)
• A private cloud deployment
• An on-premises installation

If you are unsure which instance your organization uses, check the URL you use to log into the axe Account Portal, or ask your administrator.

Set AXE_SERVER_URL explicitly in the env block of your MCP server configuration. The client setup guides include examples showing exactly where to add it.

AXE_CHROME_PATH

npm distribution only. This is not supported in Docker, which always uses its bundled browser — the server fails to start if AXE_CHROME_PATH is set under the Docker distribution.

By default, the npm distribution uses the Chromium build you install through Playwright. Set AXE_CHROME_PATH to the full path of an existing Chrome/Chromium binary to use that instead and skip the Playwright install.

• The value must be an executable binary file, not a .app bundle or directory. On macOS, for example, point at the binary inside the bundle: /Applications/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing.
• The binary must launch and respond to --version. The server validates this at startup and fails fast with Unable to find specified chrome instance if it can't.
• Branded Google Chrome stable 137 and later is not supported. Use Chrome for Testing or another Chromium-compatible binary.

The analyze and igt tools also accept a per-call chromePath argument, which takes precedence over AXE_CHROME_PATH for that call.

Configuring Your AI Agent (Recommended)

To ensure your AI coding agent uses the axe MCP Server tools correctly and follows accessibility best practices, you can provide it with custom instructions. These instructions help the agent understand the proper workflow for analyzing and remediating accessibility issues.

Where to Add Instructions

The method varies by client:

• VS Code with GitHub Copilot - Add to .github/copilot-instructions.md in your project root
• Cursor - Add to "Cursor Rules" in settings
• Claude Code - Add to a CLAUDE.md file in your project root
• Claude Desktop - Add to custom instructions in settings
• Other MCP clients - Consult your client's documentation for custom instruction configuration

Example Workflow Instructions

Below is a recommended template you can adapt for your agent:

# Accessibility Testing and Remediation Workflow

## MANDATORY WORKFLOW - DO NOT DEVIATE

When working with accessibility issues, you MUST follow this exact workflow:

### 1. Analysis Phase

When asked to analyze pages for accessibility issues, you MUST:

- Use the `analyze` tool to scan the page
- Do NOT manually identify accessibility issues
- Always provide the complete URL being analyzed

### 2. Authentication & Pre-Scan Setup

When the user's request involves credentials, form input, dismissing
overlays, or waiting for content before the scan, you MUST:

- Pass an ordered `before` array to the `analyze` tool using the
  `click`, `fill`, and `waitFor` actions
- Resolve any references to env vars, `.env*` files, or local
  configuration into literal strings BEFORE calling the tool — the
  server treats `value` as a literal and will not expand `${VAR}`,
  `$VAR`, or `{{VAR}}` syntax
- Use `fill` for secret values so the server's redaction protections
  apply; never embed secrets in a `selector`, which appears in logs
  and error messages
- ASK the user when the source of a credential or value is ambiguous;
  do NOT guess or fabricate values
- Use ONLY selectors the user provided; if a step needs a selector
  the user did not name, ASK rather than guess
- Use `waitFor` after any `click`/`fill` that triggers async UI
  (route changes, late-rendered content) to deterministically gate
  the next step or the scan — pick a selector that exists ONLY in
  the post-interaction state (e.g., a logout button or dashboard
  heading), never a generic one like `body` or `#app` that already
  exists beforehand

### 3. Remediation Phase

When asked to remediate or fix accessibility issues, you MUST:

- Collect ALL violations from the analysis and pass them to the
  `remediate` tool in a SINGLE batched call — do NOT call `remediate`
  once per issue
- Give each issue a unique `id` so each result can be correlated
  back to its input
- Provide the exact HTML element, rule ID, and issue description for
  every issue in the batch
- Review the remediation guidance before making any code changes
- Apply fixes based on the remediate tool's recommendations
- Do NOT manually fix accessibility issues without first using the remediate tool

### 4. Verification Phase

After applying fixes, you MUST:

- Re-run `analyze` to verify all issues are resolved
- Confirm zero violations before considering the task complete

## Required Workflow Example:

1. analyze → Find violations
2. remediate → Pass ALL violations in one batched call to get fix guidance
3. Apply recommended fixes to code
4. analyze → Verify fixes

## Enforcement

- NEVER skip the remediate tool when fixing accessibility issues
- ALWAYS use both analyze and remediate tools as specified
- This workflow ensures proper accessibility best practices and compliance

Why This Matters

These instructions ensure your agent:

• Uses Deque's expertise - Leverages AI models trained on decades of accessibility assessment data instead of general LLM knowledge
• Follows best practices - Applies consistent, WCAG-compliant fixes rather than generic solutions
• Verifies changes - Always confirms fixes actually resolved the issues
• Avoids false confidence - Doesn't assume it knows how to fix accessibility issues without expert guidance

While optional, providing these instructions significantly improves the quality and reliability of accessibility fixes in your codebase.