Servidor MCP

uninvoice.app incluye un servidor Model Context Protocol (MCP) para que los agentes de IA y las herramientas compatibles con MCP puedan leer los datos de tu empresa, crear facturas y gastos, y generar informes de negocio directamente. Expone las mismas operaciones que la API HTTP, autenticadas de la misma forma, pero modeladas como recursos y herramientas MCP.

info

El servidor MCP es un proceso distinto de la API HTTP. Habla MCP sobre el transporte streamable-HTTP: tu cliente MCP se conecta a un único endpoint HTTP, expuesto en su propia URL de endpoint MCP.

Autenticación

Toda petición MCP debe incluir un token Bearer en la cabecera Authorization: los mismos tokens que acepta la API HTTP. El token se valida en cada operación, incluidas la de listar recursos y herramientas. Una cabecera ausente o mal formada, o un token inválido o revocado, se rechaza.

El token determina el usuario y la empresa que actúan; cada recurso que lees y cada factura que creas quedan limitados a esa empresa.

El MCP siempre pasa por la Auditoría IA

El servidor MCP se trata siempre como una IA. Sus herramientas de escritura nunca se ejecutan directamente: cada una registra una entrada pendiente de Auditoría IA que una persona debe aprobar antes de que surta efecto. A diferencia de un token de API, el servidor MCP no puede presentar la cabecera X-Human-Proof para salir de la barrera; no hay forma de que una escritura por MCP omita la cola de revisión.

Configura tu cliente MCP con la URL del endpoint y la cabecera, por ejemplo:

{
  "mcpServers": {
    "uninvoice": {
      "url": "https://<tu-endpoint-mcp>",
      "headers": { "Authorization": "Bearer <token-de-api>" }
    }
  }
}

Recursos

Los recursos son vistas de solo lectura de tus datos bajo el esquema de URI uninvoice://. Devuelven application/json.

URI	Descripción
uninvoice://company	La configuración de tu empresa.
uninvoice://entities	Todas las entidades (clientes / proveedores).
uninvoice://entities/{id}	Una entidad concreta por ID.
uninvoice://entities/{id}/invoices	Las facturas emitidas a una entidad destinataria.
uninvoice://entities/{id}/expenses	Los gastos (facturas recibidas) de una entidad proveedora.
uninvoice://invoices	Todas las facturas (cada una con su lineCount).
uninvoice://invoices/{id}	Una factura concreta con sus líneas.
uninvoice://proformas	Todas las proformas (cada una con su lineCount).
uninvoice://proformas/{id}	Una proforma concreta con sus líneas.
uninvoice://expenses	Todos los gastos (facturas recibidas de proveedores).
uninvoice://expenses/{id}	Un gasto concreto con sus líneas.
uninvoice://reports	Todos los informes de negocio generados (estado / metadatos).
uninvoice://reports/{id}	Un informe generado concreto por su ID.

Las variantes .../{id} (y las subcolecciones entities/{id}/…) se anuncian como plantillas de recurso; las variantes de colección de nivel superior se listan como recursos simples.

Herramientas

create_invoice

Crea una nueva factura en borrador para un destinatario, con líneas. Los impuestos se calculan automáticamente a partir de la empresa y del destinatario. Refleja POST /v1/invoices; la factura resultante es un borrador hasta que la emites a través de la API HTTP.

Esquema de entrada:

Campo	Tipo	Obligatorio	Descripción
recipient_id	string	sí	ID de la entidad destinataria.
supply_type	"services" | "goods"	sí	Si la factura cubre servicios o bienes.
lines	array	sí	Líneas (ver abajo).

Cada elemento de lines:

Campo	Tipo	Obligatorio	Descripción
concept	string	sí	Descripción del servicio o producto.
quantity	number	no	Número de unidades (se permiten decimales, p. ej. 95.6).
quantity_unit	string	no	Etiqueta de unidad (p. ej. horas, días).
unit_price	integer	no	Precio por unidad, en céntimos.
unit_unit	string	no	Etiqueta de unidad monetaria.
is_tax	boolean	no	Si es una línea de impuesto explícita.
tax_amount	integer	no	Importe del impuesto en céntimos.
subtotal	integer	no	Subtotal de la línea en céntimos.

Las líneas aparecen en la factura en el orden en que las envías.

Argumentos de ejemplo:

{
  "recipient_id": "ent_...",
  "supply_type": "services",
  "lines": [
    { "concept": "Consultoría (junio 2026)", "quantity": 10, "quantity_unit": "horas", "unit_price": 20000 }
  ]
}

Como el servidor MCP siempre pasa por la barrera, esta herramienta no crea la factura al momento. Registra una entrada pendiente de Auditoría IA y devuelve un mensaje con el id de la entrada; el borrador se crea solo cuando una persona lo aprueba.

La emisión se hace a través de la API HTTP

La herramienta MCP solo crea borradores. Para asignar el número de factura y (para emisores en España) remitirla a la AEAT, emítela con POST /v1/invoices/{id}/issue. Se aplica el mismo requisito de autorización Veri*Factu: los errores de negocio, incluido el del apoderamiento, se transmiten al llamante MCP con su mensaje accionable.

create_expense

Registra un gasto (una factura recibida de un proveedor) con líneas. Refleja POST /v1/expenses.

Esquema de entrada:

Campo	Tipo	Obligatorio	Descripción
supplier_id	string	sí	ID de la entidad proveedora de la que se recibió la factura.
invoice_reference	string	sí	La referencia/número de la factura del proveedor (no vacía, única por proveedor).
lines	array	sí	Líneas (ver abajo).
expense_date	string (RFC 3339)	no	Cuándo se incurrió en el gasto.
currency_code	string	no	Código de moneda ISO. Por defecto, la moneda del proveedor.
category	string	no	Categoría del gasto.
description	string	no	Nota libre sobre el gasto.

Cada elemento de lines:

Campo	Tipo	Obligatorio	Descripción
concept	string	sí	Descripción de la línea.
subtotal	integer	sí	Subtotal de la línea en céntimos.
quantity	number	no	Número de unidades (se permiten decimales, p. ej. 95.6).
quantity_unit	string	no	Etiqueta de unidad (p. ej. horas, días).
unit_price	integer	no	Precio por unidad, en céntimos.
unit_unit	string	no	Etiqueta de unidad monetaria.
is_tax	boolean	no	Si es una línea de impuesto explícita.
tax_amount	integer	no	Importe del impuesto en céntimos.

Los justificantes no se adjuntan por MCP

Los ficheros de justificante (PDF / imagen) no pueden subirse a través de este servidor MCP. Adjúntalos desde la aplicación web de uninvoice.app o la API HTTP.

Igual que create_invoice, esto registra una entrada pendiente de Auditoría IA y devuelve el id de la entrada; el gasto se crea solo cuando una persona lo aprueba.

generate_report

Genera un informe de negocio en PDF en segundo plano para un intervalo de tiempo. Refleja POST /v1/reports. Una vez aprobado, el informe se renderiza en segundo plano y a quien lo solicitó se le envía por correo un enlace de descarga; los informes listos también aparecen como recursos uninvoice://reports.

Esquema de entrada:

Campo	Tipo	Obligatorio	Descripción
report_type	enum	sí	Uno de business_overview, vat_summary, profit_loss, client_revenue, expense_supplier.
period_start	string (RFC 3339)	sí	Inicio de la ventana del informe (inclusive).
period_end	string (RFC 3339)	sí	Fin de la ventana del informe (exclusive).
locales	array de strings	no	Idioma(s) en los que renderizar (p. ej. en, es, es_ES). Se genera un informe por idioma, y los números se formatean según la región (así es_ES y es_MX difieren). Omítelo para renderizar un único informe en el idioma del usuario que lo solicita.

Igual que las demás herramientas, esto registra una entrada pendiente de Auditoría IA y devuelve el id de la entrada; la generación empieza solo cuando una persona la aprueba.

delete_report

Elimina un informe generado (y su PDF almacenado) por su id. Refleja DELETE /v1/reports/{id}.

Esquema de entrada:

Campo	Tipo	Obligatorio	Descripción
report_id	string	sí	El id del informe a eliminar (de uninvoice://reports).

Igual que las demás herramientas, esto registra una entrada pendiente de Auditoría IA y devuelve el id de la entrada; el informe se elimina solo cuando una persona lo aprueba.