Connexió MCP

Connecta un assistent d'IA (Claude i altres) amb l'auditoria i la conversió de PDF accessibles. Un únic endpoint, autenticat amb la teva clau d'API.

Prefereixes integrar des del teu propi codi? Les mateixes operacions són a l'API REST.

Connexió

El servidor implementa Model Context Protocol sobre HTTP («streamable HTTP»): un únic endpoint que rep missatges JSON-RPC 2.0 per POST. És sense estat: no emet Mcp-Session-Id i la credencial viatja a cada petició.

Endpointhttps://pdfaccesible.com/mcp
Transporthttp (JSON-RPC 2.0, POST)
Versions de protocol2025-06-18, 2025-03-26, 2024-11-05
Capacitatstools

Alta a Claude Code

claude mcp add --transport http pdfaccesible https://pdfaccesible.com/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

Alta a Claude Desktop o altres clients

{
  "mcpServers": {
    "pdfaccesible": {
      "type": "http",
      "url": "https://pdfaccesible.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

Mètodes JSON-RPC admesos

MètodeQuè fa
initializeNegocia la versió del protocol i retorna capacitats, dades del servidor i instruccions d'ús.
notifications/initializedNotificació del client en acabar l'arrencada (respon 202 sense cos).
pingComprovació de vida.
tools/listCatàleg d'eines amb el seu esquema d'entrada.
tools/callExecuta una eina (name + arguments).
resources/list · prompts/listRetornen llistes buides: aquest servidor només exposa eines.

Exemple amb curl

curl -X POST https://pdfaccesible.com/mcp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Com funciona

El processament triga de segons a diversos minuts, així que les eines no bloquegen: primer encarregues la feina i després consultes o esperes el resultat.

  1. L'assistent crida audit_document (informe, gratis) o convert_document (genera el PDF/A accessible, consumeix quota del pla), amb el fitxer o la seva URL.
  2. L'eina respon a l'instant amb l'id del document; el servidor el processa en segon pla.
  3. Amb aquest id, wait_for_document espera que acabi (el sondeig el fa el servidor) o get_document_status consulta l'avenç.
  4. En acabar, get_document_report retorna l'informe i download_document, el PDF/A.

L'id té la forma AAAAMMDD-HHMMSS-xxxxxx i és el mateix identificador que veuràs a la teva àrea de client.

Autenticació

Requisit de pla: l'API i l'MCP estan inclosos a partir del pla Business. Amb un pla inferior no es poden crear credencials i les crides responen 403 plan_required. Veure els plans.

Cada petició porta la teva clau d'API a la capçalera Authorization: Bearer …; no hi ha sessió ni cookies. Crea-la a El meu compte → Credencials d'API; els detalls (capçaleres alternatives, bones pràctiques) són a la referència de l'API.

Authorization: Bearer pdfa_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Els límits de freqüència, les quotes del pla i la retenció dels documents són els mateixos per MCP que per REST: els tens a la referència de l'API.

Eines MCP

Aquestes són les 9 eines que retorna tools/list, tal com les publica el servidor.
El contracte de l'API (eines, arguments, camps de resposta i codis d'error) és en anglès: el consumeix una màquina. Aquesta taula és la que publica el mateix servidor a tools/list.

audit_document · Audit a PDF

Runs an accessibility AUDIT of a PDF against WCAG 2.1/2.2, PDF/UA (ISO 14289) and the European Accessibility Act (Directive (EU) 2019/882). Does not modify the document and does not consume conversion quota. Send a new file (file_base64 or file_url) or an existing document_id. Returns a document id immediately: the work runs in the BACKGROUND, so poll it with get_document_status or block with wait_for_document.

Equivalent REST: POST /api/v1/documents (type=audit) · POST /api/v1/documents/{id}/audit

ArgumentTipusObligatoriDescripció
file_base64 string no The PDF encoded in base64. Use this, "file_url" or "document_id" (exactly one).
file_url string no Public http(s) URL to download the PDF from. Alternative to "file_base64".
filename string no Original file name, e.g. "annual-report-2026.pdf". Optional but recommended.
document_id string no Process a document that is ALREADY in the account instead of uploading a new file (no need to send the bytes again).
Exemple de crida
{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "audit_document",
        "arguments": {
            "filename": "annual-report-2026.pdf",
            "file_base64": "JVBERi0xLjQK…"
        }
    }
}

convert_document · Convert a PDF to accessible PDF/A

CONVERTS a PDF into a tagged, accessible PDF/A (PDF/A-2b + PDF/UA-1: semantic structure, reading order, language, metadata and AI-generated alternative text for images). Consumes the plan quota. Send a new file (file_base64 or file_url) or an existing document_id; with document_id it is idempotent — if the document already has an accessible PDF/A, or a conversion is already running, no duplicate work is queued. Runs in the BACKGROUND: use wait_for_document and then download_document.

Equivalent REST: POST /api/v1/documents (type=conversion) · PUT /api/v1/documents/{id}/conversion

ArgumentTipusObligatoriDescripció
file_base64 string no The PDF encoded in base64. Use this, "file_url" or "document_id" (exactly one).
file_url string no Public http(s) URL to download the PDF from. Alternative to "file_base64".
filename string no Original file name, e.g. "annual-report-2026.pdf". Optional but recommended.
document_id string no Process a document that is ALREADY in the account instead of uploading a new file (no need to send the bytes again).
Exemple de crida
{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "convert_document",
        "arguments": {
            "filename": "annual-report-2026.pdf",
            "file_url": "https://pdfaccesible.com/samples/annual-report-2026.pdf"
        }
    }
}

get_document_status · Get processing status

Current state of a document: status (queued, processing, done, error), progress percentage, current step and, once finished, the accessibility score, the per-standard breakdown and the download links.

Equivalent REST: GET /api/v1/documents/{id}

ArgumentTipusObligatoriDescripció
document_id string Document id returned when the document was submitted (format YYYYMMDD-HHMMSS-xxxxxx).
Exemple de crida
{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "get_document_status",
        "arguments": {
            "document_id": "20260730-120501-a1b2c3"
        }
    }
}

wait_for_document · Wait until processing finishes

Waits (polling on the server) until the document finishes processing or the timeout elapses, then returns the final status. Saves calling get_document_status in a loop. An audit usually takes 10-60 s; an AI-assisted conversion, 1-5 min. On timeout it returns the current status with a warning instead of an error, so you can simply call it again.

Equivalent REST: — (server-side polling; no REST equivalent)

ArgumentTipusObligatoriDescripció
document_id string Document id returned when the document was submitted (format YYYYMMDD-HHMMSS-xxxxxx).
timeout_seconds integer
per defecte: 60
no Maximum time to wait, 5-240 seconds.
Exemple de crida
{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "wait_for_document",
        "arguments": {
            "document_id": "20260730-120501-a1b2c3",
            "timeout_seconds": 120
        }
    }
}

get_document_report · Get the accessibility report

Full report: overall score (the mean of WCAG, PDF/UA and EAA), score per standard and findings with severity and normative reference. If the document was converted, it also includes the result measured on the generated PDF/A and the score improvement.

Equivalent REST: GET /api/v1/documents/{id}/report

ArgumentTipusObligatoriDescripció
document_id string Document id returned when the document was submitted (format YYYYMMDD-HHMMSS-xxxxxx).
include_findings boolean
per defecte: true
no false = scores and verdicts only, without the list of findings.
max_findings integer
per defecte: 15
no Maximum findings per standard (0 = all). Keeps long reports from flooding the conversation; the response reports how many were omitted.
Exemple de crida
{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "get_document_report",
        "arguments": {
            "document_id": "20260730-120501-a1b2c3",
            "max_findings": 10
        }
    }
}

download_document · Download the PDF

Returns one of the two PDFs of the document: "pdfa" (the generated accessible version) or "original". By default it returns an authenticated download link; with delivery="base64" the file is embedded in the response (only advisable for small files).

Equivalent REST: GET /api/v1/documents/{id}/file/{original|pdfa}

ArgumentTipusObligatoriDescripció
document_id string Document id returned when the document was submitted (format YYYYMMDD-HHMMSS-xxxxxx).
file string (pdfa | original)
per defecte: 'pdfa'
no Which of the two PDFs of the document.
delivery string (link | base64)
per defecte: 'link'
no link = authenticated URL (recommended); base64 = embedded content.
Exemple de crida
{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "download_document",
        "arguments": {
            "document_id": "20260730-120501-a1b2c3",
            "file": "pdfa",
            "delivery": "link"
        }
    }
}

list_documents · List documents

Lists the documents of the account, newest first, with optional filters by type (audit / conversion) and status, and pagination.

Equivalent REST: GET /api/v1/documents

ArgumentTipusObligatoriDescripció
page integer
per defecte: 1
no
per_page integer
per defecte: 20
no
type string (audit | conversion) no Optional filter.
status string (queued | processing | done | error) no Optional filter.
Exemple de crida
{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "list_documents",
        "arguments": {
            "status": "done",
            "per_page": 10
        }
    }
}

delete_document · Delete a document

Permanently deletes a document from the account: the original PDF, the generated PDF/A and the report. Cannot be undone. Documents are deleted automatically after 30 days anyway.

Equivalent REST: DELETE /api/v1/documents/{id}

ArgumentTipusObligatoriDescripció
document_id string Document id returned when the document was submitted (format YYYYMMDD-HHMMSS-xxxxxx).
Exemple de crida
{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "delete_document",
        "arguments": {
            "document_id": "20260730-120501-a1b2c3"
        }
    }
}

get_account · Get plan, limits and usage

Subscribed plan, limits (maximum size per document, conversions per month, request rate) and usage for the current month, including how many free conversions are left. Worth checking before processing a batch of documents.

Equivalent REST: GET /api/v1/account

Sense arguments.

Exemple de crida
{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "get_account",
        "arguments": {}
    }
}

Errors

Els errors de negoci (quota exhaurida, id inexistent, PDF no vàlid) es retornen com a resultat d'eina amb isError: true i un JSON {"error":{"code":…,"message":…}}, perquè l'assistent pugui llegir-los i corregir. Els errors de protocol (credencial no vàlida, mètode desconegut, límit de freqüència) arriben com a error JSON-RPC.

La taula completa de codis (quota_exceeded, not_found…) és a la referència de l'API.