Tool catalog

This page is generated from the server's real tool registry: if a tool exists, it is here, with the same annotations your MCP client sees. Up to 90 tools, depending on the grant's scopes.

Conventions every one of them shares

• The first argument of every empresa-scoped tool is empresa. Account-level tools reject it.
• An argument with ? is optional.
• Annotations are the protocol's own, read off the same annotations object your client receives: "read-only" is readOnlyHint, "irreversible" is destructiveHint, "idempotent" is idempotentHint. Your client decides whether to ask you every time from those.
• Idempotency is the server's job, not the agent's. A REST client sends its own Idempotency-Key; an MCP agent should not have to think about retry safety. The server generates and manages the key underneath — anchored to the preview_id when the call came from draft_document, or to a fresh UUID per call — so a retry after a dropped connection reuses the folio already assigned instead of burning a second one.
• This page lists every tool. YOUR CONNECTION MAY SEE FEWER. tools/list is filtered by the scopes the person granted: a tool appears only when everything in its Scopes column is in the grant. A connection holding documents:read empresas:read is not offered emit_document, because promising an invoice it cannot issue is worse than not offering it. Each tool also publishes its requirement in _meta.requiresScope, so a client can say WHY something is missing. Calling a tool the grant does not cover still answers insufficient_scope, naming the scope and how to get it — hidden is not the same as absent.
• Almost every tool needs empresas:read, even the ones that look like they only write: naming a company means reading the list of companies this connection may reach, which is also where the sandbox boundary is checked.
• Errors are REST errors. A tool's error content is the same { type, code, message, hint, retriable, param, doc_url, request_id, empresa } object from the error envelope, returned as MCP error content.
• Money, dates and RUT follow exactly the API's own conventions: integers in CLP, civil dates YYYY-MM-DD in America/Santiago, canonical RUT.

Issuing

draft_document returns receptor_incomplete naming the exact field that is missing, never a silent guess. emit_document can return totals_mismatch if the agent sent explicit totals that do not add up — the tool's own description tells it never to compute totals by hand unless it is sure, precisely because that field is an assertion, not a hint.

Reception

Tax

confirm_total_payable is still required through the MCP layer. The REST API already refuses to file without it, and that barrier is worth double here: it forces the figure to appear explicitly in the tool call, which forces it to appear explicitly in what the agent tells the human before filing.

Account

Deliberately sparse. select_empresa is scoped so it cannot break the requirement that the server be able to operate statelessly: an explicit empresa argument always wins, and losing the session loses a default, not a wrong answer.

Onboarding

None of these mark a step done, and that is not an omission: a step advances when we read the fact from the SII, never because someone said so. get_pending_human_action is the one to call when an issuance fails with empresa_not_emitting — it returns the full handoff, written for the person who has to act, who very often is not the account holder. Relay it as written: if a caveat comes back, that sentence goes too.

Sandbox

Both of these are REHEARSAL levers and touch test companies only: the API refuses them on a live empresa and so do the tools, before calling it. They exist because a sandbox empresa is born emitting with every step skipped, so the handoff — the most important thing this surface does — could not be tried without a live company and the real SII. Forcing a step ASSERTS a state; it does not advance anything. Outside the sandbox a step moves when we read the fact off the SII, never because somebody said so.

undefined

undefined

How files come back

MCP gives a tool two ways to return a file: embedded as a base64 blob, or as a resource_link the client only fetches if and when it needs the bytes. Facturia MCP always uses resource_link, never embedded blobs.

// → get_document_file
{ "empresa": "77928532-4", "document_id": "doc_01K2R7Q4XW9M3B8ZC5YHTVJD6N", "format": "pdf" }

// ← contenido del resultado
[
  { "type": "text", "text": "Factura 33 folio 412, enlace válido 10 minutos." },
  {
    "type": "resource_link",
    "uri": "https://ver.facturia.cl/l/3d9f2b8a1c?exp=1755184211",
    "name": "factura-33-412.pdf",
    "mimeType": "application/pdf"
  }
]

Three reasons:

• Context economy. A base64-embedded signed PDF can be hundreds of kilobytes of content injected into the model's context for a document nobody asked to have read aloud. A link costs one sentence.
• Client compatibility. The REST API's pdf_url / xml_url URLs require a key. Most MCP hosts have no way to attach Facturia's OAuth token when resolving a resource link — nor should they have to.
• Safer than the REST default. get_document_file switches on the mechanism REST already publishes as opt-in (signed public links, with an expiry, unauthenticated) and shortens its life to 10 minutes, scoped to a single document and never listable.

What is not on the agent surface

Requesting a CAF, managing webhooks, branding and RCV characterisation writes stay REST- and dashboard-only: they are one-off or rare actions with a UI far better than a chat turn, and dynamic client registration means the calling software is not verified the way a dashboard session is.

There are also no void (credit_note) or retry (retry) tools in this cut.

Besides tools, this server also publishes a prompt (onboard_empresa, the full onboarding walkthrough) and resources that point at this documentation and at the site's llms.txt, so an agent can discover them from inside the connection.