Plugin de Claude Code

Instal·la el plugin oficial factuarea-mcp per connectar Claude Code al servidor MCP de Factuarea amb una sola comanda — la configuració recomanada.

La manera més ràpida de connectar Claude Code al servidor MCP de Factuarea és el plugin oficial factuarea-mcp. 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à.

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

/plugin install factuarea-mcp@factuarea

Claude Code instal·la el plugin i registra el servidor MCP factuarea.

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

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 15 dominis de tools i els seus scopes, la identitat UUID v7, la paginació per cursor, l'embolcall d'error i el mode de prova.

La skill coneix la política de canal (una API key arriba a les 232 tools; OAuth fa servir les 218 curades, sense concedir mai verifactu:write, els scopes de FacturaE 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.

Construeixes una integració de codi contra la REST API en lloc de fer servir tools? Fes servir els SDKs oficials (TypeScript i PHP) o genera 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'add-on d'API per a desenvolupadors de l'empresa està inactiu.	Activa'l al dashboard; tota la superfície MCP el requereix.
`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.
OAuth diu que l'empresa no està permesa	L'API pública està en beta privada.	Sol·licita accés a info@factuarea.com — consulta Sol·licitar accés beta.

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