Plugin de Claude Code

Instala el plugin oficial factuarea-mcp para conectar Claude Code al servidor MCP de Factuarea con un solo comando — la configuración recomendada.

La forma más rápida de conectar Claude Code al servidor MCP de Factuarea es el plugin oficial factuarea-mcp. 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.

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

/plugin install factuarea-mcp@factuarea

Claude Code instala el plugin y registra el servidor MCP factuarea.

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 el plugin

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 15 dominios de tools y sus scopes, la identidad UUID v7, la paginación por cursor, el envoltorio de error y el modo de prueba.

La skill conoce la política de canal (una API key alcanza las 232 tools; OAuth usa las 218 curadas, sin conceder nunca verifactu:write, los scopes de FacturaE 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.

¿Construyes una integración de código contra la REST API en lugar de usar tools? Usa los SDKs oficiales (TypeScript y PHP) o genera 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`)	El add-on de API para desarrolladores de la empresa está inactivo.	Actívalo en el dashboard; toda la superficie MCP lo requiere.
`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.
OAuth dice que la empresa no está permitida	La API pública está en beta privada.	Solicita acceso en info@factuarea.com — consulta Solicitar acceso beta.

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