wcagc — accessibility scanning

wcagc-mcp

An MCP server that lets an AI assistant (Claude, ChatGPT, or any MCP-compatible client) run real, deterministic accessibility scans through wcagc — axe-core under the hood, not an LLM guess. Every scan result carries an explicit coverage disclaimer and never claims "compliant": automated testing finds only a portion of accessibility barriers, and this tool says so in every response.

This package is a thin, stateless adapter. It holds no database, no scan logic, and no secrets beyond the wcagc API base URL — it translates MCP tool calls into HTTP calls against the wcagc API and forwards the caller's own bearer. All authentication, entitlements, quotas, and scan orchestration live in the API; this code is safe to read end to end.

Two ways to run it

Local (stdio) — for Claude Desktop, Cursor, or any MCP client that spawns a local process:

npx @wcagc/mcp

Configure your MCP client with:

{
  "mcpServers": {
    "wcagc": {
      "command": "npx",
      "args": ["-y", "@wcagc/mcp"],
      "env": {
        "WCAGC_MCP_KEY": "<your mcp:scan API key>"
      }
    }
  }
}

Mint an mcp:scan key from your wcagc account under Settings → API keys — available on every plan, with a daily quota on Free/Starter and unlimited on Pro/Agency.

Hosted (Streamable HTTP + managed OAuth) — what Claude web/desktop/mobile connectors and ChatGPT use, since neither runs a local process for you. Add this remote MCP connector:

https://mcp.wcagc.com/mcp

The client discovers /.well-known/oauth-protected-resource/mcp, opens the wcagc login/consent flow, and binds the connection to one Organization. No key copy/paste is required. API-key bearer authentication remains supported for local stdio and CI.

ChatGPT availability depends on the ChatGPT plan and on whether the client permits action tools; scan_url creates a scan and is not a read-only operation. See wcagc.com/integrations/mcp.

Tools

Tool	Plan	What it does
scan_url	all	Scan any public URL, or a registered site for full tracking (Pro+).
check_pdf	all	Run a PDF/UA-1 structure check on a public PDF.
get_scan · get_findings	all	Read a scan_url scan's status, severity counts, and findings — either kind, recorded or one-off.
list_sites	Pro+	List the account's registered sites.
scan_site	Pro+	Crawl and scan every reachable page of a registered site.
get_run · get_run_findings	Pro+	Read a full-site run from scan_site.
get_root_causes	Pro+	Group a run's repeated DOM patterns and return factual element/page blast radius.
run_journey	Pro+	Replay a saved multi-step journey and check each step.
get_trends	Pro+	Read a site's violation-count history over time.

One id, one poll tool: whatever scan_url did with a URL, get_scan and get_findings read it back. get_run and get_run_findings are only for full-site runs from scan_site.

Every scan-producing tool returns the coverage disclaimer in both the text content and the structured content. There is no score, grade, or conformance verdict — automated testing finds roughly 30–57% of accessibility issues, and the remainder needs manual review.

Configuration

Env var	Used by	Meaning
WCAGC_API_BASE_URL	both	The wcagc API to call. Defaults to https://api.wcagc.com; set it only when self-hosting.
WCAGC_MCP_KEY	stdio	Your mcp:scan API key.
PORT	hosted	Port to listen on (default 8080).
WCAGC_MCP_ALLOWED_HOSTS	hosted	Comma-separated Host-header allowlist (DNS-rebinding protection when bound to 0.0.0.0).
WCAGC_MCP_INTROSPECT_TTL_SECONDS	hosted	How long a verified bearer is cached before re-checking with the API (default 60).
WCAGC_MCP_OAUTH_ISSUER	hosted	Expected OAuth issuer (defaults to WCAGC_API_BASE_URL).
WCAGC_MCP_OAUTH_JWKS_URL	hosted	Authorization Server public JWKS URL.
WCAGC_MCP_URL	hosted	Canonical RFC 9728 protected-resource URL (defaults to https://mcp.wcagc.com/mcp).
WCAGC_MCP_JWKS_TTL_SECONDS	hosted	JWKS cache TTL; an unknown kid triggers an immediate refetch.
WCAGC_OPENAI_APPS_CHALLENGE	hosted	OpenAI Plugins Directory domain-verification token; keep it in the deployment secret store, never in source.

Development

Hosted HTTP requests to /mcp and discovery endpoints produce JSON logs with a generated request ID, HTTP status, MCP method, error code and duration. Tokens, headers, query strings, tool arguments and results are excluded. Health probes are not logged.

The Docker entrypoint preloads the New Relic ESM agent. Set NEW_RELIC_AGENT_ENABLED=true, NEW_RELIC_APP_NAME=wcagc-mcp and the deployment secret NEW_RELIC_LICENSE_KEY to enable APM and forwarding of these safe request logs. The license key must belong to the existing New Relic account; never commit it. The stdio entrypoint does not load the agent.

npm install
npm run dev        # hosted, watch mode
npm run start:stdio # stdio mode
npm run typecheck
npm run verify      # node:test against a local fixture API

License

MIT — see LICENSE.