Wcagc MCP README

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:

Terminal

npx @wcagc/mcp

Configure your MCP client with:

config.json

{
  "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:

Code

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.

Terminal

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.