MCP Alegra

📋 Índice

Descripción General
Inicio Rápido
Configuración de Clientes MCP
Herramientas Disponibles
API HTTP
Autenticación

🎯 Descripción General

Alegra MCP Public es un servidor orquestador que implementa el Model Context Protocol (MCP) para unificar múltiples servidores MCP privados de Alegra en un único punto de acceso público. Permite a los clientes MCP acceder a herramientas de gestión empresarial como inventarios, contactos, ingresos, bancos, pagos, retenciones, entre otros, a través de una interfaz estandarizada.

Importante: La funcionalidad aún se encuentra en modo beta por lo que su uso debe ser prudente.

Características Principales

✅ Orquestación por Grupo: Puedes seleccionar uno o varios grupos de herramientas
✅ Transporte via servidor: Soporta HTTP
✅ Autenticación Segura: Sistema de tokens Basic

🚀 Inicio Rápido

Para Usuarios (Configuración de Cliente)

El servidor MCP de Alegra está disponible públicamente en:

Producción: https://mcp.alegra.com/mcp

Requisitos

Token de Autenticación: Necesitas un token válido de Alegra
Cliente MCP Compatible: Como Cursor IDE, etc.

🔧 Configuración de Clientes MCP

Cursor IDE

Crea o edita el archivo .cursor/mcp_settings.json en tu proyecto:

{
  "mcpServers": {
    "alegra-mcp": {
      "type": "streamable-http",
      "streamable": true,
      "url": "https://mcp.alegra.com/mcp",
      "headers": {
        "Authorization": "Basic TU_TOKEN_AQUI",
        "mcp-groups": "invoices,items,contacts,banks,income-payments,resolutions,currencies,sellers,taxes,retentions"
      }
    }
  }
}

Otros Clientes MCP

Para cualquier cliente que soporte HTTP/SSE:

URL: https://mcp.alegra.com/mcp
Method: POST (para llamadas) / GET (para SSE)
Headers:
  Authorization: Basic TU_TOKEN_AQUI
  Content-Type: application/json

🛠️ Herramientas Disponibles

El servidor orquesta las siguientes herramientas MCP:

📦 Items Management

Gestión de inventario y productos.

Herramientas:

items__getItems: Listar elementos del inventario
items__getItemsByName: Listar elementos del inventario por nombre

👥 Contactos Management

Gestión de contactos y clientes.

Herramientas:

contacts__getContacts: Listar contactos
contacts__getContactsByName: Listar contactos por nombre

💰 Facturas de venta Managment

Gestión de facturación.

Herramientas:

invoices__getInvoices: Listar facturas
invoices__getInvoiceById: Consultar una factura por su ID
invoices__getInvoiceByNumber: Consultar una factura por su número (ej. NCF o número completo)
invoices__createInvoice: Crear nueva factura
invoices__updateInvoice: Actualizar una factura existente
invoices__deleteInvoice: Eliminar una factura
invoices__getPaymentTypes: Obtener tipos de pago disponibles (Específico para regulaciones de República Dominicana - DOM)

🏦 Banks Management

Gestión de cuentas bancarias y conciliaciones.

Herramientas:

banks__getBanks: Listar cuentas bancarias (con filtros)
banks__getBanksById: Consultar cuenta bancaria por id
banks__getBanksByName: Consultar cuentas bancarias por nombre
banks__createBankAccount: Crear cuenta bancaria
banks__updateBankAccount: Actualizar cuenta bancaria
banks__deleteBankAccount: Eliminar cuenta bancaria

Gestión de conciliaciones.

Herramientas:

banks__getReconciliations: Listar conciliaciones (con filtros)
banks__getReconciliationById: Consultar conciliación por id
banks__createReconciliation: Crear conciliación
banks__deleteReconciliation: Eliminar conciliación

💵 Pagos recibidos / Recibo de caja Managment

Gestión de pagos asociados a ingresos.

Herramientas:

incomePayments__getIncomePayments: Obtener lista de pagos
incomePayments__createIncomePayment: Crear un nuevo pago
incomePayments__updateIncomePayment: Actualizar un pago existente
incomePayments__deleteIncomePayment: Eliminar un pago

📄 Resoluciones / Numeraciones Managment

Gestión de plantillas de numeración y resoluciones.

Herramientas:

resolutions__getResolutionss: Obtener lista de resoluciones (nota: el nombre exacto de la tool es con 'ss' al final)
resolutions__getResolutionById: Obtener una resolución específica por ID
resolutions__getDefaultResolutions: Obtener las resoluciones por defecto para un tipo de documento
resolutions__createResolutions: Crear una nueva resolución
resolutions__updateResolutions: Actualizar una resolución
resolutions__deleteResolutions: Eliminar una resolución

💱 Monedas Managment

Gestión de monedas y divisas de la empresa.

Herramientas:

currencies__getCurrencies: Listar las monedas de la empresa
currencies__getDefaultCurrency: Obtener la moneda principal (por defecto) de la empresa
currencies__createCurrency: Crear una nueva moneda
currencies__updateCurrency: Actualizar una moneda por código
currencies__deleteCurrency: Eliminar una moneda por código

🏪 Vendedores Managment

Gestión de vendedores asociados a las transacciones.

Herramientas:

sellers__getSellers: Obtener lista de vendedores
sellers__createSeller: Crear un nuevo vendedor
sellers__updateSeller: Actualizar un vendedor existente
sellers__deleteSeller: Eliminar un vendedor

🧾 Impuestos Managment

Gestión de impuestos configurados en la cuenta.

Herramientas:

taxes__getTaxes: Obtener impuestos
taxes__createTax: Crear un nuevo impuesto
taxes__updateTax: Actualizar un impuesto existente
taxes__deleteTax: Eliminar un impuesto

🛡️ Retenciones Managment

Gestión de retenciones fiscales.

Herramientas:

retentions__getRetentions: Obtener lista de retenciones
retentions__createRetention: Crear una nueva retención
retentions__updateRetention: Actualizar una retención existente
retentions__deleteRetention: Eliminar una retención

🌐 API HTTP

Endpoints Principales

`POST /mcp`

Ejecuta herramientas MCP o inicializa sesiones.

Headers:

Authorization: Basic TOKEN
Content-Type: application/json
mcp-session-id: [opcional] ID_DE_SESION

Ejemplo - Listar Herramientas:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}

Ejemplo - Ejecutar Herramienta:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "items-get_items",
    "arguments": {
      "limit": 10,
      "offset": 0
    }
  }
}

`GET /mcp`

Establece conexión SSE para streaming.

Headers:

Authorization: Basic TOKEN
mcp-session-id: ID_DE_SESION
Accept: text/event-stream

`DELETE /mcp`

Termina una sesión MCP activa.

Headers:

Authorization: Basic TOKEN
mcp-session-id: ID_DE_SESION

`GET /health`

Endpoint de salud del servidor.

Respuesta:

{
  "success": true,
  "message": "OK"
}

🔐 Autenticación

Autenticación

📚 Recursos Adicionales

Documentación de MCP

Última actualización: Septiembre 2025
Versión: 1.0.0