Catálogo de herramientas

Esta página se genera desde el registro real de herramientas del servidor: si una herramienta existe, está acá, con las mismas anotaciones que ve tu cliente MCP. Hasta 90 herramientas, según los scopes del grant.

Convenciones que comparten todas

• El primer argumento de cada herramienta con alcance de empresa es empresa. Las de nivel cuenta lo rechazan.
• Un argumento con ? es opcional.
• Las anotaciones son las del protocolo, leídas del mismo objeto annotations que recibe tu cliente: «solo lectura» es readOnlyHint, «irreversible» es destructiveHint, «idempotente» es idempotentHint. Tu cliente decide con eso si te pregunta cada vez o no.
• La idempotencia es trabajo del servidor, no del agente. Un cliente REST manda su propio Idempotency-Key; un agente MCP no debería tener que pensar en seguridad de reintento. El servidor genera y administra la llave por debajo — anclada al preview_id cuando la llamada vino de draft_document, o a un UUID nuevo por llamada — así que un reintento tras una conexión cortada reutiliza el folio ya asignado en vez de quemar un segundo.
• Esta página lista todas. TU CONEXIÓN puede ver menos. tools/list viene filtrado por los permisos que otorgó la persona: una herramienta aparece solo si todo lo que está en su columna Permisos está en el grant. Una conexión con documents:read empresas:read no recibe emit_document, porque prometer una factura que no puede emitir es peor que no ofrecerla. Cada herramienta publica además su requisito en _meta.requiresScope, para que un cliente pueda decir POR QUÉ falta alguna. Llamar a una que el grant no cubre sigue respondiendo insufficient_scope, con el permiso que falta y cómo conseguirlo: oculta no es lo mismo que inexistente.
• Casi todas necesitan empresas:read, incluso las que parecen solo de escritura: nombrar una empresa implica leer la lista de empresas que esta conexión alcanza, que es también donde se chequea el límite del sandbox.
• Los errores son errores REST. El contenido de error de una herramienta es el mismo objeto { type, code, message, hint, retriable, param, doc_url, request_id, empresa } del sobre de errores, devuelto como contenido de error MCP.
• Plata, fechas y RUT usan exactamente las convenciones de la API: enteros en CLP, fechas civiles YYYY-MM-DD en America/Santiago, RUT canónico.

Emisión

draft_document devuelve receptor_incomplete con el campo exacto que falta, nunca una adivinanza silenciosa. emit_document puede devolver totals_mismatch si el agente mandó totales explícitos que no cuadran — la descripción de la herramienta le dice que nunca calcule totales a mano salvo que esté seguro, precisamente porque ese campo es una aserción, no una pista.

Recepción

Impuestos

confirm_total_payable sigue siendo obligatorio a través de la capa MCP. La API REST ya se niega a declarar sin él, y esa barrera vale doble acá: obliga a que la cifra aparezca explícita en la llamada de herramienta, lo que obliga a que aparezca explícita en lo que el agente le diga a la persona antes de declarar.

Cuenta

Son deliberadamente escuetas. select_empresa está acotada para que no rompa el requisito de que el servidor sea capaz de operar sin estado: un argumento empresa explícito siempre gana, y perder la sesión pierde un default, no produce una respuesta equivocada.

Puesta en marcha

Ninguna de estas marca un paso como hecho, y no es una omisión: un paso avanza cuando leemos el hecho en el SII, nunca porque alguien lo diga. get_pending_human_action es la que hay que llamar cuando una emisión falla con empresa_not_emitting — devuelve el traspaso completo, en español, escrito para la persona que tiene que actuar, que muy seguido no es quien tiene la cuenta. Relátalo tal cual: si viene un caveat, esa frase también va.

Sandbox

Estas dos son de ENSAYO y sólo tocan empresas de prueba: la API las rechaza sobre una empresa real y las herramientas también, antes de llamarla. Existen porque una empresa sandbox nace emitting con todos los pasos omitidos, así que el traspaso —lo más importante que hace esta superficie— no se podía probar sin una empresa de verdad y el SII de verdad. Forzar un paso es afirmar un estado, no hacer avanzar nada: fuera del sandbox un paso avanza cuando leemos el hecho en el SII, nunca porque alguien lo diga.

Folios y CAF

Empresa

Cómo vuelven los archivos

MCP le da a una herramienta dos formas de devolver un archivo: embebido como blob base64, o como un resource_link que el cliente busca solo si y cuando necesita los bytes. Facturia MCP siempre usa resource_link, nunca blobs embebidos.

// → 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"
  }
]

Tres razones:

• Economía de contexto. Un PDF firmado embebido en base64 puede ser cientos de kilobytes de contenido inyectado al contexto del modelo por un documento que nadie pidió que leyera en voz alta. Un enlace cuesta una frase.
• Compatibilidad de clientes. Las URL pdf_url / xml_url de la API REST exigen una llave. La mayoría de los hosts MCP no tienen forma de adjuntar el token OAuth de Facturia al resolver un resource link — ni deberían tener que sostenerlo.
• Más seguro que el default REST. get_document_file enciende el mecanismo que REST ya publica como opt-in (enlaces públicos firmados, con vencimiento, sin autenticación) y le acorta la vida a 10 minutos, con alcance de un solo documento y sin listar.

Lo que no está en la superficie de agente

Pedir CAF, administrar webhooks, la marca y las escrituras de caracterización del RCV quedan solo en REST y panel: son acciones puntuales o raras con una UI mucho mejor que un turno de chat, y el registro dinámico de cliente significa que el software que llama no está verificado como sí lo está una sesión del panel.

Tampoco hay herramientas de anulación (credit_note) ni de reintento (retry) en este corte.

Además de herramientas, este servidor publica un prompt (onboard_empresa, la caminata completa de puesta en marcha) y recursos que apuntan a esta documentación y al llms.txt del sitio, para que un agente los descubra desde dentro de la conexión.