Resum de MCP
Connecta agents d'IA a Factuarea sobre el Model Context Protocol — 391 tools de facturació, catàleg, compliment, control horari i webhooks, amb autenticació OAuth 2.1 i API key.
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 manualment, fent servir OAuth o una API key.
Explora les 391 tools
El catàleg complet agrupat per domini, amb el scope que requereix cada tool.
Què pot fer
El servidor publica 391 tools en 27 dominis. Tot el que pots fer amb la REST API ho pots fer aquí, en el format natiu de tool-calling de l'agent:
Vendes i compres
Factures, pressupostos, factures proforma, albarans, factures recurrents i factures de compra — crear, actualitzar, transicionar, enviar i generar PDFs.
Catàleg i CRM
Clients, proveïdors, productes, sèries de numeració i tipus impositius.
Compliment
Registres, esdeveniments i certificats de VeriFactu (AEAT), enviaments a FACe (FacturaE), 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.
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 la seva pròpia empresa (com un PAT de GitHub) | Fins a 391 — concedeixes els scopes que vulguis, inclòs * |
| OAuth 2.1 | Access token emès via consentiment | Apps de tercers actuant en nom d'un usuari | 305 — un catàleg curat que exclou les escriptures de VeriFactu, l'esborrat RGPD, FacturaE (FACe), Pagaments i passarel·les, i les tools de gestoria i escriptura de compte |
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.