MCP server and Custom GPT setup

This page describes the two transports we expose for the accessible-document toolchain — a Custom GPT Action (OpenAPI) and a real MCP HTTP server — and how to wire each one up.

Both transports delegate to the same tool registry (workers/api/src/mcp/registry.ts). Adding a new capability means dropping a new module into workers/api/src/mcp/tools/ and registering its operations. Neither transport needs to change.

Tools available today (21 total)

PDF tools

Tool name	Purpose
pdf_convert	Start conversion of a PDF into accessible HTML + accessible PDF + PDF/UA-1 conformance report. Source can be a public URL (fileUrl) or base64-encoded bytes (fileBytes).
pdf_status	Poll progress (HTML + PDF + conformance readiness).
pdf_result	Fetch all deliverables (HTML inline preview, signed download URLs, inline conformance summary).
pdf_conformance	Standalone PDF/UA-1 conformance report. Useful for ACR / VPAT flows.
pdf_getHtml	Fetch the full accessible HTML (no truncation). Use before pdf_editHtml to locate the exact text to edit.
pdf_editHtml	Apply find/replace edits to the HTML and automatically regenerate the accessible PDF + conformance report. Preferred remediation path for alt text, heading levels, decorative-image marking, table headers, language, link text, etc.

URL scanning tools

Tool name	Purpose
url_scan	Start a multi-variant axe-core + WCAG scan of a live URL (desktop, optional dark, mobile). Supports multi-page crawl via crawl block. Returns a jobId.
url_status	Poll scan progress. For crawl parents, returns aggregate page counts.
url_result	Full scan result: violations by variant, VPAT criteria + score, CMS/platform hint. For crawl parents, returns per-page summary + aggregate.
url_conformance	VPAT conformance slice only (criteria, summary, score) + platform hint.
url_getHtml	Fetch the rendered HTML for one variant (desktop / dark / mobile).
url_editHtml	Apply find/replace edits to the captured HTML; persists remediated copy.
url_rescan	Re-enqueue the same URL after a fix is deployed.
url_getScreenshot	Full-page JPEG screenshot of a scan variant (inline image on MCP; base64 JSON on OpenAPI).
url_altTextBatch	Bulk alt-text review: classifies every <img>, attaches AI suggestions, returns CMS-specific fix guidance.

ACR / VPAT generation tools

Tool name	Purpose
acr_queue	Return WCAG criteria needing human review, with AI pre-grades (verdict + confidence + reasoning).
acr_decide	Record one verdict (supports / partial / does-not / na) on a criterion.
acr_state	Overall progress: total, auto-decided, human-decided, remaining queue.
acr_generate	Two-call protocol: collect signoff details, then compose + download signed ACR HTML + PDF.
acr_altTextReport	Two-call protocol: same as acr_generate but produces the alt-text remediation report instead of the full ACR.
acr_getScreenshot	Cropped per-element screenshot for a WCAG criterion in the ACR queue (inline image on MCP; base64 JSON on OpenAPI).

Custom GPT (OpenAPI Action)

Canonical endpoint base: https://api.theaccessible.org/api/gpt

Legacy endpoint https://api-pdf.theaccessible.org/api/gpt continues to work for existing PDF-only GPT installs and will not be removed. The canonical spec is now at api.theaccessible.org.

Authentication: X-API-Key: <your key> (issue from the dashboard → Settings → API keys).

Set up:

1. Open https://chat.openai.com/gpts/editor, create a new GPT.
2. Configure → Actions → “Import from URL” → https://pdf.theaccessible.org/openapi.yaml (also reachable at /.well-known/openapi.yaml). Source of truth: workers/api/src/openapi/spec.ts.
3. Authentication → API Key → Custom header X-API-Key.
4. See docs/CUSTOM-GPT-PUBLICATION.md for the full system prompt covering all 21 tools.

PDF route paths

Operation	Method	Path
pdf_convert	POST	/convert
pdf_status	GET	/status/{fileId}
pdf_result	GET	/result/{fileId}
pdf_conformance	GET	/conformance/{fileId}
pdf_getHtml	GET	/pdf/html/{fileId} (also /html/{fileId} for compat)
pdf_editHtml	POST	/pdf/html/{fileId}/edit (also /html/{fileId}/edit for compat)

URL route paths

Operation	Method	Path
url_scan	POST	/url/scan
url_status	GET	/url/status/{jobId}
url_result	GET	/url/result/{jobId}
url_conformance	GET	/url/conformance/{jobId}
url_getHtml	GET	/url/html/{jobId}/{variant}
url_editHtml	POST	/url/html/{jobId}/{variant}/edit
url_rescan	POST	/url/rescan/{jobId}
url_getScreenshot	GET	/url/screenshot/{jobId}/{variant}
url_altTextBatch	POST	/url/altText/{jobId}

ACR route paths

Operation	Method	Path
acr_queue	GET	/acr/queue/{jobId}
acr_decide	POST	/acr/decide
acr_state	GET	/acr/state/{jobId}
acr_generate	POST	/acr/generate
acr_altTextReport	POST	/acr/altTextReport
acr_getScreenshot	GET	/acr/screenshot/{jobId}/{criterionId}

Screenshot endpoints note

url_getScreenshot and acr_getScreenshot return the image as base64-encoded JPEG bytes in the data field of the JSON response. On the MCP transport these are additionally returned as inline MCP image content. Custom GPT Actions receive the JSON with embedded base64 — this is adequate for ChatGPT to render images inline.

MCP HTTP server

Endpoint: https://api.theaccessible.org/api/mcp (also accepts POST to /api/mcp/rpc).

Transport: streamable-HTTP, JSON-RPC 2.0 over POST. Methods supported: initialize, tools/list, tools/call, ping.

Auth: Authorization: Bearer <api-key>. Use the same API-key value issued for the OpenAPI route.

Discovery: GET /.well-known/oauth-protected-resource returns the resource-server metadata (no auth required).

Connecting from Claude Desktop

{
  "mcpServers": {
    "theaccessible": {
      "url": "https://api.theaccessible.org/api/mcp",
      "transport": "http",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY_HERE"
      }
    }
  }
}

Quick test

curl -s https://api.theaccessible.org/api/mcp \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | jq

Legacy api-pdf.theaccessible.org endpoints

api-pdf.theaccessible.org/api/mcp and /api/gpt/* continue to work. Any existing DXT installs or GPT installs pointing at the old host keep working indefinitely. The canonical host for new installs is api.theaccessible.org.

Sending file bytes directly

For clients that have the PDF in-hand and don’t want to expose it via a public URL, pdf_convert accepts a base64-encoded fileBytes argument in place of fileUrl. Provide exactly one of the two; supplying both or neither is a 400.

// Native MCP via tools/call
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "pdf_convert",
    "arguments": {
      "fileName": "report.pdf",
      "fileBytes": "JVBERi0xLjcKJ..."
    }
  }
}

Adding future tools

Add a file workers/api/src/mcp/tools/new-tool.ts that:

1. Defines its zod input schemas.
2. Registers operations on the shared registry.
3. Imports it from mcp/bootstrap.ts.

Then add corresponding routes to mcp/transports/openapi-routes.ts and update workers/api/src/openapi/spec.ts. The MCP transport picks the tool up automatically via tools/list.