Plugin de Claude Code

Dos plugins oficiales en un mismo marketplace — factuarea-mcp conecta Claude Code al servidor MCP de Factuarea, y factuarea-api trae cinco skills para construir la propia integración.

El marketplace de Factuarea publica dos plugins de Claude Code, para dos trabajos distintos. factuarea-mcp es la forma más rápida de conectar Claude Code al servidor MCP de Factuarea: registra el servidor (https://mcp.factuarea.com) e incluye una skill que enseña a Claude a usar bien las tools — scopes, paginación por cursor, el envoltorio de error y el modo de prueba — para que no tengas que configurar nada a mano. factuarea-api sirve a la otra audiencia, quien escribe el código de la integración, y a propósito no declara ningún servidor MCP.

Esta es la forma recomendada de conectar Claude Code. ¿Prefieres configurar el servidor manualmente (otros clientes, entornos headless)? Consulta Conectar un cliente.

Instalación

Añade el marketplace

Registra el catálogo de plugins de Factuarea. Ejecuta esto dentro de Claude Code:

/plugin marketplace add factuarea/claude-plugins

Instala el plugin que necesites

/plugin install factuarea-mcp@factuarea

Claude Code instala el plugin y registra el servidor MCP factuarea. ¿También vas a escribir código de integración? Añade además factuarea-api: los dos son complementarios.

Para obtener actualizaciones más adelante, ejecuta /plugin marketplace update factuarea.

Conecta el servidor

El plugin declara el servidor sin cabecera de auth, así que la ruta recomendada es OAuth — nunca se pega nada secreto en un archivo de configuración.

Autentícate

/mcp

Elige factuarea y selecciona Authenticate. Tu navegador abre la pantalla de consentimiento de Factuarea. El Dynamic Client Registration y PKCE ocurren automáticamente — no hay client id ni secret que pegar.

Aprueba

En la pantalla de consentimiento seleccionas la empresa, el entorno (producción o prueba) y los scopes que concedes. Los scopes sensibles (borrados, invoices:void) están marcados y no vienen premarcados. Claude Code almacena el token y lo refresca de forma transparente.

Úsalo

Pide a Claude que trabaje con tus datos de Factuarea — "lista las facturas impagadas de este trimestre en modo de prueba", "crea un borrador de factura para Acme S.L.", "comprueba la cadena VeriFactu". La skill se carga automáticamente; también puedes invocarla explícitamente:

/factuarea-mcp:factuarea-mcp

Conectar con una API key en su lugar

Para entornos headless, o cuando ya tienes una clave fact_, conecta con una cabecera estática en lugar de OAuth:

claude mcp add --transport http factuarea https://mcp.factuarea.com \
  --header "Authorization: Bearer fact_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Usa una clave fact_test_ para apuntar al sandbox aislado. La superficie de la API es idéntica — solo el prefijo cambia el entorno. Con una cabecera de clave no necesitas el flujo OAuth; la clave autentica cada petición.

Qué incluye `factuarea-mcp`

El servidor MCP

La declaración del servidor factuarea (https://mcp.factuarea.com, transporte HTTP), para que Claude pueda llamar directamente a todas las tools de Factuarea.

Una skill de guía

Una skill que da a Claude el contexto para usar bien las tools — la política de canal, los dominios de tools y sus scopes, la identidad UUID v7, la paginación por cursor, el envoltorio de error y el modo de prueba.

El plugin factuarea-api

Una instalación aparte y más ligera para escribir la propia integración — cinco skills, y ninguna declaración de servidor MCP: ni OAuth ni tools cargadas.

La skill de guía conoce la política de canal (una API key alcanza las 391 tools; OAuth usa las 305 curadas, sin conceder nunca verifactu:write, los scopes de FacturaE, Pagos ni gestoría/escritura de cuenta, ni la operación GDPR de olvido de firma a apps de terceros), cómo el plan/módulo y los feature flags acotan aún más tools/list, y que los cambios de estado son tools discretas (mark_invoice_as_paid, void_invoice, accept_quote…), no un genérico change_status.

Construir la integración: el plugin `factuarea-api`

El plugin anterior sirve para operar tu cuenta mediante tools MCP. Un segundo plugin cubre el trabajo contrario: escribir el código que llama a la REST API desde tu propio backend:

/plugin install factuarea-api@factuarea

No declara ningún servidor MCP, y eso es lo que lo hace barato de tener instalado: ni consentimiento OAuth ni superficie de tools cargada en la sesión. Sus cinco skills se cargan según la tarea que tengas entre manos y se apoyan en los SDKs oficiales, en la especificación viva y en esta documentación.

Skill	Se carga cuando la tarea es…	Qué cubre
`factuarea-api`	Empezar, o preguntar qué admite la API, cómo funciona la autenticación o qué dice la documentación	El punto de entrada: diez reglas de oro, las dos cabeceras de autenticación admitidas y el prefijo que decide el entorno, búsqueda local en esta documentación con `factuarea docs`, y recetas que enrutan a las cuatro skills siguientes
`factuarea-implement`	Montar el cliente y hacer las primeras llamadas	Elegir entre el SDK de TypeScript y el de PHP, resolver la clave desde el entorno, el envoltorio `data`, la paginación por cursor, el `Idempotency-Key` en las escrituras y empezar en el sandbox
`factuarea-webhooks`	Escribir o arreglar el endpoint que recibe las entregas	Verificación HMAC de `Factuarea-Signature` sobre el cuerpo crudo, comparación en tiempo constante, deduplicación por `Factuarea-Event-Id`, un 2xx rápido con el trabajo pesado diferido, la ventana de gracia de la rotación y las pruebas en local con `factuarea listen`
`factuarea-audit`	Revisar una integración que ya existe	Seis familias de reglas — verificación de firma, idempotencia en las escrituras, exposición de la API key, manejo de errores por `code`, límites de peticiones y ciclo de vida del documento — reportando cada hallazgo con una severidad, un `fichero:línea` y la corrección concreta
`factuarea-upgrade`	Realinear tras un cambio de contrato o de SDK	Desalineación entre el código y la especificación viva, la versión fijada del SDK frente a la última publicada, y un informe que separa los cambios que rompen de los aditivos, en el orden en que aplicarlos

Los dos plugins son complementarios, no alternativas. factuarea-mcp lee y actúa sobre tus datos mediante tools; factuarea-api nunca llama a la API por ti — escribe y revisa el código que sí lo hace. Los equipos que construyen una integración suelen instalar ambos. También puedes generar tú mismo un cliente a partir de la especificación OpenAPI.

Resolución de problemas

Síntoma	Causa	Solución
Una tool devuelve `401`	No estás autenticado, o la clave/token caducó.	Ejecuta `/mcp` → factuarea → Authenticate para (re)iniciar OAuth, o revisa tu cabecera de API key.
`insufficient_scope` (`403`)	La credencial carece del scope que requiere la tool.	Vuelve a autenticarte y aprueba el scope, o usa una clave que lo tenga. Recuerda que `verifactu:write` y la tool de olvido de firma son solo para API key.
Una tool que esperabas no aparece	`tools/list` se filtra por tus scopes y feature flags.	Concede el scope (o usa una clave más amplia); confirma que el canal de la credencial puede alcanzarla (OAuth excluye las tools de solo API key). Esto es lo esperado, no un bug.
`addon_not_active` (`-32007`)	La empresa no tiene un plan de Factuarea activo que incluya acceso a la API (p. ej. un trial caducado).	Contrata o renueva un plan desde el dashboard; toda la superficie MCP requiere un plan activo.
`429` con `Retry-After`	Se alcanzó un bucket de límite de peticiones.	Espera los segundos de `Retry-After` antes de reintentar — no insistas sin parar.

Consulta Errores y límites de peticiones para la tabla completa de códigos.