Resum de MCP
Connecta agents d'IA a Factuarea sobre el Model Context Protocol — tools de facturació, catàleg, preus, compliment, control horari, projectes i tasques, automatitzacions, webhooks i el model de comptes, amb autenticació OAuth 2.1 i API key.
El servidor implementa la revisió MCP 2026-07-28 i també atén clients a 2025-11-25 i 2025-06-18. Consulta el protocol i transport per a server/discover, capçaleres i paginació; fes servir els recursos i prompts per a l’orientació fiscal. El seu repositori públic, amb el paquet de npm i el manifest del registre, és factuarea/factuarea-mcp.
El servidor MCP de Factuarea exposa l'API pública com a tools de Model Context Protocol, de manera que els agents d'IA (Claude, ChatGPT, Cursor, la teva pròpia app LLM) poden llegir i operar sobre les teves dades de facturació a través d'un únic endpoint governat en lloc d'escriure a mà crides HTTP. Parla el transport Streamable HTTP i viu a:
https://mcp.factuarea.comL'endpoint canònic és l'arrel del subdomini. La forma anterior amb path
https://mcp.factuarea.com/mcp continua funcionant com a àlies de compatibilitat, així que
les configuracions existents segueixen connectant.
Cada tool es correspon amb el mateix contracte https://api.factuarea.com/v1 documentat
a la Referència de l'API: recursos idèntics, el mateix
id opac (UUID v7), els mateixos errors normalitzats, el mateix aïllament
multi-tenant per empresa. La capa MCP afegeix descobriment (tools/list), aplicació de
scope per tool i un flux de consentiment per a apps de tercers.
Instal·la el plugin de Claude Code
La configuració recomanada — dues comandes instal·len el plugin oficial factuarea-mcp
i connecten Claude Code sobre OAuth.
Connecta qualsevol client
Configura Claude Desktop, l'MCP Inspector o qualsevol client MCP, amb OAuth o una API key, o executa el servidor local de npm.
Explora les 686 tools
El catàleg complet agrupat per domini, amb el scope que requereix cada tool.
Què pot fer
El servidor publica 686 tools en els dominis de l’API pública. Gairebé tot el que pots fer amb la REST API ho pots fer aquí, en el format natiu de tool-calling de l'agent; la importació massiva de comptes gestionats, per exemple, no té tool (consulta el catàleg):
Vendes i compres
Factures, pressupostos, factures proforma, albarans, documents de control (DeCA), factures recurrents i despeses — crear, actualitzar, transicionar, enviar i generar PDFs.
Catàleg i CRM
Contactes amb rols de client/proveïdor, productes mesurats, presentacions, variants, ofertes, tarifes, sèries de numeració i tipus impositius.
Compliment
Registres, esdeveniments i certificats de VeriFactu (AEAT), enviaments a FACe (FacturaE), les declaracions del Modelo 303/347/130, a més de webhooks i el catàleg d'esdeveniments.
Control horari
Empleats, horaris de treball, el registre de fitxatges, tancaments mensuals, absències, presència i festius — el registre del RD-ley 8/2019.
Automatitzacions
El motor de regles — el catàleg d'activadors i accions, les regles i les seves versions segellades, l'assaig, l'historial d'execucions amb els seus passos, el rellançament i la quota mensual.
Comptes i NIF
El model de comptes — membres i els seus grants, traspassos de NIF, la cartera de NIF amb el
seu estat i la seva disponibilitat d'emissió, webhooks i registres de peticions del compte —
i, amb els scopes privilegiats accounts:*, els comptes gestionats. Només amb API key.
Projectes i tasques
Projectes amb els seus taulers i camps personalitzats, tasques amb els seus comentaris, relacions, adjunts i temps imputat, el temporitzador, esborranys de factura a partir de les hores facturables, els membres de l'empresa, les notificacions i l'agenda combinada.
Quan fer servir MCP, REST o SDKs
El servidor MCP, la REST API i els SDKs oficials són tres portes d'entrada al mateix backend. Tria segons qui (o què) està cridant:
| Estàs construint… | Fes servir | Per què |
|---|---|---|
| Un agent / assistent d'IA que raona sobre les teves dades i hi actua | Servidor MCP | Les tools s'autodescriuen; el model les descobreix i les crida sense que cablegis cada endpoint. Els scopes i el consentiment s'apliquen a cada crida. |
| Un servei backend, cron job o integració amb lògica fixa | REST API | Determinista, sense model al bucle, control total sobre les peticions i els reintents. |
| Un client tipat a la teva app (TypeScript o PHP) | SDKs oficials | @factuarea/sdk i factuarea/factuarea-php embolcallen la REST API amb tipus, reintents i helpers d'idempotència. |
Les tres superfícies comparteixen els mateixos identificadors, embolcall d'error i scopes, així que pots combinar-les: prototipa un flux amb un agent sobre MCP i després endureix el camí crític com a integració REST o SDK.
Dues maneres d'autenticar-se
El mateix endpoint /mcp accepta dos tipus de credencial, per a dues audiències
diferents:
| Canal | Credencial | Per a | Tools assolibles |
|---|---|---|---|
| API key | Bearer token fact_live_… / fact_test_… | El titular del compte automatitzant el seu propi compte i els seus NIF (com un PAT de GitHub) | Fins a 686 — concedeixes els scopes que vulguis, inclòs * (els scopes privilegiats accounts:* mai els cobreix *) |
| OAuth 2.1 | Access token emès via consentiment | Apps de tercers actuant en nom d'un usuari | 559 — el catàleg curat; 127 tools de propietari (inclosos pagaments, gestió de compte i escriptures privilegiades de personal) exigeixen API key |
Consulta Connectar un client per a la política completa de canals, i Scopes i permisos per al catàleg de scopes.
Construeix primer en mode de prova
Igual que a la REST API, una clau fact_test_ — o un consentiment OAuth amb l'entorn
Test seleccionat — opera sobre una empresa sandbox aïllada amb els efectes
externs desactivats (sense transmissió a AEAT, sense emails reals, sense
webhooks sortints). Construeix i valida contra test, després canvia a producció. Consulta
Mode de prova.
El servidor MCP està inclòs en tots els plans de Factuarea, juntament amb la resta de l'API pública. Crea una API key des de Dashboard → Developers → API Keys (o connecta't per OAuth) i comença a cridar tools.