Servidor MCP de Invoiso

Invoiso habla el Model Context Protocol, así que un cliente MCP —Claude, ChatGPT o cualquier otro que lo hable— puede leer y trabajar con las facturas, los gastos, los contactos, el stock y los informes de tu espacio de invoiso. Esta página es lo que necesitas para conectar uno.

El endpoint

https://www.invoiso.com/api/mcp

Transport   Streamable HTTP (POST, JSON-RPC 2.0)
Auth        OAuth 2.1 — see below
Server      invoiso 0.1.0
Protocol    2025-06-18, 2025-03-26, 2024-11-05

A casi todo el mundo le basta con la URL. Añádela como conector personalizado en ChatGPT o como servidor MCP remoto en Claude y luego inicia sesión en invoiso como siempre: no hace falta ninguna clave de API. El cliente descubre solo cómo autenticarse: una llamada sin autenticar responde 401 con una cabecera WWW-Authenticate que apunta a https://www.invoiso.com/.well-known/oauth-protected-resource, donde se nombran el servidor de autorización y los ámbitos que hay que pedir.

Conectar

1. Añade https://www.invoiso.com/api/mcp a tu cliente como servidor MCP remoto.
2. El cliente te lleva al inicio de sesión de invoiso. Inicia sesión como de costumbre.
3. Aprueba el acceso que describe la pantalla de consentimiento. Nombra el espacio que estás conectando.
4. Ya estás conectado. Pregúntale algo a tu cliente sobre tus libros: «¿cuánto facturé el mes pasado?» es una buena primera pregunta, porque no necesita más permisos que la lectura.

Los ámbitos solicitados son openid, email, profile y user:org:read. El último es el que nos dice qué espacio estás conectando; sin él el servidor se niega en lugar de adivinar — véase más abajo.

A qué espacio estás conectado

Estás conectado al espacio que estaba activo en tu navegador cuando aprobaste la conexión. La pantalla de consentimiento lo nombra. Es la misma regla que sigue el navegador —una sesión está en un espacio a la vez— y significa que cambiar de espacio en invoiso no cambia lo que ve tu cliente MCP.

Para apuntar un cliente a otro espacio: cambia primero a ese espacio en invoiso, luego elimina y vuelve a añadir la conexión en tu cliente. Pasarás otra vez por el consentimiento y el nuevo token llevará el nuevo espacio.

Si el servidor no puede saber a qué espacio corresponde un token, responde 403 con error="insufficient_scope" nombrando el ámbito que hay que pedir, en vez de elegir uno. Elegir sería peor que negarse: la respuesta equivocada más plausible es tu espacio personal vacío, y concluirías que invoiso ha perdido tus libros.

Qué puede hacer tu plan

Todo está disponible para el asistente dentro de invoiso en cualquier plan. Lo que cambia en un cliente MCP externo es si puede escribir.

Una conexión de solo lectura no es un cliente reducido: son todas las herramientas que solo informan. La escritura desde un cliente externo empieza en Business. Pídele a una conexión de solo lectura que cambie algo y te lo dirá en una frase sin cambiar nada, en vez de fallar de forma opaca.

Qué hacen las herramientas

Hay 167 herramientas. 63 de ellas solo informan; el resto escribe. Cada herramienta lleva las tres anotaciones que define MCP —readOnlyHint, destructiveHint y openWorldHint— para que tu cliente pueda preguntarte antes de hacer algo irreversible. 15 de ellas pueden cambiar algo fuera de invoiso: enviar un correo, publicar una página de pago, escribir en Xero o QuickBooks. Ésas son las que conviene que tu cliente confirme.

Los importes siempre se indican dos veces

Un espacio puede contener documentos en varias monedas. Cualquier herramienta que devuelva un importe lo devuelve en la moneda propia del documento y en la moneda de informe del espacio, convertida al tipo fijado en ese documento. Solo la segunda es comparable entre documentos, y las instrucciones del servidor le dicen al modelo que nunca sume dos importes en monedas distintas. Donde ningún tipo de cambio cubría una fecha, la cifra de informe es null en lugar de cero.

Los totales vienen de la herramienta de informes

run_report responde a las preguntas de «cuánto». Las herramientas de listado listan; sumar una lista no es la misma aritmética —los borradores y las notas de crédito cuentan distinto— y la descripción de cada herramienta dice cuál es.

Qué lee el servidor y qué guarda

Una llamada a una herramienta lee y escribe los datos propios de tu espacio: tus facturas, gastos, contactos, productos y ajustes. Las respuestas llevan los registros de negocio consultados: para un contacto, su nombre, y puede que un correo, una dirección postal o un número de identificación fiscal, porque eso es lo que aparece en una factura.

El servidor no guarda ninguna copia separada de una conversación, no envía ninguna respuesta de herramienta a ningún sitio salvo al cliente que preguntó y nunca devuelve credenciales, claves de API ni tokens de OAuth, ni tuyos ni de un servicio conectado. Lo que hacemos con los datos en general, incluidos qué terceros reciben qué, está en la política de privacidad, y los términos se aplican a esta conexión igual que a cualquier otra.

Desconectar

Elimina la conexión en tu cliente MCP. Con eso basta: el token es lo único que concede acceso y nada de nuestro lado sigue funcionando sin él. Borrar tu cuenta de invoiso elimina todo lo que hay detrás; la política de privacidad explica qué significa eso y cuánto tarda.

Detalles del protocolo

El servidor negocia 2025-06-18, 2025-03-26 y 2024-11-05 y responde con la más reciente que entienden tanto él como el cliente. Ante una versión desconocida responde con la más reciente que admitimos en lugar de rechazarla, que es lo que pide la especificación.

La autorización sigue OAuth 2.1 con PKCE. El descubrimiento son los metadatos de recurso protegido de RFC 9728 en https://www.invoiso.com/.well-known/oauth-protected-resource, y el servidor de autorización publica documentos de descubrimiento tanto de RFC 8414 como de OpenID Connect. Los clientes se registran solos mediante registro dinámico (RFC 7591), que es por lo que los pasos de arriba no te piden más que una URL. El endpoint de registro solo se anuncia en el documento RFC 8414; un cliente que lea únicamente el de OpenID Connect no lo encontrará y necesitará el id de cliente predefinido de más abajo.

Si tu cliente no puede registrarse solo y te pide un id de cliente, escribe a support@invoiso.com y te daremos uno. Deja vacío el secreto de cliente: el cliente es público y se autentica con PKCE.

Los tokens se verifican contra el JWKS de nuestra propia instancia y deben llevar nuestro emisor y el ámbito que nombra tu espacio. Un token emitido por otro despliegue de invoiso, o por otra instancia de Clerk, se rechaza. Un token de otra aplicación registrada contra esta instancia no se distingue del nuestro y se acepta: eso es lo que significa el registro abierto, y por eso vale la pena leer la pantalla de consentimiento, que nombra la aplicación que pide, antes de aprobarla.

Si algo va mal

Escribe a support@invoiso.com con lo que pidió tu cliente y lo que llegó de vuelta. Un 401 suele significar que hay que volver a aprobar la conexión; un 403 que nombra un ámbito significa que el cliente no lo pidió; y una negativa que nombra tu plan es la barrera de solo lectura de arriba, no un fallo.