Servidor MCP

Open Factura expone sus operaciones como herramientas MCP para que un asistente de IA consulte, valide y emita documentos. Cada herramienta exige el mismo permiso que su ruta REST, así que la clave de API decide qué puede hacer el asistente. Empiece siempre con una clave of_test_….

Dos formas de conectarse

Forma	Dónde	Úsela cuando
Remota	`https://openfactura.co/mcp`	Su cliente puede enviar un encabezado HTTP fijo
Local (stdio)	`npx -y @openfactura/cli mcp`	Su cliente no envía encabezados (p. ej. Claude Desktop)

El servidor remoto es Streamable HTTP sin estado y sólo acepta claves de API (no la cookie del panel). El local expone las mismas herramientas y las ejecuta llamando a la API REST con su clave.

claude mcp add --transport http openfactura https://openfactura.co/mcp \
  --header "Authorization: Bearer of_test_..."

claude mcp add openfactura \
  --env OPENFACTURA_API_KEY=of_test_... \
  --env OPENFACTURA_URL=https://openfactura.co \
  -- npx -y @openfactura/cli mcp

En claude_desktop_config.json (o en un .mcp.json de proyecto):

{
  "mcpServers": {
    "openfactura": {
      "command": "npx",
      "args": ["-y", "@openfactura/cli", "mcp"],
      "env": {
        "OPENFACTURA_API_KEY": "of_test_...",
        "OPENFACTURA_URL": "https://openfactura.co"
      }
    }
  }
}

Si ya ejecutó openfactura login en ese equipo puede omitir env.

Herramientas

Herramienta	Qué hace	Permiso
`emisor_obtener`	Emisor, ambiente activo, puntos de venta	`emisor:read`
`catalogo_buscar`	Busca en catálogos del MH (CAT-xxx)	—
`clientes_buscar`	Busca clientes guardados	`clientes:read`
`cliente_crear`	Guarda un cliente	`clientes:write`
`productos_buscar`	Busca productos	`productos:read`
`producto_crear`	Guarda un producto (precio sin IVA)	`productos:write`
`dte_validar`	Valida sin emitir; devuelve problemas y total	`dte:emit`
`dte_emitir`	Emite (requiere `idempotencyKey`)	`dte:emit`
`dte_listar`	Lista documentos del ambiente activo	`dte:read`
`dte_obtener`	Estado, sello, respuesta del MH y eventos	`dte:read`
`dte_invalidar`	Invalida un documento o un evento	`dte:invalidate`
`dte_retorno`	Evento de retorno (requiere `idempotencyKey`)	`dte:emit`
`operaciones_especiales_informar`	Evento 17 (requiere `idempotencyKey`)	`dte:emit`
`eventos_listar`	Lista eventos de retorno y operaciones especiales	`dte:read`
`evento_obtener`	Un evento con su JSON y la respuesta del MH	`dte:read`

Cómo debe trabajar el asistente

emisor_obtener para saber el ambiente. En 01, avisarle que emitirá en producción.
Buscar receptor y productos; no adivinar NIT, NRC ni actividad económica.
dte_validar y corregir los problemas.
Mostrarle el resumen (tipo, receptor, líneas, total, ambiente) y esperar un “sí” explícito.
dte_emitir con una idempotencyKey, y reutilizarla si reintenta.

Las habilidades para agentes enseñan exactamente este flujo.