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ó.
https://pdfaccesible.com/mcphttp (JSON-RPC 2.0, POST)2025-06-18, 2025-03-26, 2024-11-05toolsAlta 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ètode | Què fa |
|---|---|
initialize | Negocia la versió del protocol i retorna capacitats, dades del servidor i instruccions d'ús. |
notifications/initialized | Notificació del client en acabar l'arrencada (respon 202 sense cos). |
ping | Comprovació de vida. |
tools/list | Catàleg d'eines amb el seu esquema d'entrada. |
tools/call | Executa una eina (name + arguments). |
resources/list · prompts/list | Retornen 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.
- L'assistent crida
audit_document(informe, gratis) oconvert_document(genera el PDF/A accessible, consumeix quota del pla), amb el fitxer o la seva URL. - L'eina respon a l'instant amb l'
iddel document; el servidor el processa en segon pla. - Amb aquest id,
wait_for_documentespera que acabi (el sondeig el fa el servidor) oget_document_statusconsulta l'avenç. - En acabar,
get_document_reportretorna l'informe idownload_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
| Argument | Tipus | Obligatori | Descripció |
|---|---|---|---|
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
| Argument | Tipus | Obligatori | Descripció |
|---|---|---|---|
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}
| Argument | Tipus | Obligatori | Descripció |
|---|---|---|---|
document_id |
string | sí | 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)
| Argument | Tipus | Obligatori | Descripció |
|---|---|---|---|
document_id |
string | sí | 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
| Argument | Tipus | Obligatori | Descripció |
|---|---|---|---|
document_id |
string | sí | 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}
| Argument | Tipus | Obligatori | Descripció |
|---|---|---|---|
document_id |
string | sí | 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
| Argument | Tipus | Obligatori | Descripció |
|---|---|---|---|
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}
| Argument | Tipus | Obligatori | Descripció |
|---|---|---|---|
document_id |
string | sí | 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.