Plugin de Claude Code

Dos plugins oficials en un mateix marketplace — factuarea-mcp connecta Claude Code al servidor MCP de Factuarea, i factuarea-api porta cinc skills per construir la mateixa integració.

El marketplace de Factuarea publica dos plugins de Claude Code, per a dues feines diferents. factuarea-mcp és la manera més ràpida de connectar Claude Code al servidor MCP de Factuarea: registra el servidor (https://mcp.factuarea.com) i inclou una skill que ensenya a Claude a fer servir bé les tools — scopes, paginació per cursor, l'embolcall d'error i el mode de prova — perquè no hagis de configurar res a mà. factuarea-api serveix l'altra audiència, qui escriu el codi de la integració, i expressament no declara cap servidor MCP.

Aquesta és la manera recomanada de connectar Claude Code. Prefereixes configurar el servidor manualment (altres clients, entorns headless)? Consulta Connectar un client.

Instal·lació

Afegeix el marketplace

Registra el catàleg de plugins de Factuarea. Executa això dins de Claude Code:

/plugin marketplace add factuarea/claude-plugins

Instal·la el plugin que necessitis

/plugin install factuarea-mcp@factuarea

Claude Code instal·la el plugin i registra el servidor MCP factuarea. També escriuràs codi d'integració? Afegeix-hi factuarea-api: tots dos són complementaris.

Per obtenir actualitzacions més endavant, executa /plugin marketplace update factuarea.

Connecta el servidor

El plugin declara el servidor sense capçalera d'auth, així que la ruta recomanada és OAuth — mai s'enganxa res secret en un fitxer de configuració.

Autentica't

/mcp

Tria factuarea i selecciona Authenticate. El teu navegador obre la pantalla de consentiment de Factuarea. El Dynamic Client Registration i PKCE passen automàticament — no hi ha cap client id ni secret per enganxar.

Aprova

A la pantalla de consentiment selecciones l'empresa, l'entorn (producció o prova) i els scopes que concedeixes. Els scopes sensibles (eliminacions, invoices:void) estan marcats i no vénen premarcats. Claude Code emmagatzema el token i el refresca de manera transparent.

Fes-lo servir

Demana a Claude que treballi amb les teves dades de Factuarea — "llista les factures impagades d'aquest trimestre en mode de prova", "crea un esborrany de factura per a Acme S.L.", "comprova la cadena VeriFactu". La skill es carrega automàticament; també la pots invocar explícitament:

/factuarea-mcp:factuarea-mcp

Connectar amb una API key en lloc d'OAuth

Per a entorns headless, o quan ja tens una clau fact_, connecta amb una capçalera estàtica en lloc d'OAuth:

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

Fes servir una clau fact_test_ per apuntar al sandbox aïllat. La superfície de l'API és idèntica — només el prefix canvia l'entorn. Amb una capçalera de clau no necessites el flux OAuth; la clau autentica cada petició.

Què inclou `factuarea-mcp`

El servidor MCP

La declaració del servidor factuarea (https://mcp.factuarea.com, transport HTTP), perquè Claude pugui cridar directament totes les tools de Factuarea.

Una skill de guia

Una skill que dóna a Claude el context per fer servir bé les tools — la política de canal, els dominis de tools i els seus scopes, la identitat UUID v7, la paginació per cursor, l'embolcall d'error i el mode de prova.

El plugin factuarea-api

Una instal·lació a part i més lleugera per escriure la mateixa integració — cinc skills, i cap declaració de servidor MCP: ni OAuth ni tools carregades.

La skill de guia coneix la política de canal (una API key arriba a les 391 tools; OAuth fa servir les 305 curades, sense concedir mai verifactu:write, els scopes de FacturaE, Pagaments ni gestoria/escriptura de compte, ni l'operació GDPR d'oblit de signatura a apps de tercers), com el pla/mòdul i els feature flags acoten encara més tools/list, i que els canvis d'estat són tools discretes (mark_invoice_as_paid, void_invoice, accept_quote…), no un genèric change_status.

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

El plugin anterior serveix per operar el teu compte mitjançant tools MCP. Un segon plugin cobreix la feina contrària: escriure el codi que crida la REST API des del teu propi backend:

/plugin install factuarea-api@factuarea

No declara cap servidor MCP, i això és el que el fa barat de tenir instal·lat: ni consentiment OAuth ni superfície de tools carregada a la sessió. Les seves cinc skills es carreguen segons la tasca que tinguis entre mans i es basen en els SDKs oficials, en l'especificació viva i en aquesta documentació.

Skill	Es carrega quan la tasca és…	Què cobreix
`factuarea-api`	Començar, o preguntar què admet l'API, com funciona l'autenticació o què diu la documentació	El punt d'entrada: deu regles d'or, les dues capçaleres d'autenticació admeses i el prefix que decideix l'entorn, cerca local en aquesta documentació amb `factuarea docs`, i receptes que enruten a les quatre skills següents
`factuarea-implement`	Muntar el client i fer les primeres crides	Triar entre el SDK de TypeScript i el de PHP, resoldre la clau des de l'entorn, l'embolcall `data`, la paginació per cursor, l'`Idempotency-Key` a les escriptures i començar al sandbox
`factuarea-webhooks`	Escriure o arreglar l'endpoint que rep les entregues	Verificació HMAC de `Factuarea-Signature` sobre el cos cru, comparació en temps constant, deduplicació per `Factuarea-Event-Id`, un 2xx ràpid amb la feina pesada diferida, la finestra de gràcia de la rotació i les proves en local amb `factuarea listen`
`factuarea-audit`	Revisar una integració que ja existeix	Sis famílies de regles — verificació de signatura, idempotència a les escriptures, exposició de l'API key, gestió d'errors per `code`, límits de peticions i cicle de vida del document — reportant cada troballa amb una severitat, un `fitxer:línia` i la correcció concreta
`factuarea-upgrade`	Realinear després d'un canvi de contracte o de SDK	Desalineació entre el codi i l'especificació viva, la versió fixada del SDK davant l'última publicada, i un informe que separa els canvis que trenquen dels additius, en l'ordre en què cal aplicar-los

Els dos plugins són complementaris, no alternatives. factuarea-mcp llegeix i actua sobre les teves dades mitjançant tools; factuarea-api no crida mai l'API per tu — escriu i revisa el codi que sí que ho fa. Els equips que construeixen una integració solen instal·lar tots dos. També pots generar tu mateix un client a partir de l'especificació OpenAPI.

Resolució de problemes

Símptoma	Causa	Solució
Una tool retorna `401`	No estàs autenticat, o la clau/token ha caducat.	Executa `/mcp` → factuarea → Authenticate per (re)iniciar OAuth, o revisa la teva capçalera d'API key.
`insufficient_scope` (`403`)	La credencial no té el scope que requereix la tool.	Torna a autenticar-te i aprova el scope, o fes servir una clau que el tingui. Recorda que `verifactu:write` i la tool d'oblit de signatura són només per a API key.
Una tool que esperaves no apareix	`tools/list` es filtra segons els teus scopes i feature flags.	Concedeix el scope (o fes servir una clau més àmplia); confirma que el canal de la credencial pot arribar-hi (OAuth exclou les tools de només API key). Això és l'esperat, no un bug.
`addon_not_active` (`-32007`)	L'empresa no té un pla de Factuarea actiu que inclogui accés a l'API (p. ex. un trial caducat).	Contracta o renova un pla des del dashboard; tota la superfície MCP requereix un pla actiu.
`429` amb `Retry-After`	S'ha arribat a un bucket de límit de peticions.	Espera els segons de `Retry-After` abans de reintentar — no insisteixis sense parar.

Consulta Errors i límits de peticions per a la taula completa de codis.