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.

31 herramientas. 6 recursos. Compatible con los principales clientes MCP.

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.

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 Configuracion > API
Pulsa Crear clave de API
Copia la clave (empieza por fri_) — solo se muestra una vez

Instalacion

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"],
      "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)

tip

Si usas Claude Code, puedes anadir el servidor con un solo comando:

claude mcp add frihet -- npx -y @frihet/mcp-server

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_API_URL es util si apuntas a un entorno de staging o una instancia personalizada.

Herramientas disponibles (31)

El servidor expone 31 herramientas organizadas en 6 recursos. Cada herramienta es bilingue (EN/ES) para que funcione con asistentes en cualquier idioma.

Facturas (6 herramientas)

Herramienta	Descripcion	Parametros clave
`list_invoices`	Lista facturas con paginacion	`limit`, `offset`
`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`
`update_invoice`	Actualiza campos de una factura	`id`, y cualquier campo a modificar
`delete_invoice`	Elimina una factura permanentemente	`id`
`search_invoices`	Busca facturas por nombre de cliente	`clientName`, `limit`, `offset`

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

Gastos (5 herramientas)

Herramienta	Descripcion	Parametros clave
`list_expenses`	Lista gastos con paginacion	`limit`, `offset`
`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	`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`
`get_client`	Obtiene un cliente por ID	`id`
`create_client`	Registra un nuevo cliente	`name`, `email`, `phone`, `taxId`, `address` (street, city, postalCode, country)
`update_client`	Actualiza datos de un cliente	`id`, y cualquier campo a modificar
`delete_client`	Elimina un cliente permanentemente	`id`

Productos (5 herramientas)

Herramienta	Descripcion	Parametros clave
`list_products`	Lista productos y servicios	`limit`, `offset`
`get_product`	Obtiene un producto por ID	`id`
`create_product`	Crea un producto o servicio	`name`, `unitPrice`, `description`, `unit`, `taxRate`, `sku`
`update_product`	Modifica un producto existente	`id`, y cualquier campo a modificar
`delete_product`	Elimina un producto permanentemente	`id`

Presupuestos (5 herramientas)

Herramienta	Descripcion	Parametros clave
`list_quotes`	Lista presupuestos	`limit`, `offset`
`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	`id`, y cualquier campo a modificar
`delete_quote`	Elimina un presupuesto permanentemente	`id`

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

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`

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.

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"].

Transporte

El servidor MCP de Frihet soporta dos modos de transporte. Ambos exponen las mismas 31 herramientas.

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.

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
`413`	El cuerpo de la peticion excede 1 MB
`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

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	Cabecera `X-API-Key` o `Authorization: Bearer`
Formato	Texto formateado para el asistente	JSON crudo
Rate limiting	Gestionado automaticamente (backoff exponencial)	Manual (el consumidor debe implementar reintentos)
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/berthelius/frihet-mcp.git
cd frihet-mcp
npm install
npm run build

Ejecutar localmente:

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
Endpoint remoto — Servidor MCP alojado en Cloudflare Workers
Especificacion MCP — Documentacion del protocolo

Anterior: Webhooks | Siguiente: Skill para Claude Code

Requisitos​

Obtener la API key​

Instalacion​

Local (stdio)​

Remoto (streamable-http)​

Configuracion por cliente​

Variables de entorno​

Herramientas disponibles (31)​

Facturas (6 herramientas)​

Gastos (5 herramientas)​

Clientes (5 herramientas)​

Productos (5 herramientas)​

Presupuestos (5 herramientas)​

Webhooks (5 herramientas)​

Ejemplos de uso​

Crear una factura​

Registrar un gasto​

Consultar morosos​

Dar de alta un cliente​

Configurar automatizacion​

Transporte​

Local (stdio)​

Remoto (streamable-http)​

Manejo de errores​

Rate limiting​

Errores de autenticacion​

Otros errores​

Limites​

Diferencia con la API REST​

Desarrollo​

Recursos relacionados​

Requisitos

Obtener la API key

Instalacion

Local (stdio)

Remoto (streamable-http)

Configuracion por cliente

Variables de entorno

Herramientas disponibles (31)

Facturas (6 herramientas)

Gastos (5 herramientas)

Clientes (5 herramientas)

Productos (5 herramientas)

Presupuestos (5 herramientas)

Webhooks (5 herramientas)

Ejemplos de uso

Crear una factura

Registrar un gasto

Consultar morosos

Dar de alta un cliente

Configurar automatizacion

Transporte

Local (stdio)

Remoto (streamable-http)

Manejo de errores

Rate limiting

Errores de autenticacion

Otros errores

Limites

Diferencia con la API REST

Desarrollo

Recursos relacionados