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

<!-- install-cta -->
## Use it in 60 seconds

Paste this into your MCP client config (Claude Desktop, Cursor, Windsurf, or any MCP-capable agent):

```json
{
  "mcpServers": {
    "colombia-invoice": {
      "type": "http",
      "url": "https://inv-co.wishpool.app/mcp"
    }
  }
}
```

Nothing to install. Credentials, when you need them, travel as HTTP headers on each request and are never stored — see the [threat model](https://mcp.wishpool.app/trust).

### Or run it yourself

Would you rather not send production credentials to a server you do not control? Deploy this identical code to your own account and point your agent at your own URL:

[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https://github.com/junter1989k-ai/colombia-invoice-mcp)

```bash
git clone https://github.com/junter1989k-ai/colombia-invoice-mcp && cd colombia-invoice-mcp && npx vercel --prod
```

MIT-licensed. Self-hosting removes us from the picture entirely, at no cost and with no loss of function.

---

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

```json
{
  "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](https://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

| Tool | What it does |
|---|---|
| `create_invoice` | Issue a Colombia factura de venta via `POST /invoice`. In: `resolution_number` (your DIAN resolution), `prefix?`, `number?`, `customer{dni,company_name,identity_document_id?,email?}`, `items[{descripcion,cantidad,precioUnitario,iva?,codigo?,unidadMedida?}]`, optional `type_document_id` (default 1 = Factura de Venta Nacional), `operation_type_id` (default 10), `notes`, `send_email`. Out: **cufe** (CUFE), `is_valid`, `number`, `dian_message`, `totals`, `tax_breakdown`. |
| `query_invoice` | Look up a document by **`uuid`** — `GET /documents/{uuid}`. Out: `uuid`, `cufe`, `state`, `number`, `dian_message`, `created_at`. |

## 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>`:

| Tool | Call |
|---|---|
| `create_invoice` | `POST /invoice` |
| `query_invoice` | `GET /documents/{uuid}` |

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

## Develop

```bash
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](https://inv-co.wishpool.app/privacy).

## Sister servers

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

MIT licensed.