Colombia Invoice MCP Server

Colombia Invoice MCP 🇨🇴 — How can my AI agent issue a DIAN factura electrónica?

Remote MCP server that lets any AI agent issue and query Colombia electronic invoices (factura electrónica / factura de venta, DIAN UBL 2.1, modelo de validación previa) through Matias API. Matias generates, digitally signs and transmits the invoice straight to the DIAN with no Proveedor Tecnológico (PT) middleman from the merchant's own account; this server is a stateless forwarder that also does the local IVA math. Bring-your-own credentials, never stores anything.

Live endpoint: https://inv-co.wishpool.app/mcp · Registry: app.wishpool/colombia-invoice-mcp

Honest scope — the positioning chain

This wraps the Matias API calls and does the IVA math. Signing and DIAN transmission stay in your Matias account.

The trust chain, spelled out honestly:

1. You self-register a Matias API account (self-service — no sales contract needed; production credentials auto-replicate to sandbox).
2. You hold your own DIAN resolución de facturación and digital certificate — bought from a Colombian certification body (entidad de certificación digital), issued to your DIAN account. This server never sees them.
3. Matias is a "Software Propio" provider: it connects directly to the DIAN with no Proveedor Tecnológico (PT) middleman (their FAQ states this — conexión directa DIAN, sin PT). It signs the UBL 2.1 document with your certificate and transmits it to the DIAN under the validación previa model.
4. This MCP server is a stateless forwarder: it validates your input, computes the Colombian IVA locally, builds the Matias invoice body, and relays POST /invoice / GET /documents/{uuid} with your bearer token. It never signs, never holds a certificate, never stores credentials.

• ✅ It does: validate and assemble the factura de venta from your buyer + line items, compute the Colombia IVA (19% / 5% / 0% exento/excluido, COP integers, tax-exclusive), forward POST /invoice to Matias, and translate the response (cufe, state); look a document up by uuid.
• ❌ It does NOT: hold your digital certificate, apply the signature, or transmit to the DIAN itself. Matias does all of that inside your own Matias account. A compromise of this stateless forwarder cannot forge or alter your invoices.

Quick start

{
  "mcpServers": {
    "colombia-invoice": {
      "type": "http",
      "url": "https://inv-co.wishpool.app/mcp",
      "headers": {
        "x-matias-token": "your-matias-bearer-token",
        "x-matias-env": "sandbox"
      }
    }
  }
}

Self-register free at matias-api.com — POST /register with first_name, last_name, company_name, email, password, password_confirmation, dni. Registration happens on the production URL and your credentials automatically replicate to the sandbox, so you can integrate against sandbox-api.matias-api.com/api/ubl2.1 before going live. Get a bearer token from POST /auth/login (JWT) or a long-lived Personal Access Token from POST /auth/token.

Required header: x-matias-token. Optional: x-matias-env (sandbox default = pruebas, no fiscal effect; production = real DIAN), x-matias-base (override the production base URL Matias assigns on contract), and the owner-policy headers below.

Tools

Money & IVA (the load-bearing math)

Colombian pesos (COP) are used as integer pesos, and unit prices are tax-exclusive (valor neto, before IVA). IVA rate per line is 19 (standard), 5 (reduced) or 0 (exento/excluido). Because prices exclude IVA, the IVA portion is:

• 19%: iva = round(net * 19 / 100)
• 5%: iva = round(net * 5 / 100)
• 0%: exento/excluido (no IVA)

The server sets each line's line_extension_amount (net), tax_totals and builds document-level legal_monetary_totals (line_extension_amount, tax_exclusive_amount, tax_inclusive_amount, payable_amount) and grouped tax_totals by rate. Covered by test/tax.test.js (19% / 5% / 0% / mixed / rounding).

Owner policy guardrails ride optional headers (x-agentpay-max-amount, x-agentpay-approval-above, x-agentpay-allowed-tools) — set by the human owner in client config; the agent cannot relax them. Cap scope: the amount gate reads the invoice grand total (pesos, COP) computed locally from the line items.

DIAN factura electrónica mandate (validación previa)

Colombia's DIAN factura electrónica de venta runs on the modelo de validación previa: the DIAN validates the document before it is delivered to the buyer, returning the CUFE (Código Único de Facturación Electrónica) that makes it fiscally valid. Under successive Resoluciones DIAN and the Estatuto Tributario, issuing the electronic factura de venta is obligatory for responsables de IVA and, progressively, for essentially all taxpayers selling goods or rendering services. Matias lets you integrate and test ahead of, or in step with, your obligation.

Endpoints wrapped

Sandbox base https://sandbox-api.matias-api.com/api/ubl2.1, auth Authorization: Bearer <token>:

Matias responses are passed through: a 4xx with { "message": "..." } (e.g. Unauthenticated.) or a { "success": false } body surfaces as Matias API error: ….

Develop

node test/tax.test.js   # IVA math unit tests (19% / 5% / 0% / mixed / rounding)
node test/serve.js      # local server on :3271
node test/e2e.js        # protocol + validation + policy asserts + LIVE fake-token probes against Matias

The e2e suite makes real calls to sandbox-api.matias-api.com/api/ubl2.1: a fake bearer token runs the full create_invoice / query_invoice path and surfaces Matias's native {"message":"Unauthenticated."} (HTTP 401) — the deepest live verification possible without a real onboarded Matias account (we never sign, so we cannot mint a valid DIAN document).

Honest gap

Without a real Matias account + DIAN resolución, the happy-path create_invoice response shape (exact cufe / DIAN acceptance field names) is assembled from the Matias Swagger (docs.matias-api.com/api-docs) and quickstart, not from a live authorized submission. The request body, IVA math, endpoint paths and the live 401 Unauthenticated fingerprint are verified; the success-response field mapping is best-effort and passed through in raw so nothing is lost. First real-key success is auto-reported by the sentinel beacon.

Safety

Pure stateless translation layer. Digital signing and DIAN transmission happen inside the merchant's own Matias account (Software Propio, direct to DIAN, no PT); the token travels per-request in a header, nothing is stored. Privacy policy.

Sister servers

Invoices: Mexico CFDI inv-mx · Brazil NF-e inv-br · Chile DTE inv-cl · Peru CPE inv-pe · Argentina AFIP inv-ar · Costa Rica Hacienda inv-cr · Ecuador SRI inv-ec · Paraguay SIFEN inv-py · Saudi ZATCA inv-sa · India GST inv-in · Poland KSeF inv-pl · Local payments in 81 countries, one family: mcp.wishpool.app · Logistics & shipping: logi.wishpool.app · Taiwan e-invoice 電子發票 included.

MIT licensed.