Connectar un client

Fes servir un client que implementi MCP 2026-07-28, inclosos server/discover, les metadades de protocol per petició i les capçaleres necessàries. Registrar només la URL del servidor no afegeix compatibilitat amb aquesta revisió. Comprova la revisió admesa abans de fer servir Claude Code, Claude Desktop o MCP Inspector.

Configuració de connexió

L’endpoint és https://mcp.factuarea.com (/mcp continua com a àlies). Configura el transport HTTP i OAuth 2.1 o una API key a Authorization: Bearer. La guia del protocol inclou una petició de discovery executable; els recursos i prompts expliquen l’orientació fiscal.

Catàleg i compatibilitat

Comença per server/discover i segueix els cursors de tools/list amb la mateixa credencial. El catàleg complet té 457 eines; OAuth pot accedir a 368. Els antics initialize i ping no estableixen cap sessió. El plugin de Claude Code registra el servidor, però la compatibilitat del transport continua depenent del client instal·lat.

Autenticació

El servidor MCP accepta dos tipus de credencial al mateix endpoint https://mcp.factuarea.com, per a dues audiències diferents. Totes dues arriben com a Authorization: Bearer <token>; el servidor les distingeix per la forma del token (fact_* → API key, qualsevol altra cosa → access token d'OAuth).

Política de canal

Aquesta és la regla més important de la superfície MCP:

El model reflecteix el de GitHub: un personal access token (API key) és la credencial pròpia del propietari i pot tenir qualsevol permís, mentre que una OAuth app és externa i es limita a un conjunt verificat de scopes que l'usuari aprova explícitament.

Les 89 tools que una OAuth app mai pot abastar (només una API key pot) són les operacions fiscals i de privacitat més sensibles, a més de la superfície first-party de gestió del compte:

• Escriptures de VeriFactu (verifactu:write) — 8 tools: registrar/reintentar/subsanar registres i esdeveniments de VeriFactu, pujar/activar/revocar certificats FNMT, actualitzar ajustos de VeriFactu. Toquen el compliment de l'AEAT i són exclusives del propietari.
• Esborrament RGPD (delivery_notes:gdpr_forget) — 1 tool: esborrar la PII d'auditoria de signatura (Art. 17). Privilegiada, només per a administradors.
• Pagaments, passarel·les i botigues (stripe_autoinvoicing:*, payouts:read, integration_events:*, stores:*, woocommerce_store:write, shopify_store:write) — 20 tools: 13 d’autofacturació Stripe, comptes connectats, payouts i safata/replay d’esdeveniments de passarel·la, més 7 de gestió de botigues i diagnòstic de connexió. Scopes granulars, només API key, sense equivalent de consentiment OAuth.
• Emails i registre de peticions (emails:read, developers:read) — 5 tools amb diagnòstics de lliurament i integració del propietari.
• Gestoria (companies:*, api_keys:*) — 17 tools: gestió de les empreses filles i les seves API keys. Gestionar sub-comptes i credencials és first-party, mai es concedeix per consentiment de tercers.
• Escriptures de compte (account:write) — 4 tools: crear/rotar/revocar les teves pròpies API keys i actualitzar la personalització del compte. Només first-party.
• Escriptures/transicions privilegiades de personal — 33 tools amb time_entries:write, absences:write, absences:transition o work_schedules:write; les lectures i employees:write continuen accessibles per OAuth.

Tota la resta — les 368 tools de lectura/escriptura/transició/enviament — està disponible per a tots dos canals. Consulta Scopes & permisos per veure el catàleg.

API keys

Una API key és un Bearer token opac vinculat a la teva empresa, creat al dashboard de desenvolupadors a Ajustos → Desenvolupadors → API Keys. El format i les regles són idèntics als de l'API REST:

fact_live_<24 alphanumeric characters>   →  production company
fact_test_<24 alphanumeric characters>   →  isolated sandbox company

El prefix és la font de veritat de l'entorn — consulta Mode de prova. El secret es mostra només una vegada en la creació; el backend només emmagatzema un hash bcrypt. Passa'l al teu client MCP com a:

Authorization: Bearer fact_test_xxxxxxxxxxxxxxxxxxxxxxxx

Per al cicle de vida complet de la clau — creació, scopes, rotació amb període de gràcia, revocació, llista d'accés d'IPs, expires_at — consulta la guia d'Autenticació canònica. Les claus es comparteixen entre les superfícies REST i MCP.

OAuth 2.1

Per a apps de tercers, Factuarea és un OAuth 2.1 Authorization Server complet. És compatible amb Dynamic Client Registration, el flux d'authorization-code amb PKCE i la rotació de refresh-token. No cal pre-registre ni aprovació manual de l'app — un client es registra a si mateix i l'usuari l'autoritza. (Els clients interactius com Claude Code i el MCP Inspector executen tot aquest flux per tu; els passos de sota són per construir el teu propi client.)

Descobriment

Els clients descobreixen les capacitats del servidor a través d'endpoints de metadata estàndard (sense prefix /api):

Quan una petició no autenticada abasta l'endpoint, el servidor respon 401 amb un header WWW-Authenticate: Bearer ..., resource_metadata="<url>" perquè els clients RFC 9728 trobin l'authorization server sense endevinar.

1. Dynamic Client Registration (RFC 7591)

Un client es registra a si mateix fent POST de la seva metadata; el servidor retorna un client_id (i un client_secret per a clients confidencials):

curl -X POST https://mcp.factuarea.com/api/oauth/register \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "My Invoicing Assistant",
    "redirect_uris": ["https://myapp.example.com/callback"],
    "token_endpoint_auth_method": "none"
  }'

Els clients públics (apps de navegador/natives) es registren amb token_endpoint_auth_method: "none" i depenen de PKCE; els clients confidencials fan servir client_secret_basic. El registre té un rate limit de 60 per minut per IP.

2. Autorització amb PKCE

Envia l'usuari a l'endpoint authorize amb un challenge PKCE (code_challenge_method=S256 és l'únic mètode acceptat):

GET https://mcp.factuarea.com/api/oauth/authorize
  ?response_type=code
  &client_id=<client_id>
  &redirect_uri=https://myapp.example.com/callback
  &scope=factuarea.read invoices.write
  &state=<opaque>
  &code_challenge=<base64url(sha256(verifier))>
  &code_challenge_method=S256

Això renderitza la pantalla de consentiment, on l'usuari:

1. Tria l'empresa a la qual donar accés (un usuari pot pertànyer a diverses).
2. Tria l'entorn — live (l'empresa real) o test (un sandbox aïllat), a l'estil Stripe. Test és opt-in; si és absent ⇒ live.
3. Revisa i selecciona els scopes a concedir. Els scopes sensibles es marquen i no vénen pre-seleccionats.

En aprovar, el servidor redirigeix de tornada amb un code d'un sol ús (i el teu state). Les operacions sensibles es filtren del catàleg que l'usuari pot aprovar — consulta la política de canal.

3. Intercanvi de token

Intercanvia el code per un access token, enviant el verificador PKCE:

curl -X POST https://mcp.factuarea.com/api/oauth/token \
  -d grant_type=authorization_code \
  -d code=<code> \
  -d redirect_uri=https://myapp.example.com/callback \
  -d client_id=<client_id> \
  -d code_verifier=<verifier>

{
  "access_token": "<opaque>",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "<opaque>",
  "scope": "profile.read contacts.read invoices.read invoices.write"
}

El token persisteix els scopes expandits i de gra fi (les macros com factuarea.read s'expandeixen en el moment de l'emissió). Fes servir l'access token com a credencial Bearer. L'endpoint token té un rate limit de 60 per minut per (client, IP) i requereix autenticació de client (HTTP Basic per a clients confidencials, client_id al body per als públics).

4. Rotació de refresh-token

Els refresh tokens roten per família: cada refresh emet un nou access token i un nou refresh token, i invalida el que vas fer servir.

curl -X POST https://mcp.factuarea.com/api/oauth/token \
  -d grant_type=refresh_token \
  -d refresh_token=<refresh_token> \
  -d client_id=<client_id>

Si un refresh token es reutilitza (usat després de la rotació — el senyal clàssic d'una fuita), el servidor detecta la reutilització, revoca tota la família de tokens i llança una alerta de seguretat. Emmagatzema i fes servir sempre només el darrer refresh token.

Revocació i introspecció

Tots dos requereixen autenticació de client. Els usuaris també poden revisar i revocar apps connectades des del dashboard de Factuarea, i a un administrador d'empresa que perd l'accés se li revoquen els tokens automàticament en la següent crida.

Mode de prova

El servidor MCP funciona contra els mateixos dos entorns que l'API REST — live (la teva empresa real) i test (un sandbox aïllat) — perquè puguis construir i validar una integració d'agent sense tocar dades de producció, l' AEAT ni les safates d'entrada dels teus clients.

Com selecciones el mode de prova depèn del canal:

Una credencial de test opera sobre una empresa sandbox dedicada — un bessó tècnic de la teva empresa real, aprovisionat automàticament i que hereta el seu pla, perquè el gating de mòdul/pla es comporti fidelment. L'aïllament és estructural (les dades de test i live viuen en empreses separades), i els efectes externs estan desactivats:

Tota la resta es comporta exactament igual que en producció, i el conjunt complet de 457 tools està disponible en tots dos entorns (subjecte als teus scopes i pla). Quan el teu flux funcioni d'extrem a extrem, canvia a live: crea una clau fact_live_, o torna a executar el flux de consentiment i selecciona l'entorn live.