Pagai MCP server

Emite facturas, genera links de pago y revisa cobros desde Claude, ChatGPT, Cursor o cualquier cliente compatible con MCP.

Instalación

Se distribuye por npm. Necesitas Node.js 18+.

Claude Code / Cursor — un comando

claude mcp add pagai --env PAGAI_API_KEY=fai_tu_key -- npx -y @pagai/mcp

Claude Desktop y cualquier otro cliente MCP

Añade el bloque a la config de tu cliente. En Claude Desktop está en Configuración → Desarrollador → Editar configuración:

{
  "mcpServers": {
    "pagai": {
      "command": "npx",
      "args": ["-y", "@pagai/mcp"],
      "env": { "PAGAI_API_KEY": "fai_tu_key" }
    }
  }
}

Reinicia el cliente después de guardar.

Para desarrollo local, apunta al archivo en vez de a npm:

claude mcp add pagai --env PAGAI_API_KEY=fai_tu_key -- node /ruta/a/factur-ai/mcp/server/index.js

De dónde sale la API key

Dashboard de Pagai → Configuración → API keys → Crear key. Se muestra una sola vez; si la pierdes, crea otra.

Los scopes por defecto no incluyen payments:write ni invoices:write. Si quieres usar mark_invoice_paid, marca esos scopes al crear la key. Si te falta uno, el error te dice exactamente cuál en details.required_scope.

Qué puedes pedirle

| Ejemplo | Herramienta | |---|---| | "Cóbrale $50.000 a [email protected] por el diseño web, vence en 30 días" | create_invoice | | "Mándame un link de pago por $30.000" | create_payment_link | | "¿Qué tengo por cobrar?" / "Muéstrame las vencidas" | list_invoices | | "¿Me pagó Juan?" | get_invoice_status | | "Juan me transfirió, márcala pagada" | mark_invoice_paid | | "Recuérdale a Juan que me pague" | send_reminder |

Son seis herramientas y no veinticinco a propósito: las definiciones se pagan en el contexto del modelo antes de que leas nada, y un catálogo grande empeora la elección de herramienta. Lo que falta (webhooks, carga masiva, DTE) se hace por la REST API, que es la superficie completa.

Seguridad

El servidor corre en tu máquina y habla HTTPS con la API de Pagai. No tiene acceso a la base de datos: puede hacer exactamente lo que permita tu API key, ni más. Para limitarlo, crea una key con menos scopes — por ejemplo solo invoices:read si quieres que el agente pueda consultar pero no emitir.

Los reintentos son seguros: el servidor genera un Idempotency-Key por operación, así que un timeout seguido de reintento no emite la factura dos veces.

Desarrollo

npm install
node server/index.js   # arranca en stdio
npm publish            # publica en npm (requiere 2FA o token con bypass)

Apunta a otro entorno con PAGAI_API_URL (por defecto https://api.pagai.cl/api/v1/external).

El contrato de errores está en docs/integration-errors.md: cada fallo trae un code estable y un retry, y el servidor los pasa tal cual al modelo.