Conectar un cliente

El servidor MCP de Factuarea habla Streamable HTTP en https://mcp.factuarea.com. Cualquier cliente compatible con MCP puede conectarse usando una de las dos credenciales admitidas:

• OAuth 2.1 — el cliente se registra a sí mismo y el usuario lo autoriza mediante una pantalla de consentimiento. Ideal para herramientas de usuario final.
• API key — pasas un Bearer token fact_live_ / fact_test_ directamente. Ideal para tus propias automatizaciones.

Claude Code

El camino más sencillo es el plugin de Claude Code — registra el servidor e incluye una skill de orientación en una sola instalación. Si prefieres conectar el servidor a mano, Claude Code también admite servidores MCP remotos sobre HTTP con OAuth integrado.

Con OAuth

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

/mcp

Con una API key

Si prefieres usar tu propia clave (sin flujo de consentimiento), pásala como un header Authorization:

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

Los scopes de la clave determinan qué tools aparecen en tools/list. Una clave con * ve las 232 tools; una clave más restringida solo ve las tools que cubren sus scopes.

Claude Desktop

Claude Desktop se conecta a servidores remotos mediante su archivo de configuración. Añade una entrada bajo mcpServers:

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

En el siguiente arranque, Claude Desktop descubre el servidor y te guía por el flujo de consentimiento OAuth en tu navegador. Para usar una API key en su lugar, añade un objeto headers:

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

MCP Inspector

El MCP Inspector es la forma más rápida de explorar el catálogo y llamar a tools a mano mientras desarrollas.

npx @modelcontextprotocol/inspector

Cualquier cliente MCP

El servidor sigue la especificación MCP, así que cualquier cliente conforme funciona. Lo esencial:

• Endpoint — https://mcp.factuarea.com (la forma con ruta …/mcp es un alias de compatibilidad)
• Transport — Streamable HTTP
• Auth — Authorization: Bearer <token>, donde el token es una API key (fact_live_ / fact_test_) o un access token de OAuth 2.1
• Discovery — ante un 401, el servidor devuelve un header WWW-Authenticate que apunta a sus Protected Resource Metadata (RFC 9728) para que los clientes encuentren el authorization server automáticamente

El descubrimiento de tools está paginado; el servidor devuelve el catálogo completo (hasta 200 tools) en una sola respuesta tools/list por defecto, y respeta nextCursor si tu cliente pagina.

Autenticación

El servidor MCP acepta dos tipos de credencial en el mismo endpoint https://mcp.factuarea.com, para dos audiencias distintas. Ambas llegan como Authorization: Bearer <token>; el servidor las distingue por la forma del token (fact_* → API key, cualquier otra cosa → access token de OAuth).

Política de canal

Esta es la regla más importante de la superficie MCP:

El modelo refleja el de GitHub: un personal access token (API key) es la credencial propia del propietario y puede tener cualquier permiso, mientras que una OAuth app es externa y se limita a un conjunto verificado de scopes que el usuario aprueba explícitamente.

Las 14 tools que una OAuth app nunca puede alcanzar (solo una API key puede) son las operaciones fiscales y de privacidad más sensibles:

• Escrituras de VeriFactu (verifactu:write) — 8 tools: registrar/reintentar/subsanar registros y eventos de VeriFactu, subir/activar/revocar certificados FNMT, actualizar ajustes de VeriFactu. Tocan el cumplimiento de la AEAT y son exclusivas del propietario.
• Borrado RGPD (delivery_notes:gdpr_forget) — 1 tool: borrar la PII de auditoría de firma (Art. 17). Privilegiada, solo para administradores.
• FacturaE (FACe) (facturae:read / facturae:write) — 5 tools: las operaciones B2G de FACe. Sus scopes aún no están en el catálogo de consentimiento OAuth, así que por ahora son solo para API key.

Todo lo demás — las 218 tools de lectura/escritura/transición/envío — está disponible para ambos canales. Consulta Scopes & permisos para ver el catálogo.

API keys

Una API key es un Bearer token opaco vinculado a tu empresa, creado en el dashboard de desarrolladores en Ajustes → Desarrolladores → API Keys. El formato y las reglas son idénticos a los de la API REST:

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

El prefijo es la fuente de verdad del entorno — consulta Modo de prueba. El secreto se muestra solo una vez en la creación; el backend solo almacena un hash bcrypt. Pásalo a tu cliente MCP como:

Authorization: Bearer fact_test_xxxxxxxxxxxxxxxxxxxxxxxx

Para el ciclo de vida completo de la clave — creación, scopes, rotación con periodo de gracia, revocación, lista de acceso de IPs, expires_at — consulta la guía de Autenticación canónica. Las claves se comparten entre las superficies REST y MCP.

OAuth 2.1

Para apps de terceros, Factuarea es un OAuth 2.1 Authorization Server completo. Es compatible con Dynamic Client Registration, el flujo de authorization-code con PKCE y la rotación de refresh-token. No se requiere pre-registro ni aprobación manual de la app — un cliente se registra a sí mismo y el usuario lo autoriza. (Los clientes interactivos como Claude Code y el MCP Inspector ejecutan todo este flujo por ti; los pasos de abajo son para construir tu propio cliente.)

Descubrimiento

Los clientes descubren las capacidades del servidor a través de endpoints de metadata estándar (sin prefijo /api):

Cuando una petición no autenticada alcanza el endpoint, el servidor responde 401 con un header WWW-Authenticate: Bearer ..., resource_metadata="<url>" para que los clientes RFC 9728 encuentren el authorization server sin adivinar.

1. Dynamic Client Registration (RFC 7591)

Un cliente se registra a sí mismo haciendo POST de su metadata; el servidor devuelve un client_id (y un client_secret para clientes confidenciales):

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"
  }'

Los clientes públicos (apps de navegador/nativas) se registran con token_endpoint_auth_method: "none" y dependen de PKCE; los clientes confidenciales usan client_secret_basic. El registro tiene un rate limit de 60 por minuto por IP.

2. Autorización con PKCE

Envía al usuario al endpoint authorize con un challenge PKCE (code_challenge_method=S256 es el único método aceptado):

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

Esto renderiza la pantalla de consentimiento, donde el usuario:

1. Elige la empresa a la que dar acceso (un usuario puede pertenecer a varias).
2. Elige el entorno — live (la empresa real) o test (un sandbox aislado), al estilo Stripe. Test es opt-in; si está ausente ⇒ live.
3. Revisa y selecciona los scopes a conceder. Los scopes sensibles se marcan y no vienen pre-seleccionados.

Al aprobar, el servidor redirige de vuelta con un code de un solo uso (y tu state). Las operaciones sensibles se filtran del catálogo que el usuario puede aprobar — consulta la política de canal.

3. Intercambio de token

Intercambia el code por un access token, enviando 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 persiste los scopes expandidos y de grano fino (las macros como factuarea.read se expanden en el momento de la emisión). Usa el access token como credencial Bearer. El endpoint token tiene un rate limit de 60 por minuto por (cliente, IP) y requiere autenticación de cliente (HTTP Basic para clientes confidenciales, client_id en el body para los públicos).

4. Rotación de refresh-token

Los refresh tokens rotan por familia: cada refresh emite un nuevo access token y un nuevo refresh token, e invalida el que usaste.

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 se reutiliza (usado tras la rotación — la señal clásica de una fuga), el servidor detecta la reutilización, revoca toda la familia de tokens y lanza una alerta de seguridad. Almacena y usa siempre solo el último refresh token.

Revocación e introspección

Ambos requieren autenticación de cliente. Los usuarios también pueden revisar y revocar apps conectadas desde el dashboard de Factuarea, y a un administrador de empresa que pierde el acceso se le revocan sus tokens automáticamente en la siguiente llamada.

Modo de prueba

El servidor MCP funciona contra los mismos dos entornos que la API REST — live (tu empresa real) y test (un sandbox aislado) — para que puedas construir y validar una integración de agente sin tocar datos de producción, la AEAT ni las bandejas de entrada de tus clientes.

Cómo seleccionas el modo de prueba depende del canal:

Una credencial de test opera sobre una empresa sandbox dedicada — un gemelo técnico de tu empresa real, aprovisionado automáticamente y que hereda su plan, para que el gating de módulo/plan se comporte fielmente. El aislamiento es estructural (los datos de test y live viven en empresas separadas), y los efectos externos están desactivados:

Todo lo demás se comporta exactamente igual que en producción, y el conjunto completo de 232 tools está disponible en ambos entornos (sujeto a tus scopes y plan). Cuando tu flujo funcione de extremo a extremo, cambia a live: crea una clave fact_live_, o vuelve a ejecutar el flujo de consentimiento y selecciona el entorno live.