# Clatri MCP URL: https://docs.clatri.com/mcp/ > Conecta Clatri a Claude Desktop, Claude Code, Cursor o Codex usando el protocolo 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. :::tip ¿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 ```mermaid flowchart LR Client["🤖 Tu cliente IA
(Claude Desktop, Cursor, …)"] Token["🔑 Token MCP
(clt_mcp_…)"] API["⚙️ api.clatri.com/mcp"] Data["🗄️ Tus datos en Clatri
(con tus permisos)"] Client -- "Authorization: Bearer" --> Token Token --> API API -- "valida + filtra por entidad y scope" --> Data Data -- "JSON" --> API API -- "MCP response" --> Client style Client fill:#3b82f6,stroke:#2563eb,color:#fff style Token fill:#8b5cf6,stroke:#7c3aed,color:#fff style API fill:#6366f1,stroke:#4f46e5,color:#fff style Data fill:#10b981,stroke:#059669,color:#fff ``` 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 1. Abre la app de Clatri → **Settings** → **API tokens**. 2. Toca **+ Nuevo token**. 3. Ponle un nombre que reconozcas (ej. "Claude Desktop en mi Mac"). 4. 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. 5. Toca **Create token**. :::warning 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 Desde la terminal: ```bash 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ó: ```bash 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. Esta instalación manual usa `mcp-remote` para conectar el servidor remoto de Clatri a los **servidores MCP locales** de Claude Desktop. 1. Instala [Node.js LTS](https://nodejs.org/en/download), que incluye npm y npx. Para este método deben estar disponibles en el sistema. Comprueba en una terminal nueva: ```text node --version npm --version ``` En Windows, usa Símbolo del sistema (`cmd`) y comprueba también `where npx.cmd`. Si acabas de instalar Node.js, cierra Claude completamente y vuelve a abrirlo para que reciba el PATH actualizado. 2. Abre **Claude Desktop → Ajustes → Aplicación de escritorio → Desarrollador → Editar configuración**. Se abre `claude_desktop_config.json`: - Windows: `%APPDATA%\Claude\claude_desktop_config.json` - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` 3. Agrega `clatri` dentro de `mcpServers`. Si el archivo ya tiene `preferences`, conserva ese objeto: `mcpServers` va al mismo nivel, fuera de `preferences`. Conserva también los demás servidores. **Windows:** ```json { "mcpServers": { "clatri": { "command": "npx.cmd", "args": [ "-y", "mcp-remote", "https://api.clatri.com/mcp", "--header", "Authorization:${CLATRI_AUTH_HEADER}" ], "env": { "CLATRI_AUTH_HEADER": "Bearer clt_mcp_TU_TOKEN_AQUI" } } } } ``` **macOS:** usa el mismo bloque, cambiando `"command": "npx.cmd"` por `"command": "npx"`. Reemplaza el token de ejemplo por el tuyo. El espacio entre `Bearer` y el token se conserva en la variable de entorno. No añadas espacios a `Authorization:${CLATRI_AUTH_HEADER}`: esto evita el [problema de argumentos de Windows documentado por mcp-remote](https://github.com/punkpeye/mcp-remote#custom-headers). 4. Guarda el JSON y **sal completamente de Claude Desktop**. En Windows comprueba que no siga abierto en la bandeja del sistema. Después vuelve a abrirlo. 5. Verifica que `clatri` aparezca **En ejecución** en Desarrollador. Abre un chat nuevo y entra en **+ → Conectores** para comprobar que Clatri está disponible y habilitado. No necesitas una sección ni un chat especial de Clatri. 6. Escribe: **«Usa Clatri MCP y lista mis entidades»**. Claude debe ejecutar la herramienta, no responder solo de memoria. Este procedimiento corresponde al JSON manual. Las extensiones de escritorio `.mcpb` pueden usar el Node.js integrado en Claude; son [otro método de instalación](https://support.claude.com/en/articles/10949351-getting-started-with-local-mcp-servers-on-claude-desktop). 1. **Cursor → Settings → Cursor Settings → MCP** (o edita `~/.cursor/mcp.json` directamente). 2. Click **+ Add new MCP server**. 3. Selecciona transport **HTTP** y pega: - **Name:** `clatri` - **URL:** `https://api.clatri.com/mcp` - **Headers:** `Authorization: Bearer clt_mcp_TU_TOKEN_AQUI` 4. Guarda. Cursor muestra el estado de la conexión con un punto verde si conectó OK. Equivalente vía archivo: ```json { "mcpServers": { "clatri": { "url": "https://api.clatri.com/mcp", "headers": { "Authorization": "Bearer clt_mcp_TU_TOKEN_AQUI" } } } } ``` Edita `~/.codex/config.toml` y agrega: ```toml [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: ```toml [mcp_servers.clatri] url = "https://api.clatri.com/mcp" bearer_token_env_var = "CLATRI_MCP_TOKEN" ``` y en tu shell: ```bash 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: ```text ¿Quién soy en Clatri y a qué entidades tengo acceso? ``` ```text 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) El servidor expone herramientas de los distintos dominios — las mismas que usa el agente de Clatri por dentro, más `whoami` y `list_entities`, que solo existen en el MCP. 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_income_statement` | | *"Resume mis cuentas y balances actuales."* | `list_entities`, `read_user_accounts`, `read_account_and_savings` | | *"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?"* | `read_obligations` | | *"Qué medicamentos estoy tomando actualmente."* | `read_medications` | :::tip 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 Ajustes → Conexiones → Clatri MCP. Todas las operaciones quedan en el **audit log** (Ajustes → Conexiones → Clatri MCP → toca un token → 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 Ajustes → Conexiones → Clatri MCP → toca 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? Al terminar una tarea que modifica datos, el agente externo recibe la instrucción de llamar a `registrar_resumen_actividad`. Esto guarda una tarjeta **Actividad externa · MCP** en el chat de la entidad, con resumen, cambios desplegables y hora local. Las consultas no generan tarjetas. Depende de que el cliente siga la instrucción; no es un detector automático de sesiones ni una notificación push. La tarjeta contiene el informe del agente externo, no una verificación independiente de Clatri.
¿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 un límite de requests? Hoy **no** hay un límite de requests por minuto. Lo que sí controla el acceso son otras tres cosas, y son las que verás si algo falla: - **Tu suscripción** — si no está activa, el token responde `402 subscription_inactive`. - **Los scopes del token** — si intenta escribir con un token de solo lectura, `403 scope_denied`. - **Las entidades del token** — si intenta tocar una entidad fuera de su alcance, `403 entity_denied`. El MCP está pensado para uso humano normal a través de un cliente IA, no para automatización masiva. Si tu caso necesita volumen alto y sostenido, escríbenos antes. ## Contexto personal desde MCP `read_user_context` devuelve la descripción de la entidad activa, comportamiento, personalidad y preferencias compartidas entre canales. El cliente recibe instrucciones de leerlo al empezar una tarea; MCP no lo inyecta automáticamente en cada conversación externa. `buscar_memoria` recupera recuerdos históricos relevantes. `edit_entity_context` y `remember_user_preference` pueden utilizar una cita literal del usuario en la conversación externa si se omite `source_message_id`. Esa evidencia se etiqueta como **informada por el cliente**, no como verificada en el historial de Clatri. Las preferencias limitadas al chat no se comparten externamente; usa `channel_scope=all` cuando el usuario autorice compartirlas entre canales. Después de una actualización, reconecta el MCP para refrescar herramientas e instrucciones. Los tokens existentes siguen siendo válidos dentro de sus permisos. El enlace a la documentación permanece disponible después de crear tokens en Flutter y web. ## Totales y consumo al consultar desde Claude Para **«¿cuánto gasté o gané este mes/año?»**, pide el **estado de resultados** (`read_income_statement`). Usa el mismo criterio que **Ganado y gastado**: las transferencias entre cuentas propias y el capital de pagos de deuda no son ingresos ni gastos. Para entradas y salidas de dinero usa `read_cashflow_report`. `read_expenses` y `read_incomes` muestran detalles de movimientos y un total contable separado. La lista de detalles puede estar limitada: no debe sumarse para calcular el total del período. Ejemplo: «Usa Clatri MCP y consulta mi estado de resultados del 1 al 30 de septiembre de 2026. Indica ingresos, gastos y la herramienta utilizada». La consulta directa de estos datos no ejecuta el modelo conversacional de Clatri. No hace falta escribir «sin gastar tokens de Clatri»: esa frase no cambia la facturación. Claude mantiene su propio consumo y el acceso MCP requiere una suscripción activa de Clatri. ### Si aparece “Server disconnected” en Windows 1. Comprueba `node --version`, `npm --version` y `where npx.cmd` en `cmd`. 2. Usa `npx.cmd` como comando y el bloque con variable de entorno anterior. Si no se encuentra el ejecutable, usa su ruta completa devuelta por `where`, escapando las barras como `\\` en JSON. 3. Sal completamente de Claude y vuelve a abrirlo. 4. Si sigue fallando, abre **Desarrollador → clatri → Ver registros**. “Server disconnected” por sí solo no identifica si el fallo es de instalación, autenticación o red. Oculta tokens antes de compartir registros o capturas; si uno quedó expuesto, revócalo y genera otro.