Connectar un client

El servidor MCP de Factuarea parla Streamable HTTP a https://mcp.factuarea.com. Qualsevol client compatible amb MCP es pot connectar fent servir una de les dues credencials admeses:

• OAuth 2.1 — el client es registra a si mateix i l'usuari l'autoritza mitjançant una pantalla de consentiment. Ideal per a eines d'usuari final.
• API key — passes un Bearer token fact_live_ / fact_test_ directament. Ideal per a les teves pròpies automatitzacions.

Claude Code

El camí més senzill és el plugin de Claude Code — registra el servidor i inclou una skill d'orientació en una sola instal·lació. Si prefereixes connectar el servidor a mà, Claude Code també admet servidors MCP remots sobre HTTP amb OAuth integrat.

Amb OAuth

claude mcp add --transport http factuarea https://mcp.factuarea.com

/mcp

Amb una API key

Si prefereixes fer servir la teva pròpia clau (sense flux de consentiment), passa-la com un header Authorization:

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

Els scopes de la clau determinen quines tools apareixen a tools/list. Una clau amb * veu les 232 tools; una clau més restringida només veu les tools que cobreixen els seus scopes.

Claude Desktop

Claude Desktop es connecta a servidors remots mitjançant el seu fitxer de configuració. Afegeix una entrada sota mcpServers:

{
  "mcpServers": {
    "factuarea": {
      "type": "http",
      "url": "https://mcp.factuarea.com"
    }
  }
}

En el següent arrencament, Claude Desktop descobreix el servidor i et guia pel flux de consentiment OAuth al teu navegador. Per fer servir una API key en lloc d'això, afegeix un objecte headers:

{
  "mcpServers": {
    "factuarea": {
      "type": "http",
      "url": "https://mcp.factuarea.com",
      "headers": {
        "Authorization": "Bearer fact_test_xxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

MCP Inspector

El MCP Inspector és la manera més ràpida d'explorar el catàleg i cridar tools a mà mentre desenvolupes.

npx @modelcontextprotocol/inspector

Qualsevol client MCP

El servidor segueix l'especificació MCP, així que qualsevol client conforme funciona. L'essencial:

• Endpoint — https://mcp.factuarea.com (la forma amb ruta …/mcp és un àlies de compatibilitat)
• Transport — Streamable HTTP
• Auth — Authorization: Bearer <token>, on el token és una API key (fact_live_ / fact_test_) o un access token d'OAuth 2.1
• Discovery — davant d'un 401, el servidor retorna un header WWW-Authenticate que apunta a les seves Protected Resource Metadata (RFC 9728) perquè els clients trobin l'authorization server automàticament

El descobriment de tools està paginat; el servidor retorna el catàleg complet (fins a 200 tools) en una sola resposta tools/list per defecte, i respecta nextCursor si el teu client pagina.

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 14 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:

• 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.
• FacturaE (FACe) (facturae:read / facturae:write) — 5 tools: les operacions B2G de FACe. Els seus scopes encara no són al catàleg de consentiment OAuth, així que per ara són només per a API key.

Tota la resta — les 218 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 clients.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 232 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.