Saltar al contenido principal

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

  1. Inicia sesion en app.frihet.io
  2. Ve a Ajustes > Desarrolladores > API Keys
  3. Pulsa Crear clave de API
  4. 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.

ClienteFichero 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
ClineConfiguracion de VS Code o .cline/mcp.json
Codex CLI~/.codex/config.toml (seccion MCP)
tip

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

VariableRequeridaValor por defecto
FRIHET_API_KEYSi--
FRIHET_API_URLNohttps://api.frihet.io/v1
FRIHET_MCP_DEBUGNo0
  • FRIHET_API_URL es util si apuntas a un entorno de staging o una instancia personalizada. Debe ser https:// con un hostname bajo frihet.io.
  • FRIHET_MCP_DEBUG=1 activa 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:

  1. El usuario se autentica via Firebase Auth (email, Google, GitHub o Microsoft)
  2. El cliente envia el token de sesion a POST /api/oauth/api-key
  3. El servidor provisiona una nueva clave fri_xxx... etiquetada "MCP OAuth" con expiracion de 365 dias
  4. 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)

HerramientaDescripcionParametros clave
list_invoicesLista facturas con paginacionlimit, offset, status, clientId, from, to
get_invoiceObtiene una factura por IDid
create_invoiceCrea una factura con lineas de detalleclientName, items[] (description, quantity, unitPrice), status, dueDate, notes, taxRate, irpfRate
update_invoiceActualiza campos de una factura (parcial)id, y cualquier campo a modificar
delete_invoiceElimina una factura permanentementeid
search_invoicesBusca facturas por nombre de clienteclientName, limit, offset
send_invoiceEnvia una factura por emailid, recipientEmail, customMessage, locale
mark_invoice_paidMarca una factura como pagadaid, paidDate (opcional)
get_invoice_pdfDescarga el PDF de una facturaid
get_invoice_einvoiceGenera e-factura EN16931 (XML)id
create_credit_noteCrea una factura rectificativaid, reason, reasonDescription, fullCredit
apply_late_feeAplica recargo por demoraid, amount (opcional, auto-calcula si se omite)

Estados posibles de factura: draft, sent, partial, paid, overdue, cancelled

Gastos (5 herramientas)

HerramientaDescripcionParametros clave
list_expensesLista gastos con paginacionlimit, offset, category, from, to
get_expenseObtiene un gasto por IDid
create_expenseRegistra un nuevo gastodescription, amount, category, date, vendor, taxDeductible
update_expenseModifica un gasto existente (parcial)id, y cualquier campo a modificar
delete_expenseElimina un gasto permanentementeid

Clientes (5 herramientas)

HerramientaDescripcionParametros clave
list_clientsLista todos los clienteslimit, offset, stage, from, to
get_clientObtiene un cliente por IDid
create_clientRegistra un nuevo clientename, email, phone, taxId, address, fiscalZone, clientType, stage
update_clientActualiza datos de un cliente (parcial)id, y cualquier campo a modificar
delete_clientElimina un cliente permanentementeid

CRM (8 herramientas)

Herramientas para gestionar contactos, actividades y notas vinculados a un cliente.

HerramientaDescripcionParametros clave
list_client_contactsLista personas de contacto de un clienteclientId, limit
create_client_contactCrea un contacto para un clienteclientId, name, email, phone, role, isPrimary
delete_client_contactElimina un contactoclientId, contactId
list_client_activitiesLista actividades de un clienteclientId, limit
log_client_activityRegistra una actividad manualclientId, type (call/email/meeting/note_added/task), title, description
list_client_notesLista notas de un clienteclientId, limit
create_client_noteCrea una nota para un clienteclientId, content
delete_client_noteElimina una notaclientId, noteId

Productos (5 herramientas)

HerramientaDescripcionParametros clave
list_productsLista productos y servicioslimit, offset, isActive
get_productObtiene un producto por IDid
create_productCrea un producto o servicioname, unitPrice, description, sku, taxRate, irpfRate
update_productModifica un producto existente (parcial)id, y cualquier campo a modificar
delete_productElimina un producto permanentementeid

Presupuestos (6 herramientas)

HerramientaDescripcionParametros clave
list_quotesLista presupuestoslimit, offset, status, clientId, from, to
get_quoteObtiene un presupuesto por IDid
create_quoteCrea un presupuesto para un clienteclientName, items[] (description, quantity, unitPrice), validUntil, notes, status
update_quoteModifica un presupuesto (parcial)id, y cualquier campo a modificar
delete_quoteElimina un presupuesto permanentementeid
send_quoteEnvia un presupuesto por emailid, recipientEmail, customMessage, locale

Estados posibles de presupuesto: draft, sent, accepted, rejected, expired

Proveedores (5 herramientas)

HerramientaDescripcionParametros clave
list_vendorsLista proveedoreslimit, offset
get_vendorObtiene un proveedor por IDid
create_vendorRegistra un nuevo proveedorname, email, phone, taxId, address
update_vendorModifica un proveedor existente (parcial)id, y cualquier campo a modificar
delete_vendorElimina un proveedor permanentementeid

Inteligencia (4 herramientas)

Herramientas de analisis y contexto para que el asistente entienda la situacion del negocio.

HerramientaDescripcionParametros clave
get_business_contextContexto completo del negocio (perfil, metricas, configuracion)
get_monthly_summaryResumen financiero del mes (ingresos, gastos, impuestos)month (YYYY-MM, opcional)
get_quarterly_taxesPreparacion fiscal trimestral (preview Modelo 303/130)quarter (YYYY-Q1, opcional), fiscalZone
duplicate_invoiceDuplica una factura existente como borradorid

Anticipos / Depositos (7 herramientas)

HerramientaDescripcionParametros clave
list_depositsLista anticipos con paginacionlimit, offset, clientId, status, from, to
get_depositObtiene un anticipo por IDid
create_depositCrea un anticipo para un clienteclientId, amount, description, date, notes
update_depositModifica un anticipo existente (parcial)id, y cualquier campo a modificar
delete_depositElimina un anticipo permanentementeid
apply_depositAplica un anticipo a una factura existentedepositId, invoiceId, amount (opcional, aplica total si se omite)
refund_depositRegistra la devolucion de un anticipoid, refundDate (opcional), notes

Webhooks (5 herramientas)

HerramientaDescripcionParametros clave
list_webhooksLista webhooks configuradoslimit, offset
get_webhookObtiene configuracion de un webhookid
create_webhookRegistra un endpoint de webhookurl, events[], active, secret
update_webhookModifica un webhook existenteid, y cualquier campo a modificar
delete_webhookElimina un webhook permanentementeid

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)

RecursoURIDescripcion
Esquema APIfrihet://api/schemaResumen de endpoints, autenticacion, rate limits y codigos de error
Tipos impositivosfrihet://tax/ratesIVA (21/10/4%), IGIC (7/3/0%), IPSI, intracomunitario, IRPF (15%/7%)
Calendario fiscalfrihet://tax/calendarFechas de presentacion trimestral (Modelo 303, 130, 420, 390)
Categorias de gastofrihet://config/expense-categories8 categorias con reglas de deducibilidad y tratamiento fiscal
Estados de facturafrihet://config/invoice-statusesFlujo de estados (borrador, enviada, pagada, vencida, anulada) con triggers
Divisasfrihet://config/currencies40 divisas soportadas con simbolos, decimales y formato
Paisesfrihet://config/countries61 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.

RecursoURIDescripcion
Perfil de negociofrihet://business-profileDatos fiscales, zona fiscal, divisa y configuracion de tu empresa
Snapshot mensualfrihet://monthly-snapshotResumen financiero del mes en curso (ingresos, gastos, impuestos)
Facturas vencidasfrihet://overdue-invoicesLista de facturas vencidas con importes y dias de retraso
Limites del planfrihet://status/plan-limitsPlan 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.

PromptDescripcionParametros
monthly-closeCierre mensual: revisa facturas impagadas, categoriza gastos, verifica obligaciones fiscales, genera resumenmonth (opcional)
onboard-clientAlta de cliente: determina tipo impositivo segun ubicacion, crea registro, genera presupuesto de bienvenidaclientName, country, region
quarterly-tax-prepPreparacion fiscal trimestral: recopila facturas, calcula IVA/IGIC, genera preview del Modelo 303/130quarter, fiscalZone
overdue-followupSeguimiento de morosos: identifica facturas vencidas, agrupa por cliente, redacta mensajes de cobro
expense-batchProcesamiento de gastos en lote: categoriza, aplica impuestos, verifica deducibilidad, crea con confirmacionfiscalZone
new-client-invoiceAlta de cliente + primera factura en un solo flujoclientName, country
expense-reportInforme de gastos agrupado por categoria con totales y deducibilidadmonth (opcional)
year-end-closeCierre anual: revision completa del ejercicio fiscalyear
cash-flow-forecastPrevision de flujo de caja a 3 meses basada en facturas y gastos recurrentesmonths (opcional)
invoice-aging-reviewAnalisis de antigueedad de facturas por cobrar (aging buckets)
tip

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, error
  • service: siempre frihet-mcp
  • timestamp: ISO 8601
  • tool: nombre de la herramienta (cuando aplica)
  • operation: tipo de operacion (tool_call, api_call, api_retry, startup, shutdown_metrics)
  • durationMs: tiempo de ejecucion en milisegundos
  • error: 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
info

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

CodigoCausaSolucion
401API key invalida, expirada o no proporcionadaVerifica que la clave en tu configuracion empieza por fri_ y no ha expirado
403La clave no tiene permisos para este recursoGenera una nueva clave con los permisos necesarios

Otros errores

CodigoDescripcion
400Parametros incorrectos o campos requeridos faltantes
404El recurso solicitado no existe
408Timeout de la peticion (30 segundos)
413El cuerpo de la peticion excede 1 MB
422Datos validos pero no procesables (ej: perfil fiscal no configurado)
429Limite de peticiones excedido (se reintenta automaticamente)
500Error 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

ConceptoValor
Peticiones por minuto100 por API key
Resultados por pagina100 maximo (50 por defecto)
Cuerpo de peticion1 MB maximo
Payload de webhook100 KB maximo
Webhooks por cuenta20 maximo
Timeout de peticion30 segundos
Reintentos por rate limit3 maximo

Diferencia con la API REST

Servidor MCPAPI REST
Dirigido aAsistentes de IA (Claude, Cursor, Windsurf)Aplicaciones, scripts, integraciones
ComunicacionLenguaje natural a traves del cliente MCPHTTP/JSON directo
AutenticacionVariable de entorno en la config del cliente (u OAuth)Cabecera X-API-Key o Authorization: Bearer
FormatoTexto formateado + output estructurado para el asistenteJSON crudo
Rate limitingGestionado automaticamente (backoff exponencial, 3 reintentos)Manual (el consumidor debe implementar reintentos)
ObservabilidadLogging estructurado + metricas por herramientaLogs de peticion via X-Request-Id
Caso de usoHablar con tu ERP desde el IDEConstruir 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


Anterior: Webhooks | Siguiente: Skill para Claude Code