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 y crear facturas 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 (un token de API o un JWT de sesión). 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.

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://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.

Las variantes .../{id} se anuncian como plantillas de recurso; las variantes de colección 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
idx	integer	sí	Índice de línea (basado en 1).
concept	string	sí	Descripción del servicio o producto.
quantity	integer	no	Número de unidades.
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.

Argumentos de ejemplo:

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

La herramienta devuelve la factura creada en JSON.

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.