Conexión MCP
Conecta un asistente de IA (Claude y otros) con la auditoría y la conversión de PDF accesibles. Un único endpoint, autenticado con tu clave de API.
¿Prefieres integrar desde tu propio código? Las mismas operaciones están en la API REST.
Conexión
El servidor implementa Model Context Protocol sobre HTTP («streamable HTTP»): un único endpoint que recibe mensajes JSON-RPC 2.0 por POST. Es sin estado: no emite Mcp-Session-Id y la credencial viaja en cada petición.
https://pdfaccesible.com/mcphttp (JSON-RPC 2.0, POST)2025-06-18, 2025-03-26, 2024-11-05toolsAlta en Claude Code
claude mcp add --transport http pdfaccesible https://pdfaccesible.com/mcp \
--header "Authorization: Bearer YOUR_API_KEY"
Alta en Claude Desktop u otros clientes
{
"mcpServers": {
"pdfaccesible": {
"type": "http",
"url": "https://pdfaccesible.com/mcp",
"headers": { "Authorization": "Bearer YOUR_API_KEY" }
}
}
}
Métodos JSON-RPC admitidos
| Método | Qué hace |
|---|---|
initialize | Negocia la versión del protocolo y devuelve capacidades, datos del servidor e instrucciones de uso. |
notifications/initialized | Notificación del cliente al terminar el arranque (responde 202 sin cuerpo). |
ping | Comprobación de vida. |
tools/list | Catálogo de herramientas con su esquema de entrada. |
tools/call | Ejecuta una herramienta (name + arguments). |
resources/list · prompts/list | Devuelven listas vacías: este servidor solo expone herramientas. |
Ejemplo con 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"}'
Cómo funciona
El procesado tarda de segundos a varios minutos, así que las herramientas no bloquean: primero encargas el trabajo y luego consultas o esperas el resultado.
- El asistente llama a
audit_document(informe, gratis) oconvert_document(genera el PDF/A accesible, consume cuota del plan), con el fichero o su URL. - La herramienta responde al instante con el
iddel documento; el servidor lo procesa en segundo plano. - Con ese id,
wait_for_documentespera a que termine (el sondeo lo hace el servidor) oget_document_statusconsulta el avance. - Al terminar,
get_document_reportdevuelve el informe ydownload_document, el PDF/A.
El id tiene la forma AAAAMMDD-HHMMSS-xxxxxx y es el mismo identificador que verás en tu área de cliente.
Autenticación
Requisito de plan: la API y el MCP están incluidos a partir del plan Business. Con un plan inferior no se pueden crear credenciales y las llamadas responden 403 plan_required. Ver planes.
Cada petición lleva tu clave de API en la cabecera Authorization: Bearer …; no hay sesión ni cookies. Créala en Mi cuenta → Credenciales de API; los detalles (cabeceras alternativas, buenas prácticas) están en la referencia de la API.
Authorization: Bearer pdfa_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Los límites de frecuencia, las cuotas del plan y la retención de los documentos son los mismos por MCP que por REST: los tienes en la referencia de la API.
Herramientas MCP
Estas son las 9 herramientas que devuelve tools/list, tal cual las publica el servidor.
El contrato de la API (herramientas, argumentos, campos de respuesta y códigos de error) está en inglés: lo consume una máquina. Esta tabla es la que publica el propio servidor en 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.
Equivalente REST: POST /api/v1/documents (type=audit) · POST /api/v1/documents/{id}/audit
| Argumento | Tipo | Obligatorio | Descripción |
|---|---|---|---|
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). |
Ejemplo de llamada
{
"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.
Equivalente REST: POST /api/v1/documents (type=conversion) · PUT /api/v1/documents/{id}/conversion
| Argumento | Tipo | Obligatorio | Descripción |
|---|---|---|---|
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). |
Ejemplo de llamada
{
"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.
Equivalente REST: GET /api/v1/documents/{id}
| Argumento | Tipo | Obligatorio | Descripción |
|---|---|---|---|
document_id |
string | sí | Document id returned when the document was submitted (format YYYYMMDD-HHMMSS-xxxxxx). |
Ejemplo de llamada
{
"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.
Equivalente REST: — (server-side polling; no REST equivalent)
| Argumento | Tipo | Obligatorio | Descripción |
|---|---|---|---|
document_id |
string | sí | Document id returned when the document was submitted (format YYYYMMDD-HHMMSS-xxxxxx). |
timeout_seconds |
integer por defecto: 60 |
no | Maximum time to wait, 5-240 seconds. |
Ejemplo de llamada
{
"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.
Equivalente REST: GET /api/v1/documents/{id}/report
| Argumento | Tipo | Obligatorio | Descripción |
|---|---|---|---|
document_id |
string | sí | Document id returned when the document was submitted (format YYYYMMDD-HHMMSS-xxxxxx). |
include_findings |
boolean por defecto: true |
no | false = scores and verdicts only, without the list of findings. |
max_findings |
integer por defecto: 15 |
no | Maximum findings per standard (0 = all). Keeps long reports from flooding the conversation; the response reports how many were omitted. |
Ejemplo de llamada
{
"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).
Equivalente REST: GET /api/v1/documents/{id}/file/{original|pdfa}
| Argumento | Tipo | Obligatorio | Descripción |
|---|---|---|---|
document_id |
string | sí | Document id returned when the document was submitted (format YYYYMMDD-HHMMSS-xxxxxx). |
file |
string (pdfa | original) por defecto: 'pdfa' |
no | Which of the two PDFs of the document. |
delivery |
string (link | base64) por defecto: 'link' |
no | link = authenticated URL (recommended); base64 = embedded content. |
Ejemplo de llamada
{
"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.
Equivalente REST: GET /api/v1/documents
| Argumento | Tipo | Obligatorio | Descripción |
|---|---|---|---|
page |
integer por defecto: 1 |
no | |
per_page |
integer por defecto: 20 |
no | |
type |
string (audit | conversion) | no | Optional filter. |
status |
string (queued | processing | done | error) | no | Optional filter. |
Ejemplo de llamada
{
"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.
Equivalente REST: DELETE /api/v1/documents/{id}
| Argumento | Tipo | Obligatorio | Descripción |
|---|---|---|---|
document_id |
string | sí | Document id returned when the document was submitted (format YYYYMMDD-HHMMSS-xxxxxx). |
Ejemplo de llamada
{
"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.
Equivalente REST: GET /api/v1/account
Sin argumentos.
Ejemplo de llamada
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "get_account",
"arguments": {}
}
}
Errores
Los errores de negocio (cuota agotada, id inexistente, PDF no válido) se devuelven como resultado de herramienta con isError: true y un JSON {"error":{"code":…,"message":…}}, para que el asistente pueda leerlos y corregir. Los errores de protocolo (credencial no válida, método desconocido, límite de frecuencia) llegan como error JSON-RPC.
La tabla completa de códigos (quota_exceeded, not_found…) está en la referencia de la API.