Use with an AI agent

Connect the server

Add a11ied to the MCP configuration your editor or agent reads, then restart it.

{
  "mcpServers": {
    "a11ied": {
      "command": "npx",
      "args": ["-y", "a11ied", "mcp"]
    }
  }
}

Point command at a1 with args: ["mcp"] instead if you installed the package globally and want the client to use that copy.

Ask the agent to call doctor first. The result says which browser a11ied uses and whether VoiceOver, NVDA, and the simulated screen reader are ready, so the agent knows which tools it can run on this machine.

The server also serves seven read-only resources, including the criteria index and the test method of every criterion in WCAG 2.1 and 2.2. See the MCP reference.

The automated checks

The automated checks run axe-core, the open-source rule engine most automated accessibility checkers use. a1 injects it into the page and runs it there, so it sees the rendered DOM, not just the HTML a server sent. Start your development server, then give the agent the exact route and the WCAG level you want tested.

Open http://localhost:3000/account/settings.
Use a11ied to run axe at WCAG level AA.
For each violation, give me the selector, the impact, and the failing HTML.

The agent calls run_axe with target set to the URL and level: "AA". Omitting criterion, level, and ruleIds runs every rule mapped to a WCAG criterion. The response has a verdict object and exitCode 4 when a violation was found.

Screen reader sessions

Use a session for labels, focus order, dialogs, menus, and validation messages. The automated checks do not test any of those in sequence.

Use a11ied to walk the checkout form with the screen reader.
Move through every field in order and collect every announcement.
Tell me which controls announce without a name and where the order
does not match the visual order.

The agent calls sr_session with action: "start", then sr_action for each step, then sr_expect to check that an announcement was made. For VoiceOver or NVDA, open the page in a browser before the agent starts. For the simulated screen reader, the agent passes url and allowVirtual: true.

Remind the agent to call sr_session with action: "stop" when it finishes. A session left open keeps VoiceOver or NVDA under automation until something stops it.