— "Emite una factura de 2 horas de consultoría a $75 para Juan Pérez, pago por transferencia, y mándale el PDF a su correo"

El asistente busca (o crea) al cliente, el servidor calcula el IVA y cuadra los totales con las reglas oficiales del SRI, te muestra el resumen, y tras tu confirmación emite, espera la autorización del SRI y te entrega el RIDE.

Por qué es seguro

La matemática tributaria no la hace el modelo de IA — la hace este servidor, con las mismas reglas que valida Contadeo:

Cálculo y cuadre de totales con aritmética decimal exacta (redondeo half-up a 2 decimales, agrupación de IVA por tarifa).
Validación del dígito verificador de cédulas y RUC (los 3 tipos) antes de enviar nada — espejo verificado contra el núcleo fiscal de Contadeo (fuzz de 100 000 valores, 0 diferencias).
Regla de consumidor final (identificación fija, máximo $50 — error SRI 69).
Catálogos oficiales embebidos: tarifas de IVA (Tabla 18), formas de pago (Tabla 24), tipos de identificación (Tabla 7).
El flujo exige confirmación humana: preparar_factura solo calcula y devuelve un resumen; emitir_factura re-valida el cuadre y rechaza payloads hechos a mano.
Ambiente siempre visible (Pruebas/Producción): el objeto ambiente viaja en las respuestas y el resumen que confirmas encabeza con un banner (⚠️ Producción = documento tributario real). Nunca se describe "de memoria".
confirmToken: preparar_* firma el resumen y emitir_* lo verifica — ata la emisión al resumen exacto que confirmaste y bloquea payloads modificados o resúmenes rancios (se activa con MCP_CONFIRM_SECRET).
Auditoría: cada emisión queda registrada (tenant, tool, latencia, sin datos personales) para depuración y cumplimiento.
Reverso legal: para dejar sin efecto una factura se emite una nota de crédito (preparar_nota_credito / emitir_nota_credito) — la vía del SRI cuando ya no aplica la anulación (fuera del plazo del día 7, o consumidor final). La anulación interna (estado ANULADO) sigue haciéndose desde el panel; su trámite formal ante el SRI es en SRI en línea.

Protección de datos e IA

Las respuestas de estas tools pueden contener datos personales de terceros: los compradores y proveedores del emisor (identificación, nombre, email, teléfono, dirección). Eso significa que la facturación pasa a tratarse mediante un sistema de IA, con un reparto de roles que conviene tener claro (LOPDP y resolución SPSP-SPD-2026-0009-R de la SPDP):

Quién	Rol
La empresa emisora (tenant)	Responsable del tratamiento de los datos de sus compradores y desplegador del sistema de IA: es quien decide conectar el asistente y a cuál
Contadeo	Encargado del tratamiento: entrega los datos por el canal MCP bajo instrucciones del tenant. No elige el asistente ni consume ningún modelo de lenguaje
El proveedor del modelo (Anthropic, OpenAI, el que sea)	Lo elige y contrata el tenant con su cliente de IA. No es subencargado de Contadeo: la transferencia la ejecuta el asistente, bajo responsabilidad del tenant

Qué hace el servidor por su parte: las instructions incluyen la regla (10), que ordena al asistente usar esos datos solo para la tarea en curso y no retenerlos ni reutilizarlos fuera de ella; la auditoría (mcp_auditoria) registra la llamada sin PII; y el catálogo y los comprobantes siguen acotados por la credencial y por RLS al tenant conectado.

Qué le toca al tenant: decirlo en su aviso de privacidad. Hay un texto modelo listo para copiar en docs/legal/TEXTO-MODELO-AVISO-IA.md. Si el asistente va a manejar datos de compradores, ese aviso es parte de la transparencia que la LOPDP exige hacia el titular.

Requisitos

Cuenta en contadeo.com (gratis: 10 comprobantes/mes) con emisor y certificado .p12 configurados
Para el modo stdio: Node.js 18+ y una API key (panel → Configuración → API → Crear; rol emisor basta)

Conexión recomendada: servidor remoto con OAuth

Sin API keys: el cliente abre el login de Contadeo, autorizas con un clic y listo (OAuth 2.1 con PKCE y registro dinámico de clientes).

# Claude Code
claude mcp add --transport http contadeo https://contadeo.com/api/mcp
# dentro de la sesión: /mcp → authenticate (abre el navegador)

En claude.ai: Settings → Connectors → Add custom connector → https://contadeo.com/api/mcp.

Para clientes que solo hablan stdio pero soportan OAuth vía proxy:

claude mcp add contadeo -- npx -y mcp-remote https://contadeo.com/api/mcp

Revocar el acceso: cambia tu contraseña en Contadeo (invalida los tokens de todos los clientes conectados).

Método alternativo: stdio + API key

Útil para automatizaciones machine-to-machine o clientes sin MCP remoto. La API key se crea en el panel (Configuración → API; el rol emisor basta).

Claude Desktop / Cursor (`claude_desktop_config.json`)

{
  "mcpServers": {
    "contadeo": {
      "command": "npx",
      "args": ["-y", "contadeo-mcp"],
      "env": { "CONTADEO_API_KEY": "cdo_tu_api_key" }
    }
  }
}

Claude Code

claude mcp add contadeo -e CONTADEO_API_KEY=cdo_tu_api_key -- npx -y contadeo-mcp

Variables de entorno (solo stdio)

Variable	Requerida	Default
`CONTADEO_API_KEY`	✅	—
`CONTADEO_API_URL`	—	`https://contadeo.com/api`

MCP Registry

Los metadatos del servidor para el MCP Registry oficial viven en server.json, bajo el nombre com.contadeo/mcp. Ese es el identificador con el que lo resuelven los clientes que leen el registro. Si el tuyo no lo encuentra, se instala igual desde npm como contadeo-mcp o se conecta como servidor remoto (ver arriba).

Tu primera factura (tutorial)

Recomendado: deja tu cuenta en ambiente de Pruebas (Configuración → Empresa) hasta dominar el flujo — los comprobantes de Pruebas no tienen validez tributaria.

Una conversación real se ve así:

Tú: Factúrale a María García, cédula 1723456784, 3 cajas de té a $4.50 cada una, pago en efectivo. Su correo es maria@correo.com

Asistente: (usa contexto_emision, crear_cliente y preparar_factura) Te muestro el resumen antes de emitir:
Factura para: MARIA GARCIA (Cédula 1723456784)
Detalle:
  • 3 × Caja de té @ $4.50 = $13.50 [IVA 15% (tarifa general vigente)]
Subtotal (sin impuestos): $13.50
IVA: $2.03
TOTAL: $15.53
Forma de pago: Sin utilización del sistema financiero (efectivo)
RIDE se enviará a: maria@correo.com
¿Confirmas la emisión?

Tú: Sí

Asistente: (emitir_factura → esperar_autorizacion) ✅ AUTORIZADA por el SRI en 8 segundos. Clave de acceso 2306…947. Aquí tienes el PDF: [descargar RIDE]. María también lo recibirá en su correo.

En clientes MCP que soportan prompts, el comando facturar arranca este flujo guiado automáticamente.

Tools

Categoría	Tool	Qué hace
Cuenta	`consultar_cuenta`	Plan, consumo del mes y ambiente (Pruebas/Producción)
Contexto	`contexto_emision`	Emisores, establecimientos, puntos y certificados (los IDs para emitir)
Catálogo	`buscar_clientes` / `buscar_productos`	Búsqueda por texto
Catálogo	`crear_cliente` / `crear_producto`	Altas (valida cédula/RUC y tarifas antes de enviar)
Catálogo	`ajustar_stock`	Ajusta las existencias de un producto (entrada, salida o corrección de inventario)
Catálogo	`consultar_ruc`	Autocompleta al comprador por RUC/cédula (directorio + catastro SRI); alerta de contribuyente fantasma/inactivo
Emisión	`preparar_factura`	Calcula y cuadra todo; devuelve resumen + payload (con `idempotencyKey`). `fechaEmision` opcional: default hoy, hasta 5 días atrás. No emite
Emisión	`emitir_factura`	Emite tras confirmación; re-valida el cuadre localmente
Emisión	`preparar_lote`	Hasta 25 facturas de una vez: datos comunes al lote + override por factura; devuelve `resumenAgregado` (tabla por factura + totales). No emite
Emisión	`emitir_lote`	Emite el lote en secuencia tras UNA confirmación; pre-vuelo todo-o-nada y estado por factura (ENCOLADA/FALLO/NO_INTENTADA)
Reverso	`preparar_nota_credito`	Nota de crédito (04) que revierte una factura: reverso TOTAL desde `comprobanteId` + `motivo`, o explícito/parcial con `items`. Calcula y cuadra; no emite
Reverso	`emitir_nota_credito`	Emite la nota de crédito tras confirmación; re-valida cuadre y confirmToken
Emisión	`esperar_autorizacion`	Polling hasta AUTORIZADO/RECHAZADO (el SRI tarda 5–30 s); acepta `id` o `ids` (hasta 25, para lotes). Los AUTORIZADO incluyen los links de descarga del RIDE y XML
Consulta	`listar_comprobantes` / `consultar_comprobante`	Estados y detalle; con `eventos: true` incluye el timeline paso a paso de la emisión
Descarga	`descargar_ride` / `descargar_xml`	URLs temporales (1 h) del PDF y XML
Acción	`anular_comprobante` / `reenviar_comprobante`	Anula una factura autorizada (registro interno; si no aplica, orienta a nota de crédito) o reenvía el RIDE/XML por email
Reportes	`reporte_ventas`	Agregados del período
Multi-cuenta	(sin tool propia)	Si tu cuenta administra varias empresas (un RUC = una empresa), `consultar_cuenta`, `contexto_emision` y `mi_situacion_tributaria` traen el bloque `multiempresa`: cuál está activa y cuáles son las otras. Desde v0.23.0 todas las tools aceptan `cuenta` con el tenantId de otra empresa, emisión incluida: el resumen que confirmas nombra la razón social y el RUC emisor, y el confirmToken ata la empresa. Requiere conexión OAuth autorizada con 'operar todas mis cuentas'
Referencia	`consultar_reglas_sri`	Tablas oficiales: tarifas IVA, formas de pago, identificaciones, reglas
Asesor	`consultar_calendario_tributario`	Próximos vencimientos según el 9.º dígito del RUC y el régimen
Asesor	`consultar_semaforo_rimpe`	Proyección de ingresos vs límites RIMPE: VERDE/AMARILLO/ROJO
Asesor	`consultar_obligaciones`	Checklist de obligaciones del perfil (declaraciones, anexos, contabilidad)
Asesor	`consultar_f104`	Borrador del F104 de IVA explicado: cifras + resumen en español llano, desglose por casillero (429, 564, 601, 605, 609, 902/615), alertas proactivas y proyección del arrastre — no es la declaración oficial
Asesor	`explicar_f104`	Narra la declaración casillero por casillero para quien nunca ha declarado; también explica cifras pegadas de una declaración ya presentada
Asesor	`simular_f104`	"¿Si facturo $500 más, cuánto más pago?": escenarios de ventas/compras/retenciones/ventas a crédito sobre el borrador, con la tarifa vigente del servidor
Asesor	`validar_f104`	Chequeo previo a declarar: cruza el borrador contra los libros, detecta compras sin autorización, notas de crédito por compensar y diferencias con lo que piensas declarar
Asesor	`consultar_libro_ventas` / `consultar_libro_compras`	Libros de ventas y de compras del período (líneas + totales, insumo de declaración y ATS)
Asesor	`consultar_retenciones`	Retenciones practicadas por el emisor (no las que le practican a él) en el período
Asesor	`consultar_f103`	Auxiliar del F103 (retenciones en la fuente de RENTA): agrupa por código de retención del SRI (base, valor, cantidad) + vencimiento del catálogo; excluye IVA (va al F104/ATS). No es la declaración oficial: el mapeo código→casillero lo confirma el contador
ATS (módulo sin publicar)	`consultar_ats`	Borrador de solo lectura del Anexo Transaccional Simplificado: conteos por sección, totales de cabecera, informe de validación (V1-V17/N1-N9), exclusiones, brechas del producto y si el período ya tiene un anexo archivado (`snapshot`). NUNCA devuelve el XML ni el ZIP — llevan la identificación de todos los clientes y proveedores del período; eso se descarga solo desde el panel. Requiere el módulo `ats` (402 sin él)
Asesor	`registrar_compra` / `clasificar_proveedor`	Registro de una compra con su base y tarifa (el IVA lo deriva el servidor) y clasificación de IVA de un proveedor en dos fases: primero el impacto, y solo con `confirmar` se aplica
Orientación	`mi_situacion_tributaria`	«¿Cómo voy?» en una llamada: qué falta para emitir, alertas, semáforo RIMPE y obligaciones, con el `resumen` ya redactado
Orientación	`explicar_termino`	Glosario del SRI (RIDE, RIMPE, retención, clave de acceso…) para no definir de memoria

Los tools del Asesor son informativos: el servidor calcula con sus catálogos legislativos vigentes y toda respuesta incluye un disclaimer («no constituye asesoría tributaria») que el asistente siempre muestra. 39 tools en total, las mismas para todas las cuentas: el catálogo ya no se filtra por perfil (las 3 tools de despacho multiempresa se retiraron en la v0.19.0).

Campos de respuesta (v0.7.0): preparar_* incluye el objeto ambiente, preparadoEn y un confirmToken en cada payload (reenvíalo tal cual, junto al idempotencyKey); emitir_* devuelve el ambiente legible y encoladoEn (y en el lote estadoComprobante); esperar_autorizacion y consultar_comprobante traen el ambiente legible, y con eventos:true el timeline incluye firmado → enviado → autorizado → notificado. El detalle interno de arquitectura vive en docs/MCP.md.

Lotes: varias facturas de una vez

Para emitir hasta 25 facturas en una sola pasada (p. ej. la facturación mensual a toda la cartera):

preparar_lote — construye el lote con la matemática hecha por el servidor: comprador, forma de pago y fechaEmision comunes al lote, con override por factura. Devuelve el resumenAgregado (tabla por factura + totales del lote).
UNA confirmación — el asistente muestra la tabla completa y pide una única confirmación explícita del lote entero antes de emitir.
emitir_lote — emite en secuencia con pre-vuelo todo-o-nada (si un payload no cuadra, no se emite ninguna); si una factura falla continúa con las demás, salvo 401/402/429 que corta el lote.
esperar_autorizacion con ids — sigue todos los comprobantes hasta el estado terminal (timeout sugerido: 90 s).

Reintentos seguros: cada payload lleva su idempotencyKey (lo genera preparar_lote); reintentar la emisión con la misma clave devuelve el comprobante original — no quema secuenciales ni duplica facturas.

Reglas del SRI que el servidor aplica por ti

Regla	Detalle
Tarifas de IVA (Tabla 18)	`'4'` = 15% (general vigente) · `'0'` = 0% · `'5'` = 5% · `'7'` = exento · `'6'` = no objeto
Formas de pago (Tabla 24)	`'01'` efectivo · `'20'` transferencia · `'19'` t. crédito · `'16'` t. débito · más en `consultar_reglas_sri`
Identificación (Tabla 7)	`'04'` RUC · `'05'` cédula · `'06'` pasaporte · `'07'` consumidor final — con dígito verificador validado
Consumidor final	Identificación fija `9999999999999`, importe máximo $50
Cuadre	línea = cantidad×precio−descuento; IVA = base×tarifa/100; total = subtotal+IVA+propina — redondeo half-up a 2 decimales
Fecha de emisión	Default: hoy (calendario de Ecuador). `fechaEmision` opcional acepta hasta 5 días atrás; nunca futura (la API la rechaza — error 65 SRI)

Skill para Claude (opcional, recomendado)

La carpeta skill/facturacion-contadeo/ contiene un Agent Skill que le enseña a Claude el flujo completo, las reglas de oro (nunca emitir sin confirmación, nunca calcular de cabeza, verificar el ambiente) y el manejo de errores del SRI. Instalación en Claude Code:

mkdir -p ~/.claude/skills && cp -r node_modules/contadeo-mcp/skill/facturacion-contadeo ~/.claude/skills/

(o copia la carpeta a .claude/skills/ de tu proyecto).

Troubleshooting

Síntoma	Causa probable	Solución
`401 API key inválida o revocada`	Key mal copiada o revocada	Genera otra en Configuración → API
`402 Cupo mensual agotado`	Límite del plan	contadeo.com/precios
`RECHAZADO` con error 62	Identificación inválida	El flujo normal lo previene; revisa el número con el comprador
`RECHAZADO` con error 52	Totales descuadrados	Usa siempre `preparar_factura`; no edites el payload
Queda en `ENVIADO`/`CONTINGENCIA`	SRI lento o caído	Reintentos automáticos; consulta en unos minutos
La factura salió "de verdad" sin querer	Cuenta en Producción	Cambia a Pruebas en Configuración → Empresa para experimentar

Desarrollo

# desde la raíz del monorepo (el paquete vive en el workspace)
pnpm install
pnpm --filter contadeo-mcp test    # vitest: identificación + cálculo/cuadre
pnpm --filter contadeo-mcp build   # tsc → dist/
CONTADEO_API_KEY=cdo_... node mcp/dist/index.js   # corre por stdio

El paquete exporta crearServidorContadeo({ apiUrl, token, confirmSecret?, onAuditoria? }): la misma factoría que usa el backend de Contadeo para montar el servidor remoto en https://contadeo.com/api/mcp. Arquitectura interna (protocolo, garantías, modelo de datos): docs/MCP.md; transporte/OAuth y despliegue: docs/MCP-REMOTO.md.

Documentación completa de la API REST: https://contadeo.com/desarrolladores