Accessibility Agents

A11y Agent Team MCP Server

MCP (Model Context Protocol) server that provides 39 accessibility scanning tools over Streamable HTTP or stdio. Works with Claude Code, Claude Desktop, VS Code, the Copilot CLI and any MCP-compatible client. It is built on @modelcontextprotocol/sdk 1.32.2 and implements what that SDK provides (protocol revisions up to 2025-11-25); see the MCP standards page for where it stands against 2026-07-28.

In this repository, the MCP server lives in the top-level mcp-server/ directory. The main entry points are server.js (HTTP) and stdio.js (stdio).

What Works Out Of The Box

The MCP server is the executable part of document scanning. The skills (for PDF, pdf-accessibility and pdf-scan-config under skills/) tell the model when to scan; this server provides the actual scan_pdf_document tool.

A plugin install launches dist/stdio.mjs, a single esbuild bundle of the stdio server and its dependencies, so it starts with no npm install (mcp.json, and mcpServers in .claude-plugin/plugin.json). Playwright, @axe-core/playwright and pdf-lib are left out of the bundle and stay optional; the tools that need them say how to install them. Run npm install in this folder only for the HTTP server (server.js) or to work on the source.

If you change the server's source, run npm run build here and commit the rebuilt dist/stdio.mjs: the bundle gate in npm run verify fails when the committed bundle differs from a fresh build.

Architecture

The server supports two transport modes:

Both modes share the same tool implementations via server-core.js.

Quick Start

Before you start, make sure node --version reports a supported Node.js LTS line (26, 24 or 22) and that npm is available. The repository installer does not install Node.js; get it from https://nodejs.org/en/download.

# stdio, from the bundle: no install needednode mcp-server/dist/stdio.mjs
# HTTP mode needs the dependenciescd mcp-servernpm installnpm start# -> http://127.0.0.1:3100/mcp

From npm, with no checkout (from 7.1.0, once published as @community-access/accessibility-agents-mcp; also listed in the MCP Registry as io.github.Community-Access/accessibility-agents):

npx -y @community-access/accessibility-agents-mcpclaude mcp add accessibility-agents -- npx -y @community-access/accessibility-agents-mcp

The npm package is the stdio bundle alone. The browser and PDF form tools need their optional packages in the same node_modules, so for those install the server into a folder with them and run it from there: npm install @community-access/accessibility-agents-mcp playwright @axe-core/playwright pdf-lib, npx playwright install chromium, then npx accessibility-agents-mcp.

For a PDF-only walkthrough, see PDF-QUICKSTART.md.

Prerequisite Matrix

Each class, with requirement, needed for and required.

Python is not required to run the MCP server or to install the package.

Local Vs Shared Server

You can run this MCP server either locally on your own machine or as a shared HTTP service.

For most users, start locally first. The default HTTP binding is 127.0.0.1, so it is not exposed to the network unless you deliberately change the host.

Configuration

Each environment variable, with its default and description.

Stateful vs Stateless

• Stateful (default): Sessions persist across requests (Mcp-Session-Id), and a GET request opens a server-sent event stream for that session. Best for interactive use. The 2026-07-28 MCP revision removes sessions and the GET endpoint; this mode follows the SDK.
• Stateless: Each request creates a fresh server instance. No sessions, POST only. Best for CI/CD and serverless deployments.

Client Configuration

Claude Desktop (claude_desktop_config.json)

Claude Desktop starts local servers from claude_desktop_config.json (Settings, Developer, Edit Config), using stdio:

{  "mcpServers": {    "a11y-agent-team": {      "command": "node",      "args": ["/path/to/mcp-server/dist/stdio.mjs"]    }  }}

Remote HTTP servers are added in Claude Desktop as custom connectors rather than in this file; see https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp.

Claude Code

The plugin registers the server for you. Without the plugin:

claude mcp add --transport stdio a11y-agent-team -- node /path/to/mcp-server/dist/stdio.mjs

VS Code (.vscode/mcp.json)

{  "servers": {    "a11y-agent-team": {      "type": "http",      "url": "http://127.0.0.1:3100/mcp"    }  }}

Using GLOW Bridge Tools

The GLOW bridge tools are part of this MCP server. You do not register a second MCP server for GLOW.

Default behavior

• The bridge targets https://letitglow.app/mcp by default.
• You can call glow_health_check immediately after starting this server.

Use a different GLOW endpoint

Option 1: set server environment variable before startup:

# Linux/macOSexport GLOW_API_BASE_URL="https://letitglow.app/mcp"npm start

# Windows PowerShell$env:GLOW_API_BASE_URL = "https://letitglow.app/mcp"npm start

Option 2: pass baseUrl per tool call (for one-off testing):

• glow_health_check with baseUrl
• glow_audit_document with baseUrl
• glow_fix_document with baseUrl
• glow_convert_document with baseUrl
• glow_generate_report with baseUrl

Example prompts after connection

• Run glow_health_check
• Audit ./docs/sample.md with glow_audit_document using format markdown
• Convert ./docs/sample.md from markdown to html with glow_convert_document
• Generate an html report for ./docs/sample.md with glow_generate_report

PDF-Only Quick Start

If your immediate goal is only PDF accessibility scanning, this is the smallest working path:

1. Install a Node.js LTS release (26, 24 or 22).
2. Open this folder: mcp-server/
3. Run npm install
4. Start the server with npm start
5. Point your MCP client at http://127.0.0.1:3100/mcp
6. Install the skills (see Getting started) if you want the guided PDF workflow in chat

Minimum files for the MCP side:

• package.json
• server.js
• server-core.js
• stdio.js
• tools/

If you also want the chat workflow layer, add:

• the pdf-accessibility and pdf-scan-config skills (skills/pdf-accessibility/, skills/pdf-scan-config/), installed with the rest of the package
• templates/pdf-config-moderate.json copied to your project as .a11y-pdf-config.json (optional)

Available Tools

Core Tools

Each tool, with its description.

Document Tools

Each tool, with its description.

GLOW Bridge Tools

Each tool, with its description.

Advanced Tools (Optional Dependencies)

Each tool, with its requires and description.

Markdown Tools

Each tool, with its description.

Caching Tools

Each tool, with its description.

Installing Optional Dependencies

# Playwright + axe-core (for web scanning)npm install playwright @axe-core/playwrightnpx playwright install chromium
# pdf-lib (for PDF form conversion)npm install pdf-lib
# veraPDF (external CLI)# Download from https://verapdf.org/software/

Actionable veraPDF Setup

veraPDF is optional. The built-in scan_pdf_document tool works without it. Install veraPDF when you need deeper PDF/UA validation than the built-in heuristic scan provides.

What veraPDF is for

• Validate PDF/UA conformance more deeply than the built-in scanner
• Confirm structure and metadata issues against a dedicated PDF validator
• Use as a second pass after baseline scanning

What veraPDF is not for

• It is not required for baseline PDF scanning
• It is not the primary remediation workflow in this repository
• Do not assume verapdf --fix is part of the supported workflow here

Install veraPDF

veraPDF requires Java 11 or later.

Windows

Install Java first if it is not already present:

winget install --exact --id EclipseAdoptium.Temurin.21.JRE

Then install veraPDF using Chocolatey if available:

choco install verapdf

If Chocolatey is not part of your environment, use the manual installer from https://docs.verapdf.org/install/.

macOS

brew install verapdf

Manual download

Download from https://docs.verapdf.org/install/ and make sure verapdf is available on your PATH.

Verify veraPDF

verapdf --version

On Windows, restart your terminal or editor after installing Java or veraPDF so the updated PATH is picked up.

Use veraPDF directly

verapdf --flavour ua1 --format text path/to/file.pdf

Use veraPDF through this MCP server

Once the server is running and veraPDF is installed on the same machine, an MCP client can call run_verapdf_scan.

Example natural-language requests:

• Run a deep PDF/UA scan on report.pdf using veraPDF
• Validate brochure.pdf with veraPDF and summarize the failures

The tool will return installation guidance if verapdf is not installed.

For more background, see veraPDF integration.

Health Check

curl http://127.0.0.1:3100/health# {"status":"ok","name":"a11y-agent-team","version":"7.1.0","mode":"stateful"}

MCP Prompts

Pre-built prompt templates that guide the model through accessibility workflows.

MCP Resources

Read-only data endpoints for accessibility reference material. The two with a {...} parameter are resource templates: a client lists or completes them and reads a concrete address such as a11y://guidelines/modal.

Security

• Path traversal prevention: File operations validate paths against home directory and CWD boundaries (CWE-22)
• Symlink resolution: Write operations resolve symlinks to prevent escape (CWE-59)
• SSRF protection: URL-based tools validate schemes (http/https only)
• Command injection prevention: External commands use execFile (not exec) with argument arrays
• File size limits: Documents capped at 100 MB, batch operations at 50 files
• Local binding: Server binds to 127.0.0.1 by default (not exposed to network)

Deployment

Docker

FROM node:24-slimWORKDIR /appCOPY package.json .RUN npm installCOPY . .EXPOSE 3100CMD ["node", "server.js"]

Systemd

[Unit]Description=A11y Agent Team MCP ServerAfter=network.target
[Service]Type=simpleExecStart=/usr/bin/node /opt/a11y-mcp/server.jsEnvironment=PORT=3100Restart=on-failure
[Install]WantedBy=multi-user.target

License

MIT. See LICENSE in the repository root.