Skip to main content

Tools

The server exposes 17 tools grouped by functional area.

Organization

get_user_organization_info

Returns the active organization context (tax ID, fiscal regime, and defaults) so the agent can operate with the correct fiscal context when company or tax defaults are needed.

get_mcp_workflows_guidance

Returns summarized MCP workflow guidance (workflow name, description, and kickoff steps) to help the agent plan or execute multistep flows.

Contacts

list_contacts

Search contacts in the organization with optional filters.

resolve_contact

Deterministically resolve a single contact. Returns status (unique / ambiguous / none) and up to 5 candidates. Use this before any write operation that requires a contact_id. At least one of the four fields is required.

create_contact

Create a new contact in the organization. Idempotent on document_number: if a contact with that NIF/CIF already exists, returns the existing one instead of creating a duplicate.

update_contact

Update the fields of an existing contact. Only the fields passed are modified (PATCH semantics).

Products

resolve_product

Deterministically resolve a single product. Returns status (unique / ambiguous / none) and candidates. Use this before creating an invoice draft. At least one of the two fields is required.

create_product

Add a new product to the organization’s catalogue.

update_product

Update the fields of an existing product. Only the fields passed are modified (PATCH semantics).

Invoices

resolve_invoice

Locate an existing issued invoice.

create_invoice_draft

Create an ordinary (F1) invoice draft. The draft is not issued; use issue_invoice_draft to make it fiscally binding. Returns the draft_id, a confirmation_token, and a preview to show the user before issuing.

create_simplified_invoice_draft

Create a simplified (F2) invoice draft, without an associated contact. Useful for tickets or general public sales. Returns draft_id, confirmation_token, and a preview.

issue_invoice_draft

Destructive and irreversible operation. Once issued, the invoice is hash-chained and cannot be modified or deleted.
Keep in mind that invoices will not be sent to Verifactu until you submit the request from the platform.
Issue a draft (F1 or F2), making it fiscally binding. The invoice is automatically submitted to VeriFactu.

send_invoice_email

Send or resend an issued invoice by email to its associated contact.

Received invoices

create_received_invoice

Register a supplier invoice. Before calling it, use resolve_contact and show the user only the invoice data: supplier, number, date, lines, totals, payment state, and accounting classification. Require explicit confirmation and a new UUID in idempotency_key. Registration never attaches a document: if upload_session_id is sent, the tool returns the attach_after_registration error and does not create the invoice. The server calculates authoritative totals, detects duplicates, and rejects closed periods. control_totals lets you compare source-document totals with server-calculated totals; the response includes discrepancies. The response returns the persisted id, authoritative totals, discrepancies, attachment state (always without a document), and edit URL. After registration, the agent may offer to attach the source document.

create_received_invoice_upload_session

Create a short-lived session to attach the PDF or image of an already registered received invoice. Call it only after create_received_invoice has succeeded and the user has accepted attaching the document. The session is bound to the given invoice and can only be attached to it. The response includes upload_session_id, expires_at, upload_url, and received_invoice (id, full_number, and supplier_name). Use the returned upload_url or render the MCP App resource in ui.resourceUri; both interfaces show the supplier and invoice number. It accepts one server-validated document; do not send file bytes, storage keys, or credentials as arguments. When the upload is ready, call update_received_invoice with the same received_invoice_id, attachment_action replace, and upload_session_id.

update_received_invoice

Correct an existing received invoice after showing and confirming the complete corrected state. Use received_invoice_id and a new UUID in idempotency_key; if the supplier changes, resolve it first with resolve_contact. Omitted scalar fields are preserved and supplied lines replace the complete line set. attachment_action can be preserve, replace, or remove; upload_session_id is required when replacing and must be a session created for the same invoice. To attach the document to a newly registered invoice, send only received_invoice_id, idempotency_key, attachment_action, and upload_session_id. The response includes changed_fields, recalculated totals, and final attachment state.

Prompt

create_invoice

Full guided flow for issuing an invoice. The agent resolves the contact and products, creates the draft, presents the preview, and requests explicit confirmation before issuing.