Servidor MCP
El servidor MCP de Frihet implementa el Model Context Protocol para que asistentes de IA puedan interactuar directamente con tu ERP. Crear facturas, registrar gastos, consultar clientes o gestionar presupuestos — todo desde tu IDE o terminal, en lenguaje natural.
Version actual: 1.6.0 | 62 herramientas | 11 recursos | 10 prompts | Output estructurado | Compatible con 30+ agentes de IA.
Tu: "Crea una factura para TechStart SL, 40 horas de consultoria a 75 EUR/hora, vencimiento 1 marzo"
Claude: Hecho. Factura INV-2026-089 creada. Total: 3.000,00 EUR + 21% IVA = 3.630,00 EUR.
Que esperar (y que no)
El servidor MCP es un puente stateless entre tu asistente de IA y la API REST de Frihet. Cada llamada de herramienta se traduce en una peticion HTTP a la API.
Lo que SI hace:
- CRUD completo sobre facturas, gastos, clientes, productos, presupuestos y webhooks
- Busqueda de facturas por nombre de cliente
- Acceso a datos de referencia (tipos impositivos, calendario fiscal, categorias)
- Flujos de trabajo guiados (cierre mensual, preparacion fiscal, seguimiento de morosos)
Lo que NO hace:
- OCR de documentos (eso lo hace el asistente IA dentro de la app)
- Generacion de PDFs (usa la API REST directamente:
GET /v1/invoices/:id/pdf) - Procesamiento de pagos (los cobros se gestionan via Stripe Connect en la app)
Requisitos
- Cuenta de Frihet con acceso a la API (planes de pago)
- API key generada desde el panel
Obtener la API key
- Inicia sesion en app.frihet.io
- Ve a Ajustes > Desarrolladores > API Keys
- Pulsa Crear clave de API
- Copia la clave (empieza por
fri_) — solo se muestra una vez
Instalacion
Universal (30+ agentes)
La forma mas rapida de instalar el servidor MCP y el skill de negocio:
npx skills add Frihet-io/frihet-mcp
Funciona con Claude Code, Cursor, Copilot, Codex, Windsurf, Gemini CLI, Goose, Roo Code, y 30+ agentes mas.
MCP Registry
El servidor esta registrado como io.frihet/erp en el MCP Registry oficial. Los clientes MCP compatibles con el registro pueden descubrirlo e instalarlo automaticamente por su nombre canonico.
npx directo
npx -y @frihet/mcp-server@latest
No necesitas instalar nada globalmente. npx descarga y ejecuta la ultima version automaticamente.
Configuracion manual
Hay dos modos de conexion: local (el servidor se ejecuta en tu maquina via npx) y remoto (conexion directa a mcp.frihet.io, sin instalar nada).
Local (stdio)
{
"mcpServers": {
"frihet": {
"command": "npx",
"args": ["-y", "@frihet/mcp-server@latest"],
"env": {
"FRIHET_API_KEY": "fri_tu_clave_aqui"
}
}
}
}
Remoto (streamable-http)
{
"mcpServers": {
"frihet": {
"type": "streamable-http",
"url": "https://mcp.frihet.io/mcp",
"headers": {
"Authorization": "Bearer fri_tu_clave_aqui"
}
}
}
}
Configuracion por cliente
La estructura JSON es identica en todos los clientes. Solo cambia la ubicacion del fichero de configuracion.
| Cliente | Fichero de configuracion |
|---|---|
| Claude Code | ~/.claude/mcp.json |
| Claude Desktop | ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) |
| Cursor | .cursor/mcp.json o ~/.cursor/mcp.json |
| Windsurf | ~/.windsurf/mcp.json |
| Cline | Configuracion de VS Code o .cline/mcp.json |
| Codex CLI | ~/.codex/config.toml (seccion MCP) |
Si usas Claude Code, puedes anadir el servidor con un solo comando:
claude mcp add frihet -- npx -y @frihet/mcp-server@latest
Despues configura la variable FRIHET_API_KEY en el fichero ~/.claude/mcp.json resultante.
Variables de entorno
| Variable | Requerida | Valor por defecto |
|---|---|---|
FRIHET_API_KEY | Si | -- |
FRIHET_API_URL | No | https://api.frihet.io/v1 |
FRIHET_MCP_DEBUG | No | 0 |
FRIHET_API_URLes util si apuntas a un entorno de staging o una instancia personalizada. Debe serhttps://con un hostname bajofrihet.io.FRIHET_MCP_DEBUG=1activa logs de nivel debug (util para diagnosticar problemas).
Flujo OAuth
El servidor MCP soporta autenticacion OAuth ademas de API key manual. Cuando un cliente MCP inicia el flujo OAuth:
- El usuario se autentica via Firebase Auth (email, Google, GitHub o Microsoft)
- El cliente envia el token de sesion a
POST /api/oauth/api-key - El servidor provisiona una nueva clave
fri_xxx...etiquetada "MCP OAuth" con expiracion de 365 dias - La clave se usa automaticamente para las llamadas subsiguientes
Esto permite a los usuarios conectar el servidor MCP sin copiar claves manualmente.
Herramientas disponibles (62)
El servidor expone 62 herramientas organizadas en 10 categorias. Cada herramienta incluye output estructurado (outputSchema + structuredContent) para que los asistentes puedan parsear respuestas de forma fiable, ademas de anotaciones de seguridad y contenido. Bilingue (EN/ES).
Facturas (12 herramientas)
| Herramienta | Descripcion | Parametros clave |
|---|---|---|
list_invoices | Lista facturas con paginacion | limit, offset, status, clientId, from, to |
get_invoice | Obtiene una factura por ID | id |
create_invoice | Crea una factura con lineas de detalle | clientName, items[] (description, quantity, unitPrice), status, dueDate, notes, taxRate, irpfRate |
update_invoice | Actualiza campos de una factura (parcial) | id, y cualquier campo a modificar |
delete_invoice | Elimina una factura permanentemente | id |
search_invoices | Busca facturas por nombre de cliente | clientName, limit, offset |
send_invoice | Envia una factura por email | id, recipientEmail, customMessage, locale |
mark_invoice_paid | Marca una factura como pagada | id, paidDate (opcional) |
get_invoice_pdf | Descarga el PDF de una factura | id |
get_invoice_einvoice | Genera e-factura EN16931 (XML) | id |
create_credit_note | Crea una factura rectificativa | id, reason, reasonDescription, fullCredit |
apply_late_fee | Aplica recargo por demora | id, amount (opcional, auto-calcula si se omite) |
Estados posibles de factura: draft, sent, partial, paid, overdue, cancelled
Gastos (5 herramientas)
| Herramienta | Descripcion | Parametros clave |
|---|---|---|
list_expenses | Lista gastos con paginacion | limit, offset, category, from, to |
get_expense | Obtiene un gasto por ID | id |
create_expense | Registra un nuevo gasto | description, amount, category, date, vendor, taxDeductible |
update_expense | Modifica un gasto existente (parcial) | id, y cualquier campo a modificar |
delete_expense | Elimina un gasto permanentemente | id |
Clientes (5 herramientas)
| Herramienta | Descripcion | Parametros clave |
|---|---|---|
list_clients | Lista todos los clientes | limit, offset, stage, from, to |
get_client | Obtiene un cliente por ID | id |
create_client | Registra un nuevo cliente | name, email, phone, taxId, address, fiscalZone, clientType, stage |
update_client | Actualiza datos de un cliente (parcial) | id, y cualquier campo a modificar |
delete_client | Elimina un cliente permanentemente | id |
CRM (8 herramientas)
Herramientas para gestionar contactos, actividades y notas vinculados a un cliente.
| Herramienta | Descripcion | Parametros clave |
|---|---|---|
list_client_contacts | Lista personas de contacto de un cliente | clientId, limit |
create_client_contact | Crea un contacto para un cliente | clientId, name, email, phone, role, isPrimary |
delete_client_contact | Elimina un contacto | clientId, contactId |
list_client_activities | Lista actividades de un cliente | clientId, limit |
log_client_activity | Registra una actividad manual | clientId, type (call/email/meeting/note_added/task), title, description |
list_client_notes | Lista notas de un cliente | clientId, limit |
create_client_note | Crea una nota para un cliente | clientId, content |
delete_client_note | Elimina una nota | clientId, noteId |
Productos (5 herramientas)
| Herramienta | Descripcion | Parametros clave |
|---|---|---|
list_products | Lista productos y servicios | limit, offset, isActive |
get_product | Obtiene un producto por ID | id |
create_product | Crea un producto o servicio | name, unitPrice, description, sku, taxRate, irpfRate |
update_product | Modifica un producto existente (parcial) | id, y cualquier campo a modificar |
delete_product | Elimina un producto permanentemente | id |
Presupuestos (6 herramientas)
| Herramienta | Descripcion | Parametros clave |
|---|---|---|
list_quotes | Lista presupuestos | limit, offset, status, clientId, from, to |
get_quote | Obtiene un presupuesto por ID | id |
create_quote | Crea un presupuesto para un cliente | clientName, items[] (description, quantity, unitPrice), validUntil, notes, status |
update_quote | Modifica un presupuesto (parcial) | id, y cualquier campo a modificar |
delete_quote | Elimina un presupuesto permanentemente | id |
send_quote | Envia un presupuesto por email | id, recipientEmail, customMessage, locale |
Estados posibles de presupuesto: draft, sent, accepted, rejected, expired
Proveedores (5 herramientas)
| Herramienta | Descripcion | Parametros clave |
|---|---|---|
list_vendors | Lista proveedores | limit, offset |
get_vendor | Obtiene un proveedor por ID | id |
create_vendor | Registra un nuevo proveedor | name, email, phone, taxId, address |
update_vendor | Modifica un proveedor existente (parcial) | id, y cualquier campo a modificar |
delete_vendor | Elimina un proveedor permanentemente | id |
Inteligencia (4 herramientas)
Herramientas de analisis y contexto para que el asistente entienda la situacion del negocio.
| Herramienta | Descripcion | Parametros clave |
|---|---|---|
get_business_context | Contexto completo del negocio (perfil, metricas, configuracion) | — |
get_monthly_summary | Resumen financiero del mes (ingresos, gastos, impuestos) | month (YYYY-MM, opcional) |
get_quarterly_taxes | Preparacion fiscal trimestral (preview Modelo 303/130) | quarter (YYYY-Q1, opcional), fiscalZone |
duplicate_invoice | Duplica una factura existente como borrador | id |
Anticipos / Depositos (7 herramientas)
| Herramienta | Descripcion | Parametros clave |
|---|---|---|
list_deposits | Lista anticipos con paginacion | limit, offset, clientId, status, from, to |
get_deposit | Obtiene un anticipo por ID | id |
create_deposit | Crea un anticipo para un cliente | clientId, amount, description, date, notes |
update_deposit | Modifica un anticipo existente (parcial) | id, y cualquier campo a modificar |
delete_deposit | Elimina un anticipo permanentemente | id |
apply_deposit | Aplica un anticipo a una factura existente | depositId, invoiceId, amount (opcional, aplica total si se omite) |
refund_deposit | Registra la devolucion de un anticipo | id, refundDate (opcional), notes |
Webhooks (5 herramientas)
| Herramienta | Descripcion | Parametros clave |
|---|---|---|
list_webhooks | Lista webhooks configurados | limit, offset |
get_webhook | Obtiene configuracion de un webhook | id |
create_webhook | Registra un endpoint de webhook | url, events[], active, secret |
update_webhook | Modifica un webhook existente | id, y cualquier campo a modificar |
delete_webhook | Elimina un webhook permanentemente | id |
Consulta Webhooks para la lista completa de 27 eventos disponibles, formato del payload y verificacion HMAC.
Recursos disponibles (11)
Los recursos MCP proporcionan datos de referencia y contexto en tiempo real. Los recursos estaticos estan siempre disponibles; los dinamicos requieren autenticacion con API key.
Recursos estaticos (7)
| Recurso | URI | Descripcion |
|---|---|---|
| Esquema API | frihet://api/schema | Resumen de endpoints, autenticacion, rate limits y codigos de error |
| Tipos impositivos | frihet://tax/rates | IVA (21/10/4%), IGIC (7/3/0%), IPSI, intracomunitario, IRPF (15%/7%) |
| Calendario fiscal | frihet://tax/calendar | Fechas de presentacion trimestral (Modelo 303, 130, 420, 390) |
| Categorias de gasto | frihet://config/expense-categories | 8 categorias con reglas de deducibilidad y tratamiento fiscal |
| Estados de factura | frihet://config/invoice-statuses | Flujo de estados (borrador, enviada, pagada, vencida, anulada) con triggers |
| Divisas | frihet://config/currencies | 40 divisas soportadas con simbolos, decimales y formato |
| Paises | frihet://config/countries | 61 paises con zona fiscal y tipo impositivo por defecto |
Recursos dinamicos (4)
Estos recursos devuelven datos en tiempo real de tu cuenta. Solo se registran cuando la conexion esta autenticada.
| Recurso | URI | Descripcion |
|---|---|---|
| Perfil de negocio | frihet://business-profile | Datos fiscales, zona fiscal, divisa y configuracion de tu empresa |
| Snapshot mensual | frihet://monthly-snapshot | Resumen financiero del mes en curso (ingresos, gastos, impuestos) |
| Facturas vencidas | frihet://overdue-invoices | Lista de facturas vencidas con importes y dias de retraso |
| Limites del plan | frihet://status/plan-limits | Plan actual, uso de facturas/escaneos/mensajes IA y limites |
Prompts disponibles (10)
Los prompts son flujos de trabajo guiados que el asistente ejecuta paso a paso. Se invocan por nombre.
| Prompt | Descripcion | Parametros |
|---|---|---|
monthly-close | Cierre mensual: revisa facturas impagadas, categoriza gastos, verifica obligaciones fiscales, genera resumen | month (opcional) |
onboard-client | Alta de cliente: determina tipo impositivo segun ubicacion, crea registro, genera presupuesto de bienvenida | clientName, country, region |
quarterly-tax-prep | Preparacion fiscal trimestral: recopila facturas, calcula IVA/IGIC, genera preview del Modelo 303/130 | quarter, fiscalZone |
overdue-followup | Seguimiento de morosos: identifica facturas vencidas, agrupa por cliente, redacta mensajes de cobro | — |
expense-batch | Procesamiento de gastos en lote: categoriza, aplica impuestos, verifica deducibilidad, crea con confirmacion | fiscalZone |
new-client-invoice | Alta de cliente + primera factura en un solo flujo | clientName, country |
expense-report | Informe de gastos agrupado por categoria con totales y deducibilidad | month (opcional) |
year-end-close | Cierre anual: revision completa del ejercicio fiscal | year |
cash-flow-forecast | Prevision de flujo de caja a 3 meses basada en facturas y gastos recurrentes | months (opcional) |
invoice-aging-review | Analisis de antigueedad de facturas por cobrar (aging buckets) | — |
Puedes invocar un prompt directamente: "Ejecuta el cierre mensual de febrero" o "Prepara los impuestos del Q1".
Ejemplos de uso
Estas son peticiones reales en lenguaje natural que el asistente traduce a llamadas de herramientas MCP.
Crear una factura
"Crea una factura para Acme SL con 10 horas de consultoria a 95 EUR/hora, vencimiento 15 de marzo"
El asistente llama a create_invoice con clientName: "Acme SL", una linea de detalle (10 x 95) y dueDate: "2026-03-15". Calcula el total automaticamente.
Registrar un gasto
"Registra un gasto de 59.99 EUR en Adobe Creative Cloud, categoria software, deducible"
Llama a create_expense con description, amount: 59.99, category: "software" y taxDeductible: true.
Buscar facturas de un cliente
"Busca todas las facturas de TechStart SL"
Llama a search_invoices con clientName: "TechStart SL" y devuelve las coincidencias con sus totales y estados.
Consultar morosos
"Muestrame todas las facturas sin pagar"
Llama a list_invoices y filtra por status: "sent" o "overdue", mostrando las vencidas ordenadas por importe.
Dar de alta un cliente
"Nuevo cliente: Design Studio SL, NIF B87654321, email hola@designstudio.es, Madrid 28001"
Llama a create_client con nombre, NIF, email y direccion.
Configurar automatizacion
"Crea un webhook para notificar a https://mi-app.com/hook cuando se pague una factura"
Llama a create_webhook con url y events: ["invoice.paid"].
Actualizar un producto
"Sube el precio de la hora de consultoria a 85 EUR"
Llama a update_product con el id del producto y unitPrice: 85. Solo se modifica el campo indicado.
Observabilidad
El servidor MCP v1.6.0 incluye logging estructurado y metricas de herramientas.
Logging estructurado
Todos los logs se emiten como JSON a stderr (MCP usa stdout para mensajes del protocolo). Cada entrada incluye:
level:debug,info,warn,errorservice: siemprefrihet-mcptimestamp: ISO 8601tool: nombre de la herramienta (cuando aplica)operation: tipo de operacion (tool_call,api_call,api_retry,startup,shutdown_metrics)durationMs: tiempo de ejecucion en milisegundoserror: detalles del error (message, code, statusCode)
Activa los logs de debug con FRIHET_MCP_DEBUG=1.
Metricas de herramientas
El servidor registra en memoria las llamadas a cada herramienta: numero de invocaciones, errores y duracion media. Al cerrar el servidor (SIGINT/SIGTERM), se emite un resumen:
{
"level": "info",
"message": "Shutdown after 3600s — 42 calls, 1 errors",
"operation": "shutdown_metrics",
"metadata": {
"tools": {
"list_invoices": { "calls": 15, "errors": 0, "avgMs": 230 },
"create_invoice": { "calls": 8, "errors": 1, "avgMs": 450 }
},
"uptime": 3600
}
}
Rate-limit retry automatico
Cuando la API responde con 429, el servidor reintenta automaticamente con backoff exponencial (hasta 3 reintentos). Los reintentos se registran en el log:
{
"level": "warn",
"message": "Rate limited, retrying GET /invoices (attempt 2, delay 2000ms)",
"operation": "api_retry"
}
No necesitas gestionar el rate limiting manualmente — el servidor lo hace por ti.
Transporte
El servidor MCP de Frihet soporta dos modos de transporte. Ambos exponen las mismas 62 herramientas, 11 recursos y 10 prompts.
Local (stdio)
El servidor se ejecuta como proceso local en tu maquina. La comunicacion entre el cliente MCP y el servidor usa entrada/salida estandar (stdin/stdout).
- Requiere: Node.js instalado (se descarga automaticamente via
npx) - Ventaja: Menor latencia, funciona sin conexion a internet (excepto para las llamadas a la API)
- Caso de uso: Desarrollo diario, uso intensivo, entornos corporativos con restricciones de red
Remoto (streamable-http)
El servidor se ejecuta en Cloudflare Workers. Tu cliente MCP se conecta directamente a https://mcp.frihet.io/mcp via HTTP.
- Requiere: Solo conexion a internet
- Ventaja: Sin instalacion local, sin dependencias, funciona en cualquier dispositivo
- Caso de uso: Configuracion rapida, equipos que prefieren no instalar paquetes, clientes que solo soportan transporte HTTP
Si tu cliente MCP no soporta streamable-http (algunos clientes antiguos solo soportan stdio), usa el modo local.
Manejo de errores
Rate limiting
La API permite 100 peticiones por minuto por clave. Si se excede el limite, el servidor devuelve un error 429 con el tiempo de espera en retryAfter.
El servidor MCP gestiona automaticamente el rate limiting con backoff exponencial: reintenta la peticion despues de esperar el tiempo indicado, sin intervencion del usuario. Maximo 3 reintentos.
Errores de autenticacion
| Codigo | Causa | Solucion |
|---|---|---|
401 | API key invalida, expirada o no proporcionada | Verifica que la clave en tu configuracion empieza por fri_ y no ha expirado |
403 | La clave no tiene permisos para este recurso | Genera una nueva clave con los permisos necesarios |
Otros errores
| Codigo | Descripcion |
|---|---|
400 | Parametros incorrectos o campos requeridos faltantes |
404 | El recurso solicitado no existe |
408 | Timeout de la peticion (30 segundos) |
413 | El cuerpo de la peticion excede 1 MB |
422 | Datos validos pero no procesables (ej: perfil fiscal no configurado) |
429 | Limite de peticiones excedido (se reintenta automaticamente) |
500 | Error interno del servidor |
Todos los errores devuelven un mensaje descriptivo bilingue (EN/ES) para que el asistente pueda comunicar el problema al usuario de forma clara.
Limites
| Concepto | Valor |
|---|---|
| Peticiones por minuto | 100 por API key |
| Resultados por pagina | 100 maximo (50 por defecto) |
| Cuerpo de peticion | 1 MB maximo |
| Payload de webhook | 100 KB maximo |
| Webhooks por cuenta | 20 maximo |
| Timeout de peticion | 30 segundos |
| Reintentos por rate limit | 3 maximo |
Diferencia con la API REST
| Servidor MCP | API REST | |
|---|---|---|
| Dirigido a | Asistentes de IA (Claude, Cursor, Windsurf) | Aplicaciones, scripts, integraciones |
| Comunicacion | Lenguaje natural a traves del cliente MCP | HTTP/JSON directo |
| Autenticacion | Variable de entorno en la config del cliente (u OAuth) | Cabecera X-API-Key o Authorization: Bearer |
| Formato | Texto formateado + output estructurado para el asistente | JSON crudo |
| Rate limiting | Gestionado automaticamente (backoff exponencial, 3 reintentos) | Manual (el consumidor debe implementar reintentos) |
| Observabilidad | Logging estructurado + metricas por herramienta | Logs de peticion via X-Request-Id |
| Caso de uso | Hablar con tu ERP desde el IDE | Construir integraciones programaticas |
Internamente, el servidor MCP traduce cada llamada de herramienta en una peticion a la API REST. No duplica logica — es un puente stateless.
Desarrollo
Para contribuir o ejecutar el servidor en modo desarrollo:
git clone https://github.com/Frihet-io/frihet-mcp.git
cd frihet-mcp
npm install
npm run build
Ejecutar localmente:
FRIHET_API_KEY=fri_tu_clave node dist/index.js
Ejecutar con logs de debug:
FRIHET_MCP_DEBUG=1 FRIHET_API_KEY=fri_tu_clave node dist/index.js
Probar con el MCP Inspector:
npx @modelcontextprotocol/inspector node dist/index.js
Recursos relacionados
- API REST — Referencia completa de endpoints, autenticacion y codigos de error
- Webhooks — Eventos disponibles, verificacion HMAC-SHA256 y politica de reintentos
- Skill para Claude Code — Capa de inteligencia de negocio sobre el servidor MCP
- Codigo fuente (GitHub) — Repositorio del servidor MCP
- Paquete npm —
@frihet/mcp-server@1.6.0 - MCP Registry —
io.frihet/erp - Endpoint remoto — Servidor MCP alojado en Cloudflare Workers
- Especificacion MCP — Documentacion del protocolo