Documentación

MCP para IAs

Conecta Claude u otro asistente compatible con MCP a tu cuenta de Contratos y pídele en lenguaje natural que prepare, envíe y siga tus documentos.

1. Qué es y qué puede hacer

MCP (Model Context Protocol) es el estándar con el que los asistentes de IA usan herramientas externas. El servidor MCP de Contratos es un pequeño programa que se ejecuta en tu equipo y traduce lo que pides al asistente en llamadas a la API de Contratos.

Con él, tu asistente puede:

Enviar a firmar un PDF de tu equipo o un documento creado desde una plantilla.
Decirte en qué estado está cada documento, quién ha firmado y quién ha abierto el enlace.
Reenviar una invitación o corregir el email de un firmante.
Consultar tus firmas disponibles y tus facturas.

2. Antes de empezar

Activa el acceso para IAs en Configuración → Integraciones → Acceso para IAs. Lo tiene que hacer un administrador de la organización. Mientras esté apagado, el MCP no funciona aunque la clave sea válida (la API normal sí).
Crea una clave API en Configuración → Integraciones → Claves API. Te recomendamos una clave solo para el MCP, con un nombre que la identifique, para poder revocarla sin afectar a otras integraciones.
Instala Node.js 22 o superior en el equipo donde uses el asistente (nodejs.org).

3. Instalación

Descarga el servidor y guárdalo en una carpeta propia, por ejemplo C:\contratos-mcp en Windows o ~/contratos-mcp en macOS y Linux.

Descargar contratos-mcp.mjs

Abre una terminal en esa carpeta e instala sus dos dependencias:

bash

npm install @modelcontextprotocol/sdk zod

4. Conectarlo a tu asistente

El servidor necesita dos variables: la dirección de Contratos y tu clave API.

Claude Desktop

En Claude Desktop, abre Ajustes → Desarrollador → Editar configuración y añade el servidor al archivo claude_desktop_config.json, cambiando la ruta y la clave por las tuyas. Después reinicia Claude Desktop.

json

{
  "mcpServers": {
    "contratos": {
      "command": "node",
      "args": ["C:/contratos-mcp/contratos-mcp.mjs"],
      "env": {
        "CONTRATOS_BASE_URL": "https://contratos.compensador.es",
        "CONTRATOS_API_KEY": "fo_xxx"
      }
    }
  }
}

Claude Code

bash

claude mcp add contratos \
  -e CONTRATOS_BASE_URL=https://contratos.compensador.es \
  -e CONTRATOS_API_KEY=fo_xxx \
  -- node ~/contratos-mcp/contratos-mcp.mjs

Otros asistentes

Cualquier cliente compatible con MCP por stdio sirve: el comando es node con la ruta del archivo como argumento, y las variables CONTRATOS_BASE_URL y CONTRATOS_API_KEY en su entorno.

Cuando publiquemos una versión nueva del servidor, vuelve a descargarlo y reinicia el asistente para que vea las herramientas nuevas.

5. Ejemplos de uso

No hace falta conocer las herramientas: pídeselo al asistente con tus palabras.

«Envía a firmar C:\contratos\alquiler.pdf a Ana López (ana@example.com) y después a Luis Martín (luis@example.com), en ese orden.»
«Crea un documento con la plantilla de reclamación de vuelo para María Pérez, DNI 12345678Z, vuelo IB1234. Hazlo en modo prueba.»
«¿Qué documentos siguen pendientes de firma desde la semana pasada? ¿Alguien ha abierto el enlace?»
«El email de Luis estaba mal, es luis.martin@example.com. Corrígelo y reenvíale la invitación.»
«Permite que la firma se muestre en un iframe de https://portal.miempresa.com.»
«¿Cuántas firmas me quedan este mes?»
«¿Cuántos documentos se firmaron el mes pasado y cuánto se tardó en firmarlos? Compáralo con el mes anterior.»
«Dame el enlace para exportar las facturas del primer trimestre en CSV.»

El asistente te pedirá confirmación antes de usar cada herramienta, según cómo lo tengas configurado. Para probar sin gastar firmas, pídele que cree los documentos en modo prueba o activa el modo prueba de tu organización.

6. Herramientas

Cuenta	Qué hace
`get_account`	Plan, firmas disponibles, modo prueba y qué permite tu plan por API.
`set_qr_logo`	Sube el logo del centro del QR desde un archivo de tu equipo (PNG/JPG, máx. 300 KB).
`remove_qr_logo`	Quita el logo del QR.
`set_embed_origins`	Define las webs que pueden mostrar la firma en un iframe (firma en persona).

Plantillas	Qué hace
`list_templates`	Lista tus plantillas con los datos que pide cada una.
`get_template`	Detalle de una plantilla: campos, tipos y valores por defecto; con includeContent, también su HTML, CSS y schema.
`create_template`	Crea una plantilla con su HTML, CSS y schema de datos.
`update_template`	Cambia una plantilla (solo lo indicado) o la archiva y reactiva.
`export_template`	Exporta una plantilla a un .json de tu equipo para llevarla a otra cuenta.
`import_template`	Importa una plantilla desde un .json exportado; siempre crea una nueva.

Documentos	Qué hace
`create_envelope_from_pdf`	Crea un documento subiendo un PDF de tu equipo, con firmantes, posición de las firmas y, si quieres, externalRef, metadata e idempotencyKey (para reintentar sin duplicar).
`create_envelope_from_template`	Crea un documento desde una plantilla rellenando sus datos, con externalRef, metadata e idempotencyKey opcionales.
`list_envelopes`	Lista documentos, con filtro por estado y paginación.
`get_envelope`	Detalle de un documento: firmantes, auditoría y accesos al enlace de firma.
`resend_envelope`	Reenvía la invitación al firmante pendiente, corrigiendo su email si hace falta.
`cancel_envelope`	Cancela un documento, con un motivo opcional que queda en la auditoría y llega en el webhook envelope.voided.
`get_download_urls`	Rutas para descargar el PDF y el certificado.

Informes	Qué hace
`get_report`	Informe de documentos de un periodo: enviados, firmados, tasa de firma, tiempo hasta la firma y firmas gastadas, comparado con el periodo anterior.

Facturas	Qué hace
`list_invoices`	Lista tus facturas de Contratos con importes y estado.
`get_invoice_download_urls`	Rutas del PDF y del XML Facturae de una factura.
`get_invoice_export_url`	Ruta de exportación de un periodo (ZIP o CSV contable).

Las descargas (PDF, certificado, facturas) se devuelven como rutas de la API: para abrirlas hay que llamar con la clave API, así que el asistente te dará la ruta, no el archivo.

7. Seguridad

La clave API se queda en la configuración de tu equipo. No la compartas ni la subas a repositorios.
El servidor solo lee los archivos que le indicas: PDF para crear documentos y PNG/JPG para el logo del QR.
Todo lo que hace queda limitado a tu organización y registrado en la auditoría de cada documento, igual que por la API.
Puedes cortar el acceso en cualquier momento desactivando el acceso para IAs o revocando la clave.