MCP server

uninvoice.app ships a Model Context Protocol (MCP) server so AI agents and MCP-aware tools can read your company data and create invoices directly. It exposes the same operations as the HTTP API, authenticated the same way, but shaped as MCP resources and tools.

info

The MCP server is a distinct process from the HTTP API. It speaks MCP over the streamable-HTTP transport: your MCP client connects to a single HTTP endpoint, exposed at its own MCP endpoint URL.

Authentication

Every MCP request must carry a Bearer token in the Authorization header — the same tokens the HTTP API accepts (an API token or a session JWT). The token is validated on every operation, including listing resources and tools. A missing or malformed header, or an invalid or revoked token, is rejected.

The token determines the acting user and company; every resource you read and every invoice you create is scoped to that company.

Configure your MCP client with the endpoint URL and the header, for example:

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

Resources

Resources are read-only views of your data under the uninvoice:// URI scheme. They return application/json.

URI	Description
uninvoice://company	Your company configuration.
uninvoice://entities	All entities (clients / suppliers).
uninvoice://entities/{id}	A single entity by ID.
uninvoice://invoices	All invoices (each with its lineCount).
uninvoice://invoices/{id}	A single invoice with its lines.
uninvoice://proformas	All proformas (each with its lineCount).
uninvoice://proformas/{id}	A single proforma with its lines.

The .../{id} forms are advertised as resource templates; the collection forms are listed as plain resources.

Tools

create_invoice

Creates a new draft invoice for a recipient, with line items. Taxes are calculated automatically from the company and recipient. This mirrors POST /v1/invoices; the resulting invoice is a draft until you issue it through the HTTP API.

Input schema:

Field	Type	Required	Description
recipient_id	string	yes	Entity ID of the recipient.
supply_type	"services" | "goods"	yes	Whether the invoice covers services or goods.
lines	array	yes	Line items (see below).

Each entry in lines:

Field	Type	Required	Description
idx	integer	yes	Line index (1-based).
concept	string	yes	Description of the service or product.
quantity	integer	no	Number of units.
quantity_unit	string	no	Unit label (e.g. hours, days).
unit_price	integer	no	Price per unit, in cents.
unit_unit	string	no	Currency unit label.
is_tax	boolean	no	Whether this is an explicit tax line.
tax_amount	integer	no	Tax amount in cents.
subtotal	integer	no	Line subtotal in cents.

Example arguments:

{
  "recipient_id": "ent_...",
  "supply_type": "services",
  "lines": [
    { "idx": 1, "concept": "Consulting — June 2026", "quantity": 10, "quantity_unit": "hours", "unit_price": 20000 }
  ]
}

The tool returns the created invoice as JSON.

Issuing happens over the HTTP API

The MCP tool creates drafts only. To assign the invoice number and (for Spanish issuers) report it to the AEAT, issue it with POST /v1/invoices/{id}/issue. The same Veri*Factu authorization gate applies — business errors, including the apoderamiento requirement, are surfaced to the MCP caller with their actionable message.