Clatri MCP

El Clatri MCP te deja conectar tu información de Clatri a clientes de IA externos como Claude Desktop, Cursor, Claude Code o Codex. El asistente externo lee y, si tú lo autorizas, escribe en tus datos — siempre dentro de los permisos que le otorgaste al token.

Para los curiosos: MCP significa Model Context Protocol, un estándar abierto creado por Anthropic. Cualquier cliente compatible puede conectarse a Clatri sin que tengamos que hacer una integración propietaria.

¿Cuándo usar el MCP?

Si ya hablas con Claude o Cursor todo el día y te gustaría que tuviera acceso a tu información de Clatri sin tener que abrir la app. Por ejemplo: "¿cuánto gasté este mes en restaurantes?" directamente en Claude Desktop, sin copy-paste.

Cómo funciona, en una imagen

Cada vez que el cliente IA hace una pregunta, manda el token al backend de Clatri. El backend valida el token, comprueba qué entidades y permisos tiene, ejecuta la herramienta solicitada y devuelve la respuesta. Nunca expone tu password, ni tu sesión de la app, ni te puede impersonar fuera de Clatri.

Requisitos

Necesitas una suscripción activa de Clatri

El MCP es una funcionalidad premium. Si no tienes suscripción:

No puedes crear tokens — el botón devuelve un error indicando que renueves.
Si tu suscripción se vence con tokens activos, esos tokens dejan de funcionar (responden 402) hasta que reactives. No se borran — vuelven a funcionar automáticamente al renovar.

Esto cubre el costo de procesar tus requests con baja latencia y mantener la infraestructura segura.

Necesitas un cliente compatible con MCP

Los más usados:

Claude Desktop (Mac, Windows) — instalación gráfica
Claude Code (CLI) — claude mcp add
Cursor (IDE) — Settings → MCP
Codex CLI (OpenAI) — ~/.codex/config.toml

Otros clientes que también funcionan: Continue, Cline, Zed, mcp-cli, cualquier integración que hable streamable HTTP MCP.

Paso 1 — Crea tu token

Abre la app de Clatri → Settings → API tokens.
Toca + Nuevo token.
Ponle un nombre que reconozcas (ej. "Claude Desktop en mi Mac").
Elige el nivel de permisos:
- Read only — el cliente puede consultar pero no modifica nada.
- Read + Write — puede crear y editar (gastos, episodios, notas, etc.).
- Full access — incluye borrar.
Toca Create token.

Cópialo inmediatamente

El token se muestra una sola vez. Si lo pierdes, no podemos recuperarlo — tienes que revocarlo y crear uno nuevo. Pégalo de inmediato en tu cliente o guárdalo en tu gestor de contraseñas.

El token expira automáticamente a los 6 meses. Puedes revocarlo manualmente en cualquier momento desde la misma pantalla.

Paso 2 — Conéctalo a tu cliente

Claude Code
Claude Desktop
Cursor
Codex CLI

Desde la terminal:

claude mcp add clatri \
  --transport http \
  --scope user \
  https://api.clatri.com/mcp \
  --header "Authorization: Bearer clt_mcp_TU_TOKEN_AQUI"

--scope user lo registra a nivel global (disponible en todos los proyectos). Usa --scope project si solo lo quieres en este repo (queda en .mcp.json).
--transport http es obligatorio porque el Clatri MCP es remoto.

Verifica que conectó:

claude mcp list

Deberías ver clatri: connected ✓. En tu próxima sesión de Claude Code, las herramientas whoami, list_entities y las demás aparecerán automáticamente.

Abre Claude Desktop.
Settings → Developer → Edit Config. Esto abre claude_desktop_config.json.
Agrega Clatri al objeto mcpServers:

{
  "mcpServers": {
    "clatri": {
      "type": "http",
      "url": "https://api.clatri.com/mcp",
      "headers": {
        "Authorization": "Bearer clt_mcp_TU_TOKEN_AQUI"
      }
    }
  }
}

Guarda el archivo y reinicia Claude Desktop (cerrar y abrir, no solo minimizar).
En una conversación nueva, abre el menú de tools (ícono de herramienta abajo a la izquierda del input). Deberías ver Clatri listada con las herramientas disponibles.

Path del config

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Cursor → Settings → Cursor Settings → MCP (o edita ~/.cursor/mcp.json directamente).
Click + Add new MCP server.
Selecciona transport HTTP y pega:
- Name: clatri
- URL: https://api.clatri.com/mcp
- Headers: Authorization: Bearer clt_mcp_TU_TOKEN_AQUI
Guarda. Cursor muestra el estado de la conexión con un punto verde si conectó OK.

Equivalente vía archivo:

{
  "mcpServers": {
    "clatri": {
      "url": "https://api.clatri.com/mcp",
      "headers": {
        "Authorization": "Bearer clt_mcp_TU_TOKEN_AQUI"
      }
    }
  }
}

Edita ~/.codex/config.toml y agrega:

[mcp_servers.clatri]
url = "https://api.clatri.com/mcp"
http_headers = { "Authorization" = "Bearer clt_mcp_TU_TOKEN_AQUI" }

Recomendado: en vez de pegar el token directo, usa una env var:

[mcp_servers.clatri]
url = "https://api.clatri.com/mcp"
bearer_token_env_var = "CLATRI_MCP_TOKEN"

y en tu shell:

export CLATRI_MCP_TOKEN="clt_mcp_TU_TOKEN_AQUI"

Reinicia Codex (ctrl+C y vuelve a abrir).

Paso 3 — Prueba que funciona

En tu cliente recién configurado, escribe alguno de estos mensajes:

¿Quién soy en Clatri y a qué entidades tengo acceso?

Lista mis entidades de Clatri.

Si todo está OK, el cliente va a usar las tools whoami y list_entities y te va a responder con tu nombre, las entidades disponibles (Personal, Empresa, etc.) y los permisos del token.

Qué puedes preguntarle (ejemplos)

Una vez conectado, estos prompts funcionan en cualquier cliente:

Pregunta	Tools que usa
"¿Cuánto gasté el mes pasado en restaurantes en mi cuenta personal?"	`list_entities`, `read_expenses`
"Resume mis cuentas y balances actuales."	`list_entities`, `list_accounts`, `get_balance`
"Anota un gasto de 45 USD en Uber para hoy en Gurwi LLC."	`list_entities`, `create_expense` (requiere scope write)
"¿Cuándo es mi próxima obligación a pagar y de cuánto?"	`list_obligations`
"Qué medicamentos estoy tomando actualmente."	`list_medications`

Para preguntas vagas

Si no sabes exactamente qué tool usar, simplemente pregúntale al cliente en lenguaje natural. Los LLMs modernos eligen las tools adecuadas automáticamente.

Seguridad

El token nunca da acceso fuera de Clatri

Aunque el token leakee:

Solo aplica los scopes que diste (read / write / delete).
Solo accede a datos dentro de Clatri — no tiene acceso a tu password, ni puede cambiar tu email, ni resetear tu 2FA.
No puede crear más tokens, ni revokar otros, ni tocar tu suscripción.
Tú lo puedes revocar instantáneamente desde Settings → API tokens.

Todas las operaciones quedan en el audit log (Settings → API tokens → tap en un token → ver actividad reciente). Si ves uso anómalo, revoca.

Restringir un token a entidades específicas

Por defecto un token tiene acceso a las mismas entidades que tu cuenta — propias y compartidas. Al crear o editar un token puedes seleccionar solo las entidades que el cliente IA verá. Útil para:

Un token para tu contador que solo ve la empresa.
Un token de prueba que solo accede a una entidad sandbox.
Un cliente IA en tu compu personal que no puede tocar datos del trabajo.

Después de creado puedes cambiar las entidades, los permisos y el nombre desde Settings → API tokens → tap el menú (···) → Edit. No tienes que generar un token nuevo cada vez que ajustas su alcance.

El token expira a los 6 meses

Por seguridad. Cuando expira, simplemente creas uno nuevo y reemplazas en el cliente. No hay forma de extender la expiración — es a propósito.

Troubleshooting

El cliente dice "401 unauthorized"

El token expiró → crea uno nuevo.
Lo revocaste por error → crea uno nuevo.
Lo copiaste mal (le falta el prefijo clt_mcp_ o le sobra un espacio) → verifica el header Authorization: Bearer clt_mcp_....

El cliente dice "402 subscription_inactive"

Tu suscripción a Clatri no está activa. Renuévala en la app y vuelve a probar — el mismo token sigue funcionando.

El cliente dice "403 scope_denied" o "entity_denied"

scope_denied: el token no tiene el permiso requerido (ej. quiere escribir pero solo le diste read). Crea un token nuevo con más scopes y reemplaza.
entity_denied: el cliente intentó tocar una entidad que el token no tiene permitido. Si quieres ampliar, revoca y crea un token nuevo sin restricción de entidades.

"Browser origins not allowed"

Estás tratando de hablar con /mcp desde un navegador o una pestaña web. Los clientes MCP legítimos son procesos nativos (Claude Desktop, Claude Code CLI, Cursor desktop). Esto es una protección anti DNS-rebinding — no es un bug, es a propósito.

El cliente no detecta las tools después de instalar

Reinicia el cliente completamente (no solo minimizar).
Claude Code: corre claude mcp list para ver si aparece. Si dice "failed", revisa el formato del header.
Codex: corre con --verbose o revisa logs en ~/.codex/log/.

Preguntas frecuentes

¿Cuántos tokens puedo crear?

Hasta 10 tokens activos por usuario. Si llegas al límite, revoca uno viejo antes de crear nuevo.

¿Puedo compartir un token con alguien más?

Técnicamente sí (es solo un string), pero no es recomendable. Si la persona necesita acceso a tu Clatri, mejor compartir la entidad desde Settings → Compartir entidades y darle a esa persona su propio acceso con su cuenta. Los tokens son personales.

¿Las acciones del cliente IA se reflejan en mi historial de chat con Clatri?

No. Las llamadas MCP son independientes del chat del agente principal. Quedan registradas en el audit log del token (no en el historial conversacional del agente). Esto es a propósito: el agente principal y los clientes externos son contextos separados.

¿Qué pasa con mi token cuando renueve mis API keys o JWT signing keys de Supabase?

Nada. El token MCP es independiente del sistema de auth interno de Supabase. Rotaciones de keys backend son transparentes para los tokens MCP.

¿Hay rate limits?

Sí, pero conservadores — pensados para uso humano normal vía un cliente IA, no para automatización masiva. Si llegas al límite verás 429 rate_limited en el audit log. Si necesitas más volumen, contáctanos.

Cómo funciona, en una imagen​

Requisitos​

Paso 1 — Crea tu token​

Paso 2 — Conéctalo a tu cliente​

Paso 3 — Prueba que funciona​

Qué puedes preguntarle (ejemplos)​

Seguridad​

Troubleshooting​

Preguntas frecuentes​