Levantar el MCP de Dynamo Auth

0. Qué necesitás antes de empezar

• Node.js 20+ instalado — corré node --version, debe imprimir v20.x o más. Con Node 18 nada de esto funciona.
• El repo auth-dynamo clonado en tu máquina. Si no lo tenés: git clone git@github.com-dynamo:DynamoTechTVT/auth-dynamo.git.
• gh (GitHub CLI) autenticado con la cuenta de Dynamo. El paquete depende de @dynamotechtvt/mcp-core, que vive en GitHub Packages (privado) — sin token no instala. Verificá con gh auth status que aparezca la organización DynamoTechTVT.
• Un usuario real de Supabase Auth. Para que las tools devuelvan algo útil necesitás ser global-admin (la mayoría) o al menos project-admin del proyecto que consultás (auth_list_project_members y auth_list_project_app_access). Si no lo sos, vas a ver listas vacías — no errores.
• El ambiente contra el que vas a apuntar. Este manual usa QA (bxogqotctuurtcgjakfz.supabase.co) porque es el ambiente seguro para probar — este MCP tiene 6 tools de escritura sobre el sistema de permisos, así que no repitas estos pasos contra PROD sin saber lo que hacés.

1. Instalar dependencias del paquete mcp/

Andá a la carpeta mcp/ del repo (NO la raíz, son paquetes Node distintos — mcp/ tiene su propio package-lock.json y no está en los workspaces del root):

cd auth-dynamo/mcp
NODE_AUTH_TOKEN=$(gh auth token) npm ci

Qué tenés que ver: una línea final del estilo added 252 packages in 11s.

401 Unauthorized = tu gh no está autenticado con la cuenta de Dynamo. 403 Forbidden = la cuenta está bien pero al repo le falta el permiso de lectura sobre el paquete; eso lo otorga Daniel en Package settings → Manage Actions access → auth-dynamo: Read.

2. Generar tu sesión (npm run login)

El MCP necesita un JWT de sesión guardado en tu disco (~/.dynamo/dynamo-qa-session.json). Exportá estas 4 variables en la misma terminal donde vas a correr el comando (no las guardes en ningún archivo commiteado):

export SUPABASE_URL="https://bxogqotctuurtcgjakfz.supabase.co"
export ANON_KEY="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6ImJ4b2dxb3RjdHV1cnRjZ2pha2Z6Iiwicm9sZSI6ImFub24iLCJpYXQiOjE3ODIxODY5OTcsImV4cCI6MjA5Nzc2Mjk5N30.IL2_oF_UWFuOMZfvD6rJ4g4f87q4f9ioROJrxGss0qg"
export DYNAMO_LOGIN_EMAIL="tu-email@ejemplo.com"
export DYNAMO_LOGIN_PASSWORD="tu-password-de-supabase-auth"

Corré:

npm run login

Qué tenés que ver: primero una línea Ambiente: QA — la sesión se escribe en /Users/<vos>/.dynamo/dynamo-qa-session.json, y después la confirmación de que la sesión quedó guardada.

Si en cambio el login falla con credenciales inválidas, tu usuario probablemente no tiene password configurado (entrás siempre por magic-link). En ese caso usá el fallback OTP, que son dos corridas:

unset DYNAMO_LOGIN_PASSWORD
export DYNAMO_LOGIN_OTP=1
npm run login
# Te llega un código de 6 dígitos al email. Corré de nuevo con el código:
export DYNAMO_LOGIN_OTP_CODE="123456"
npm run login

Verificación de este paso: corré ls -l ~/.dynamo/dynamo-qa-session.json — la línea tiene que empezar con -rw-------. Esos permisos (600) son a propósito: el archivo tiene tus tokens. Si el archivo no existe, no sigas hasta que exista.

3. Compilar el server

npm run build

Qué tenés que ver: nada. Cero salida es éxito (tsc solo habla cuando hay errores). Confirmá que generó el ejecutable con ls dist/server.js.

4. Configurar Claude Code (transporte stdio)

Claude Code necesita la ruta absoluta al dist/server.js. Conseguila con pwd desde mcp/ y reemplazala abajo:

claude mcp add dynamo-auth \
  --env SUPABASE_URL=https://bxogqotctuurtcgjakfz.supabase.co \
  --env ANON_KEY="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6ImJ4b2dxb3RjdHV1cnRjZ2pha2Z6Iiwicm9sZSI6ImFub24iLCJpYXQiOjE3ODIxODY5OTcsImV4cCI6MjA5Nzc2Mjk5N30.IL2_oF_UWFuOMZfvD6rJ4g4f87q4f9ioROJrxGss0qg" \
  -- node /RUTA/ABSOLUTA/A/auth-dynamo/mcp/dist/server.js

Qué tenés que ver: Added stdio MCP server dynamo-auth to local config. Verificá con claude mcp list — tiene que aparecer dynamo-auth con ✓ Connected a la derecha. El server no necesita tokens acá: lee la sesión directo del archivo del paso 2.

Equivalente en JSON (editar a mano)

{
  "mcpServers": {
    "dynamo-auth": {
      "command": "node",
      "args": ["/RUTA/ABSOLUTA/A/auth-dynamo/mcp/dist/server.js"],
      "env": {
        "SUPABASE_URL": "https://bxogqotctuurtcgjakfz.supabase.co",
        "ANON_KEY": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6ImJ4b2dxb3RjdHV1cnRjZ2pha2Z6Iiwicm9sZSI6ImFub24iLCJpYXQiOjE3ODIxODY5OTcsImV4cCI6MjA5Nzc2Mjk5N30.IL2_oF_UWFuOMZfvD6rJ4g4f87q4f9ioROJrxGss0qg"
      }
    }
  }
}

Claude Desktop: el mismo bloque JSON, pegado en claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json). Reiniciá Claude Desktop después de guardar.

Si dice ✗ Failed to connect: casi siempre es una de tres — la ruta del server.js está mal, no corriste npm run build, o falta una de las dos variables de entorno. Arrancalo a mano para ver el error real:

SUPABASE_URL="https://bxogqotctuurtcgjakfz.supabase.co" ANON_KEY="<ANON_KEY>" node dist/server.js

Tiene que quedar colgado esperando (es correcto: habla por stdin/stdout) y escribir [dynamo-auth-mcp] Listo — v0.1.0, 12 tools registradas, transport stdio.. Cortalo con Ctrl+C.

5. Verificar que responde

Reiniciá la sesión de Claude Code (o abrí una nueva) y pedile:

Usá auth_session_status para decirme contra qué ambiente estoy corriendo y quién soy.

Qué tenés que ver: algo así.

{
  "authenticated": true,
  "email": "tu.email@dynamotech.co",
  "user_id": "…",
  "env": "QA",
  "version": "0.1.0",
  "is_global_admin": true,
  "admin_project_ids": [],
  "multi_client": false
}

Si ves eso, terminaste. Si ves "authenticated": false, la sesión no se hidrató: repetí el paso 2 y reiniciá Claude Code — el MCP lee la sesión al arrancar, no en cada llamada.

6. auth_session_status — el diagnóstico antes de operar

Es la única tool sin requisitos, siempre corrible primero. Te dice quién sos (email/user_id), contra qué ambiente estás apuntando (DEV/QA/PROD, resuelto del SUPABASE_URL), si sos global-admin, de qué proyectos sos project-admin (admin_project_ids) y si tenés la flag multi_client. Nunca devuelve el JWT, solo su expiry.

7. Inventario de tools (12 total)

6 de lectura + 6 de escritura. Cada una valida su input y traduce cualquier error de la base a un mensaje legible en español — nunca se escapa una excepción cruda. No hace falta llamarlas por nombre: pedile a Claude lo que querés en castellano ("dale acceso a analytics a juan@cliente.com en el proyecto Acme") y elige la herramienta sola.

Lectura (6)

Escritura (6)

El modelo de acceso, en tres frases

Sin esto las respuestas no tienen sentido:

1. Todo es por proyecto. No existe "tener acceso a forms" a secas: existe "tener acceso a forms en el proyecto X".
2. Son dos capas, y el orden importa. Primero la app se habilita en el proyecto (auth_set_project_app / auth_list_project_apps), y recién después se le puede dar a un usuario (auth_set_app_access / auth_list_project_app_access). Dar acceso a una app que no está habilitada en el proyecto falla.
3. Los global-admins no aparecen en la lista de accesos. Pueden usar todo y son miembros automáticos de todos los proyectos, pero por su rol — no por una fila de permiso. Que alguien no figure en auth_list_project_app_access no quiere decir que no pueda entrar.

Cuatro cosas que hay que saber antes de escribir

• Habilitar o deshabilitar una app arrastra a mucha gente de golpe. Al habilitarla, la app se le da automáticamente a todos los administradores del proyecto. Al deshabilitarla, se borran todos los accesos de esa app en ese proyecto — y volver a habilitarla no los devuelve: hay que otorgarlos de nuevo uno por uno. Por eso deshabilitar exige confirm_cascade: true, y la tool se niega antes de tocar la base si no lo pasás. Antes de deshabilitar, pedile a Claude la lista actual de accesos y guardala: es la única forma de poder reconstruirla.
• La app auth no es una app: es el interruptor de "administrador del proyecto". Dársela a alguien lo promueve a admin de ese proyecto; quitársela lo degrada. Y promover a alguien le da automáticamente todas las apps habilitadas del proyecto, no solo las que pidas. Si lo que querés es darle una herramienta, no uses auth.
• Las apps que no estén habilitadas en el proyecto se saltean en silencio. Si metés a alguien pidiendo ["forms", "crm"] y el proyecto no tiene crm habilitada, la operación no falla: le da forms y se olvida de crm, sin avisar. La función de base no puede reportarlo (devuelve void), así que la tool te lo advierte en la respuesta. Verificá siempre el resultado real con auth_list_project_app_access.
• Desactivar a alguien no lo saca en el acto. Le bloquea la renovación del token, pero su sesión abierta sigue viva hasta que expire — hasta una hora. El campo sessions_revoked viene siempre en false, y no es un bug: el corte inmediato no existe por esta vía.

Las dos operaciones privilegiadas van por Edge Function

auth_invite_user y auth_set_user_deactivated necesitan la service_role key de Supabase — crear un usuario y banearlo no se pueden hacer con una sesión de usuario común. El MCP nunca ve esa clave. Esas dos operaciones viven dentro de Edge Functions (admin-invite-user y admin-deactivate-user): el MCP las invoca como vos, y la función vuelve a verificar tus permisos con tu propio JWT (construye un cliente con tu bearer y llama is_global_admin) antes de usar su clave privilegiada. Hay un test automatizado que falla el CI si alguien intenta meter esa clave en el MCP (mcp/src/__tests__/no-service-role.test.ts).

Lo que este MCP deliberadamente NO puede hacer

No hay tools para promover a alguien a global_admin, para cambiar por la vía directa quién es administrador de un proyecto, ni para borrar un proyecto. No es un olvido: las dos primeras son escalada de privilegios y la tercera arrastra en cascada a miembros y apps de forma irreversible. Se hacen desde el portal, con una persona mirando. Si Claude te dice que no puede promover a alguien a global-admin, está funcionando bien. Tampoco hay borrado de usuarios, porque el sistema no borra usuarios: los desactiva (auth_set_user_deactivated), que es reversible y queda auditado. Y no es un bypass de permisos: usa tu sesión — lo que no ves en el portal tampoco lo ves acá — ni toca infraestructura: un write del MCP no es un deploy.

8. Cuando el refresh token expira

Si después de mucho tiempo sin usarlo las tools empiezan a fallar con mensajes de sesión inválida/expirada, repetí el paso 2 (npm run login) y reiniciá Claude Code — no hace falta reconfigurar Claude Code de nuevo.

9. Troubleshooting rápido

• Una lista vacía cuando esperabas datos — es lo primero que hay que descartar, y casi nunca es un bug. El control de permisos está dentro del filtro: si no sos global-admin no recibís un error, recibís cero filas. Corré auth_session_status y mirá is_global_admin.
• "No tenés permiso para esta operación" — ese sí es el forbidden explícito, y viene de la base, no del MCP. La mayoría de estas operaciones exigen global-admin; algunas aceptan además al project-admin de ese proyecto en particular.
• auth_list_users devuelve exactamente 100 resultados — no es casualidad: la función tiene un tope de 100 filas del lado del servidor, ordenadas por email, y no se puede paginar. Estás viendo los primeros 100 alfabéticamente y hay más que no ves. Usá el parámetro de búsqueda para acotar.
• "No se pudo identificar al usuario" al pasar un email — la resolución email→user_id también tiene el gate por filtro: si no sos global-admin devuelve "no encontrado" en lugar de "no tenés permiso". Un email que existe puede darte "no existe" simplemente porque no podés verlo.
• "La app no está habilitada en el proyecto" — te salteaste la capa de arriba. Primero auth_set_project_app, después auth_set_app_access.
• "El usuario no es miembro del proyecto" — agregalo primero con auth_add_project_member; podés pasarle las apps en la misma llamada y te ahorrás el paso.
• "No se puede sacar a un global-admin de un proyecto" — correcto y es incondicional: ni otro global-admin puede. Un global-admin es miembro automático de todos los proyectos y esa membresía no se regenera sola. Si querés sacarle el acceso, la tool es auth_set_user_deactivated.
• "Es el último global-admin activo" — bloqueo anti-lockout: si lo desactivás, la plataforma queda sin nadie capaz de reactivar a nadie. Promové o reactivá otro global-admin primero.
• deactivated_at con fecha en vez de un usuario que desapareció — el sistema no borra usuarios: los desactiva. Sigue existiendo, conserva su historia y puede reactivarse.
• 403 Forbidden en el npm ci — falta el grant de lectura del paquete @dynamotechtvt/mcp-core (§1).
• Tools desactualizadas después de un git pull — faltó npm run build (§3).

Tabla completa de errores y causas: Troubleshooting.