Skip to content

Open Factura exposes its operations as MCP tools so an AI assistant can query, validate, and issue documents. Each tool requires the same permission as its REST route, so the API key decides what the assistant can do. Always start with an of_test_… key.

Mode Where Use it when
Remote https://openfactura.co/mcp Your client can send a fixed HTTP header
Local (stdio) npx -y @openfactura/cli mcp Your client doesn’t send headers (e.g. Claude Desktop)

The remote server is stateless Streamable HTTP and only accepts API keys (not the dashboard cookie). The local one exposes the same tools and runs them by calling the REST API with your key.

It works with any MCP client. The CLI writes the configuration for Claude Code, Claude Desktop, Cursor, VS Code, Codex, Gemini CLI, Windsurf, Zed, Cline, and Goose:

Ventana de terminal
npx @openfactura/cli login
npx @openfactura/cli mcp install --todos # or a single agent: cursor, codex, vscode…

Manual configuration for each agent is in Connect your agent. Examples with Claude:

Ventana de terminal
claude mcp add --transport http openfactura https://openfactura.co/mcp \
--header "Authorization: Bearer of_test_..."
Tool What it does Permission
emisor_obtener Issuer, active environment, points of sale emisor:read
catalogo_buscar Searches MH catalogs (CAT-xxx) —
clientes_buscar Searches saved customers (production only) clientes:read
cliente_crear Saves a customer (production only) clientes:write
productos_buscar Searches the key environment’s products productos:read
producto_crear Saves a product (price without VAT) productos:write
dte_validar Validates without issuing; returns problems and total dte:emit
dte_emitir Issues (requires idempotencyKey) dte:emit
dte_listar Lists documents in the active environment dte:read
dte_obtener Status, stamp, MH response, and events dte:read
dte_invalidar Invalidates a document or an event dte:invalidate
dte_retorno Return event (requires idempotencyKey) dte:emit
operaciones_especiales_informar Event 17 (requires idempotencyKey) dte:emit
eventos_listar Lists return and special operations events dte:read
evento_obtener An event with its JSON and the MH response dte:read
webhooks_listar Your webhooks in the key’s environment webhooks:manage
webhook_crear Creates a webhook (the secret only appears here) webhooks:manage
webhook_eliminar Deletes a webhook webhooks:manage
webhook_probar Sends a signed test event webhooks:manage
uso_obtener DTEs issued and processed per period dte:read
registros_listar Recent API requests (for debugging) registros:read
Tool What it’s for Permission
dte_enviar_correo Emails a stamped DTE with its PDF and JSON dte:emit
certificacion_estado Progress of the minimum tests dte:read
certificacion_avanzar Next batch of minimum tests dte:emit and dte:invalidate
plataforma_clientes_listar Your customers, their status, and what’s missing Key enabled for Plataforma
plataforma_cliente_crear Adds a customer (with prefilled data) Key enabled for Plataforma
plataforma_cliente_enlace Their onboarding link Key enabled for Plataforma
plataforma_cliente_clave_crear An API key in the customer’s space Key enabled for Plataforma
  1. emisor_obtener to learn the environment. In 01, warn you that it will issue in production.
  2. Look up the recipient and products; never guess a NIT, NRC, or economic activity. In test mode there are no saved customers: the recipient goes in datos.receptor.
  3. dte_validar and fix the problems.
  4. Show you the summary (type, recipient, lines, total, environment) and wait for an explicit “yes”.
  5. dte_emitir with an idempotencyKey, and reuse it on retries.

The agent skills teach exactly this flow.

For AI assistants: llms.txt ·llms-full.txt ·every page as Markdown by adding .md to its path.