# 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](https://docs.uninvoice.app/es/api/reference), 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](https://docs.uninvoice.app/es/api/overview#autenticaci%C3%B3n) 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](https://docs.uninvoice.app/es/api/ai-audit)** 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://" , "headers" : { "Authorization" : "Bearer " } } } } ``` ## 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`](https://docs.uninvoice.app/es/api/#tag/Invoices/operation/create-invoice); 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](https://docs.uninvoice.app/es/api/overview#importes). | | `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](https://docs.uninvoice.app/es/api/ai-audit)** 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`](https://docs.uninvoice.app/es/api/#tag/Invoices/operation/issue-invoice). Se aplica el mismo [requisito de autorización Veri\*Factu](https://docs.uninvoice.app/es/verifactu/authorize): los errores de negocio, incluido el de la autorización Veri\*Factu, 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`](https://docs.uninvoice.app/es/api/#tag/Expenses/operation/create-expense). 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](https://docs.uninvoice.app/es/api/overview#importes). | | `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](https://docs.uninvoice.app/es/api/ai-audit)** 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`](https://docs.uninvoice.app/es/api/#tag/Reports/operation/request-report). 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`](#recursos). 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](https://docs.uninvoice.app/es/api/ai-audit)** 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}`](https://docs.uninvoice.app/es/api/#tag/Reports/operation/delete-report). 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](https://docs.uninvoice.app/es/api/ai-audit)** y devuelve el id de la entrada; el informe se elimina solo cuando una persona lo aprueba.