Conectar un cliente

Usa un cliente que implemente MCP 2026-07-28, incluidos server/discover, los metadatos de protocolo por petición y las cabeceras necesarias. Registrar solo la URL del servidor no añade compatibilidad con esta revisión. Comprueba la revisión admitida antes de usar Claude Code, Claude Desktop o MCP Inspector.

Configuración de conexión

El endpoint es https://mcp.factuarea.com (/mcp sigue como alias). Configura el transporte HTTP y OAuth 2.1 o una API key en Authorization: Bearer. La guía del protocolo incluye una petición de discovery ejecutable; los recursos y prompts explican la orientación fiscal.

Catálogo y compatibilidad

Empieza por server/discover y sigue los cursores de tools/list con la misma credencial. El catálogo completo tiene 457 herramientas; OAuth puede acceder a 368. Los antiguos initialize y ping no establecen una sesión. El plugin de Claude Code registra el servidor, pero la compatibilidad del transporte sigue dependiendo del cliente instalado.

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 89 tools que una OAuth app nunca puede alcanzar (solo una API key puede) son las operaciones fiscales y de privacidad más sensibles, además de la superficie first-party de gestión de la cuenta:

• 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.
• Pagos, pasarelas y tiendas (stripe_autoinvoicing:*, payouts:read, integration_events:*, stores:*, woocommerce_store:write, shopify_store:write) — 20 tools: 13 de autofacturación Stripe, cuentas conectadas, payouts y bandeja/replay de eventos de pasarela, más 7 de gestión de tiendas y diagnóstico de conexión. Scopes granulares, solo API key, sin equivalente de consentimiento OAuth.
• Emails y registro de peticiones (emails:read, developers:read) — 5 tools con diagnósticos de entrega e integración del propietario.
• Gestoría (companies:*, api_keys:*) — 17 tools: gestión de las empresas hijas y sus API keys. Gestionar sub-cuentas y credenciales es first-party, nunca se concede por consentimiento de terceros.
• Escrituras de cuenta (account:write) — 4 tools: crear/rotar/revocar tus propias API keys y actualizar la personalización de la cuenta. Solo first-party.
• Escrituras/transiciones privilegiadas de personal — 33 tools con time_entries:write, absences:write, absences:transition o work_schedules:write; las lecturas y employees:write siguen accesibles por OAuth.

Todo lo demás — las 368 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 contacts.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 457 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.