Integrations & automation

Beyond the web dashboard, TheAccessiblePDF can be driven from AI agents, your CI pipeline, and your own storage buckets — so accessibility work happens automatically instead of by hand. This page covers four ways to automate it.

Every integration authenticates with an API key. Generate one at Settings → API Keys → Create Key on pdf.theaccessible.org. Copy it immediately — it is only shown once.

Claude Desktop skill

The TheAccessiblePDF skill plugs directly into Claude Desktop so you can scan a website, walk through the items that need human review, fix what's broken, and produce a defensible Accessibility Conformance Report (ACR / VPAT 2.5) — all from a single chat conversation.

What you can do

• Scan any URL for WCAG 2.1 AA violations, including pages behind a login (Claude can pass cookies or session tokens you provide).
• Walk through human-review items one at a time, with Claude pre-grading each one and explaining its reasoning so you just confirm or override.
• Get fix instructions tailored to your platform — WordPress, Squarespace, Webflow, Wix, Shopify, Instructure Canvas, Drupal, Ghost, and others. Claude tells you which menu to click in your CMS, not a wall of HTML.
• Re-scan after you fix to confirm the issue is resolved.
• Generate a signed ACR with your name, role, organization, and date stamped on the document — ready to hand to legal, procurement, or an accessibility auditor.

Prerequisites

• Claude Desktop (Mac or Windows). Note: the Chrome PWA shim of Claude is not the same app and won't load extensions.
• An API key (see above).
• A Claude.ai account — the skill itself is free, but Claude Desktop needs an account.

Install

1. Download the skill bundle (a .dxt file) from your account.
2. Quit Claude Desktop completely (Cmd+Q on Mac, not just close the window).
3. Open the .dxt file — double-click it, or drag it onto the Claude Desktop icon. Claude shows an install dialog.
4. Paste your API key when prompted. Claude stores it securely in your operating system keychain — it never appears in plain text.
5. Reopen Claude Desktop.
6. Verify it loaded — Settings → Extensions should show the audit skill with no error icon. In a new chat, the tools icon in the composer should list the url.*, acr.*, and pdf.* tools.

Your first scan

In a new chat, describe what you want, for example: "Scan https://example.com for accessibility issues." Claude starts the scan, polls until it finishes (10–30 seconds for most pages), and summarizes the violations, the WCAG 2.1 AA score, and the platform it detected. It then offers to walk you through the criteria that require manual review.

Human verification

When you ask Claude to walk through verification, it presents items one at a time with a pre-graded suggestion (e.g. "My suggestion: Supports — confidence 88%") and its reasoning. You answer in plain language — "yes," "no, mark it Does Not Support," "make it Partial," etc. Claude records each decision individually with a timestamp, your verdict, its suggestion, and any note. It never batch-approves all items — that would defeat the audit trail.

Platform-specific fixes

When the scan detects your platform with reasonable confidence, Claude tailors the fix steps to your editor (the WordPress block editor, the Squarespace design panel, the Canvas Rich Content Editor, the Webflow element settings, and so on). If your site is hand-coded HTML, Claude can apply the fix to a working copy and hand you a diff to deploy. After you publish, say "rescan" to verify.

Generate your ACR

Once the verification queue is empty, ask Claude to generate the report. Claude returns the prefilled sign-off (your name and organization from your account, today's date), asks you to confirm or edit it, and then produces downloadable HTML and PDF versions of your ACR. Download links are valid for 10 minutes. The report includes a per-criterion table with audit-trail badges showing which decisions were AI-auto, AI-suggested + human-confirmed, or human-only.

Scanning sites behind a login

For TheAccessible.org's own apps, the skill forwards your existing session automatically. For other protected sites, tell Claude — it asks for the cookies or headers your browser sends (from DevTools → Application → Cookies) and passes them to the scanner. Cookies are used only for that one scan and are not stored. Single sign-on and multi-factor auth may not work with the cookie approach.

Troubleshooting

• "Server disconnected" right after install — almost always a stale npx cache. In a terminal run rm -rf ~/.npm/_npx, then quit and reopen Claude Desktop.
• No tool icon in the chat — make sure you're running the real Claude Desktop, not the Chrome PWA shim, which can't load extensions.
• The first verification call is slow — expected. The AI pre-grader runs through 10–20 criteria in parallel (5–10 seconds). Subsequent calls are instant.
• The scan returned the login page instead of your dashboard — the cookies you provided didn't authenticate. Re-copy the exact cookie names and values; some sites split session data across multiple cookies.

MCP server

The Model Context Protocol (MCP) is an open standard that lets AI agents call external tools in a structured, auditable way. Our hosted MCP server exposes the full toolset — PDF remediation, URL auditing, page-level fixes, and ACR scorecards — over a single secure endpoint. Point your agent at it once, and your team can fix accessibility problems by asking, not by hand-clicking.

What your agent can do

Tool	What it does
pdf-remediate	Convert a PDF into a tagged, WCAG-conformant accessible PDF + HTML report.
url-crawler	Crawl a page (or site) and return a structured accessibility audit.
url-remediate	Apply targeted fixes to an HTML page — alt text, ARIA, heading order, etc.
acr	Produce a vendor-grade ACR / VPAT 2.5 scorecard against WCAG 2.1 AA.

Each tool returns structured JSON and publishes its input/output schema, so your client auto-discovers them on connect.

Supported clients

Claude Desktop, Claude Code, Cursor, Windsurf, VS Code (Copilot Chat), and any other MCP-compatible host.

Connect in 60 seconds

Drop the snippet below into your client's MCP configuration, replacing <YOUR_API_KEY> with your key.

{
  "mcpServers": {
    "accessible": {
      "url": "https://api.theaccessible.org/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_API_KEY>"
      }
    }
  }
}

For Claude Desktop, paste this into claude_desktop_config.json (under ~/Library/Application Support/Claude/ on macOS), then quit and reopen. For Cursor and Windsurf, add the same JSON under MCP Servers in settings, pointing at https://api.theaccessible.org/mcp.

Try it

Open a new chat and ask: "Scan https://example.com for accessibility issues and tell me the top three things to fix." The agent picks url-crawler automatically and answers in plain language. Follow-ups like "Generate an ACR for that scan" or "Fix the alt-text issues and give me the updated HTML" trigger the acr and url-remediate tools.

Authentication and rate limits

• The API key in the Authorization: Bearer header is all the server needs to identify your account.
• Tool calls charge against your normal credit balance — there is no separate MCP pricing.
• Heavy operations (full-site crawls, PDF remediation) run asynchronously. The tool returns a job ID and the agent polls until it completes. Most jobs finish in 10–60 seconds.

Troubleshooting

• "MCP server failed to start" — almost always a wrong or unreachable URL. Confirm https://api.theaccessible.org/mcp resolves and that the Authorization header is present.
• Empty tools list — check that the API key is valid and hasn't been rotated or revoked.
• A tool call fails with 429 — you hit a rate limit. Wait 60 seconds and retry, or contact support to raise your limits.

CI/CD integration

Plug the audit engine straight into your CI pipeline. When a developer opens a pull request, we crawl the changed pages against WCAG 2.1 AA, post a summary comment, and gate the merge based on the severity thresholds you set. No new dashboards, no separate accounts — the check passes or it fails, just like your linter.

What you get on every PR

• Pull request audits — every PR runs a full WCAG 2.1 AA scan of the changed pages.
• Blocking failures — configure severity thresholds. New critical violations fail the check and block the merge.
• Existing-debt separation — legacy issues are tracked separately so they don't stall delivery while you work them down.
• Trend tracking — every build is scored against your ACR baseline.

Supported platforms

GitHub Actions (officially supported action), plus GitLab CI, CircleCI, Jenkins, and any CI system that can run a shell command (via the CLI runner).

Prerequisites

• An API key (see above).
• A staging or preview URL your CI can reach. The action audits a live URL, so your pipeline needs to deploy the change somewhere reachable before the audit step runs.

GitHub Actions setup

Drop this workflow into .github/workflows/accessibility.yml:

name: Accessibility Audit
on: [pull_request]

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: theaccessible-org/audit-action@v1
        with:
          api-key: ${{ secrets.ACCESSIBLE_API_KEY }}
          target: https://staging.example.com
          fail-on: critical

Then add a repository secret named ACCESSIBLE_API_KEY (Settings → Secrets and variables → Actions) with your API key, commit the workflow file, and open your next pull request. The audit runs automatically and posts a summary comment.

Workflow inputs

Input	Required	Default	Description
api-key	yes	—	Your API key (use a GitHub secret).
target	yes	—	The URL to audit. Often a per-PR preview URL from your deploy step.
fail-on	no	critical	Severity threshold: critical, serious, moderate, minor, or any.
wcag-level	no	AA	WCAG conformance level: A or AA.
comment	no	true	Whether to post a results comment back to the PR.

The check turns red if any violation at or above your fail-on threshold appears in the new column. Pre-existing violations are reported but never fail the check.

GitLab / CircleCI / Jenkins

Use the CLI directly — it works the same way the GitHub Action does internally.

accessibility-audit:
  image: node:20
  script:
    - npx @theaccessible-org/audit-cli@latest \
        --target https://staging.example.com \
        --fail-on critical
  variables:
    ACCESSIBLE_API_KEY: $ACCESSIBLE_API_KEY

The CLI exits non-zero on failure, posts a comment via your provider's PR API if a token is available, and prints a summary table to stdout.

Scanning multiple pages

Pass a comma-separated list to target:

target: https://staging.example.com,https://staging.example.com/pricing,https://staging.example.com/contact

Choosing a threshold

Start new repositories at fail-on: critical — that blocks merges introducing litigation-grade issues without stalling on minor stylistic problems. After a few weeks, tighten to fail-on: serious. Save fail-on: any for repositories where accessibility is the whole point.

Troubleshooting

• The check is green but you expected red — the action only fails on new violations introduced by the PR. Pre-existing violations are reported but don't fail the check.

• The action times out — the default timeout is 5 minutes. Raise it with timeout: 10m, or add a wait step if your preview URL is slow to come online.

• The PR comment is missing — the action needs pull-requests: write permission:

  permissions:
    contents: read
    pull-requests: write

Shared folder (S3)

Connect your own object-storage bucket (Amazon S3, Cloudflare R2, Backblaze B2, or any S3-compatible service) and every PDF you drop into the input prefix is automatically remediated and written back to your bucket under the output prefix — no copy-paste, no manual uploads. The original is left untouched, and each integration is isolated to the prefix you point us at.

This is the right fit if you're publishing accessibility-compliant PDFs at volume (course materials, regulatory filings, public-records portals) and don't want to run files through the web dashboard one by one. Detection runs either by polling every couple of minutes or, on supported providers, by event notification within seconds. S3 integrations themselves are free — you only pay the per-page conversion credits when a file is remediated.

For the full walkthrough — provider-by-provider setup, IAM policies, event-mode configuration, limits, and troubleshooting — see S3 bucket integrations.