Cómo conectar Claude Code con Supabase usando el MCP (con prompts listos)

Supabase es hoy el estándar para bases de datos y autenticación en proyectos modernos. Antes había que armar todo a mano: tablas, relaciones, policies, login, signup, recovery. Hoy existe el MCP oficial de Supabase (supabase-community/supabase-mcp), que le da a Claude Code acceso directo a tu proyecto para que haga todo eso automáticamente con prompts.

Esta guía sigue al pie de la letra la documentación oficial y agrega los prompts que más uso en proyectos reales.

📌 Nivel 4 de la ruta: Producción.

Esto es lo que separa una demo en localStorage de un producto real con base de datos — el que podés cobrarle a un cliente mes a mes.

Paso 0 — Antes de arrancar

Guía de Nivel 4. Es el salto a producción. Antes de meterte acá deberías tener:

→ Claude Code andando: Iniciar cualquier proyecto en Claude Code

→ Claro qué es un MCP: Qué es un MCP

→ Idealmente un sistema demo para migrar a base real: barberías, tatuajes o taller.

Recordá el flujo de Claude Code (2026): npm install -g @anthropic-ai/claude-code → corrés claude → entrás con tu cuenta de Claude en el navegador (plan Pro ~20 USD/mes o Max). Sin API key de console.anthropic.com.

Crear tu cuenta y proyecto en Supabase desde cero

La guía da por hecho que ya tenés un proyecto en Supabase. Si no lo tenés, este es el paso donde la mayoría se traba. Hacelo así:

1. Entrá a supabase.com y tocá Start your project. Te logueás con GitHub o con email. La cuenta es gratis.

2. Ya adentro, New project. Elegí tu organización (se crea una sola la primera vez), poné un nombre, generá una database password (guardala, la vas a necesitar) y elegí la región más cercana a tus clientes.

3. Esperá ~2 minutos a que Supabase aprovisione la base. Cuando termina, ya tenés un proyecto Postgres real corriendo.

Dónde sacar lo que vas a usar:

→ Project ID (el project_ref): menú lateral → Project Settings → General. Lo vas a pegar en el comando del MCP.

→ API keys (anon y service_role): Project Settings → API. La anon es la pública (va en el frontend). La service_role es la que salta todas las reglas — nunca la pegues en un prompt ni la subas a Git.

Lo mínimo que tenés que entender

El MCP escribe en tu base real. Antes de aprobar cambios, manejá estos 4 términos:

• Tabla → una planilla con columnas y filas (ej: clientes, turnos).

• RLS (Row Level Security) → reglas que deciden quién puede ver/editar cada fila. Sin RLS, cualquiera con la key pública lee todo. Con RLS, cada usuario ve solo lo suyo.

• Migración → un cambio versionado en la estructura de la base (crear tabla, agregar columna). Queda registrado, no es un toque suelto.

• read-only → modo donde el MCP solo lee, no escribe. Tu red de seguridad por defecto.

Con esos cuatro alcanza para entender qué estás aprobando.

Qué es el MCP de Supabase

El MCP (Model Context Protocol) es el estándar abierto que conecta LLMs con plataformas externas. El MCP de Supabase expone tu proyecto a Claude Code: listar tablas, aplicar migraciones, correr SQL, generar tipos TypeScript, consultar logs, ejecutar advisors de seguridad, deployar Edge Functions y manejar branches — sin copiar y pegar nada.

Antes de instalar: leé esto

El MCP corre con tus permisos de desarrollador. Antes de conectarlo, tres reglas que te van a evitar problemas:

1. No lo apuntes a producción. Usalo contra un proyecto de desarrollo, idealmente con datos no productivos u obfuscados.
2. Activá read-only mode si vas contra datos reales (?read_only=true en la URL).
3. Limitá el scope a un solo proyecto (?project_ref=<id>). Sin scope, el MCP ve todos los proyectos de tu organización.

La razón principal es prompt injection: si tu base tiene contenido generado por usuarios (tickets, mensajes, comentarios), un atacante puede meter instrucciones ahí adentro que el LLM podría llegar a ejecutar como tool calls. El MCP de Supabase envuelve los resultados SQL con instrucciones defensivas, pero no es infalible — mantené siempre activada la aprobación manual de tool calls en tu cliente.

Conectar Claude Code con Supabase (paso a paso)

Requisitos

• Claude Code instalado y logueado con tu cuenta (ver Paso 0)
• Un proyecto en Supabase ya creado (ver Paso 0)
• Terminal parada dentro de la carpeta de tu proyecto

1. Obtener el project_ref

En tu dashboard de Supabase, abrí Project Settings → General y copiá el Project ID. Ese es el project_ref que vas a usar para el scope. (Lo viste en el Paso 0.)

2. Agregar el MCP a Claude Code

El comando oficial (con scope al proyecto + read-only, recomendado por defecto):

claude mcp add --scope project --transport http supabase \
  "https://mcp.supabase.com/mcp?project_ref=TU_PROJECT_REF&read_only=true"

--scope project deja el registro en .mcp.json del repo (así lo comparte el equipo). Si preferís configurar a mano, agregá esto al .mcp.json en la raíz:

{
  "mcpServers": {
    "supabase": {
      "type": "http",
      "url": "https://mcp.supabase.com/mcp?project_ref=TU_PROJECT_REF&read_only=true"
    }
  }
}

3. Autenticar

Salí del IDE y abrí una terminal normal. Dentro de la carpeta del proyecto, corré:

claude /mcp

En el menú elegí supabase y luego Authenticate. Se abre el navegador con el OAuth de Supabase — autorizá el acceso a la organización que contiene el proyecto. Cuando termina, la pestaña se cierra sola.

4. Verificar la conexión

Volvé a Claude Code (claude) y mandá:

"Listá las tablas que tengo en Supabase y mostrame qué tools del MCP tenés disponibles."

Si responde con tus tablas reales (o con "la base está vacía") y enumera tools como list_tables / apply_migration / get_advisors, el MCP está conectado.

Tools disponibles y feature groups

El MCP expone tools agrupadas en feature groups. Por defecto se habilitan todas menos storage. Podés acotar con ?features=database,docs en la URL.

En read-only mode quedan deshabilitadas todas las tools mutantes: apply_migration, create_project, pause_project, restore_project, deploy_edge_function, todas las de branching y update_storage_config.

Local development (Supabase CLI)

Si corrés Supabase localmente con la CLI, el MCP está disponible en http://localhost:54321/mcp con un subset acotado de tools y sin OAuth (no hace falta autenticar).

Para self-hosted, ver la guía de enabling MCP server.

Prompts listos para usar

Asumen MCP conectado, claude corriendo dentro del proyecto y el read-only desactivado (read_only=false) para los prompts que escriben en la base. Para los de lectura/auditoría, dejá read-only activado.

Prompt 1 — Sistema de autenticación completo

Necesito armar el sistema de autenticación de mi proyecto en Supabase usando
el MCP. Quiero:

1. Email + password con confirmación por mail
2. Login con Google
3. Recuperación de contraseña
4. Tabla `profiles` enlazada a `auth.users` con: full_name, avatar_url, role
5. Trigger `on_auth_user_created` que inserte el profile automáticamente
6. RLS habilitado en `profiles` con políticas:
   - SELECT: cualquier autenticado puede leer cualquier profile
   - UPDATE: solo el dueño puede editar su propio profile
   - INSERT/DELETE: bloqueado (lo maneja el trigger)

Antes de tocar nada:
- Usá `list_tables` para ver qué hay ya
- Mostrame el plan completo (migraciones que vas a correr, en orden)
- Esperá mi confirmación explícita antes de cada `apply_migration`
- Después de aplicar, corré `get_advisors` para confirmar que no hay warnings

Prompt 2 — Diseñar el schema desde un dominio de negocio

Estoy armando [describí el negocio en una línea — ej: "un sistema de
reservas para un estudio de tatuajes, con clientes, sesiones, pagos y un
catálogo de servicios"].

Diseñá el schema completo en Supabase usando el MCP:
- Identificá entidades principales y relaciones (1:N, N:N)
- Tipos correctos: uuid para IDs, timestamptz para fechas, jsonb donde
  haga sentido, numeric(10,2) para dinero
- Índices en columnas que se filtran/joinean
- RLS habilitado en TODAS las tablas con datos de usuario
- Mostrame el ERD en texto (mermaid) antes de migrar
- Esperá mi OK antes de `apply_migration`

Cuando termine, generá los tipos TS con `generate_typescript_types` y
guardalos en `src/types/database.types.ts`.

Prompt 3 — Auditoría de seguridad y performance

Corré `get_advisors` sobre mi proyecto y categorizá los hallazgos:

[CRÍTICO] — tablas sin RLS, policies que exponen datos
[ALTO] — funciones con search_path inseguro, queries sin índice usadas
        frecuentemente
[MEDIO] — warnings de performance que no afectan seguridad

Para cada hallazgo:
- Explicá en una línea por qué importa
- Proponé el fix en SQL
- NO lo apliques — quiero revisarlo primero

Al final, ranqueá los fixes por relación impacto/esfuerzo.

Prompt 4 — Sincronizar tipos TypeScript

Usando el MCP de Supabase:
1. `generate_typescript_types` con el schema actual
2. Guardalos en `src/types/database.types.ts` reemplazando el contenido
3. Buscá en el código cualquier import roto o tipo viejo y actualizalo
4. Si hay queries con `.from('tabla')` que ya no tipan bien, listámelas para
   que yo decida si las arreglo

Prompt 5 — Aplicar una migración con plan previo

Quiero agregar la columna `[nombre]` (tipo [text/uuid/numeric]) a la tabla
`[tabla]`, NOT NULL con default `[valor]`, y un índice en esa columna.

- Usá `list_tables` para confirmar el estado actual
- Mostrame el SQL completo (CREATE/ALTER + índice) antes de tocar
- Aplicá con `apply_migration` SOLO después de mi "dale"
- Corré `get_advisors` después para confirmar que el cambio no rompió nada

Prompt 6 — Debug de un endpoint que devuelve 500

Mi endpoint [ruta o Edge Function] está fallando con 500. Usando el MCP:

1. `get_logs` para los servicios relevantes (api, postgres y, si aplica,
   edge functions) en los últimos 30 minutos
2. Identificá la query o función que está tirando el error
3. Si es SQL, mostrame el statement exacto y razoná qué puede estar mal
4. Proponé el fix concreto, pero NO lo apliques

Si el problema es una query lenta y no un error, sumá un análisis del plan
de ejecución con `execute_sql EXPLAIN ANALYZE ...`.

Prompt 7 — Deployar una Edge Function

Necesito una Edge Function `[nombre]` que [describí qué hace].

Inputs: [JSON shape]
Outputs: [JSON shape]
Side effects: [qué tablas toca, qué APIs externas llama]

Pasos:
- Escribí el código en Deno/TypeScript
- Usá el cliente de Supabase con la `service_role` SOLO si es estrictamente
  necesario (justificá)
- Mostrame el código completo antes de deployar
- Deployá con `deploy_edge_function` después de mi confirmación
- Probala con un `execute_sql` o un fetch de ejemplo y mostrame el resultado

Buenas prácticas operativas

• Branches de desarrollo (plan paid): create_branch → trabajás contra una copia → merge_branch cuando estás conforme. Es la red de seguridad estándar para cambios destructivos en producción.
• Read-only por defecto, mutaciones explícitas: dejá read_only=true en tu config y pasalo a false solo cuando vas a aplicar migraciones — y volvelo a true después.
• Aprobación manual de tool calls: en Claude Code, no autoaprobes tools del MCP de Supabase. Cada apply_migration o execute_sql mutante debería pedir tu OK.
• Advisors semanales: agendá el Prompt 3 una vez por semana — el MCP detecta agujeros de RLS y queries sin índice que pasan desapercibidos.
• Feature groups acotados: si tu proyecto no usa Edge Functions, sacá functions del query param. Menos tools = menos superficie de ataque y prompts más enfocados.
• Service role nunca en texto plano: el MCP usa OAuth con scopes acotados. No pegues nunca el service_role en un prompt.

Para qué te sirve esto si vendés

Acá está el salto de plata. Una demo en localStorage se ve linda pero se borra al cerrar el navegador: no es un producto, es una maqueta. Con Supabase atrás, ese mismo sistema guarda turnos, clientes y pagos de verdad.

Lo que cambia:

• Pasás de demo a producto real → algo que el negocio usa todos los días, no un truco de venta.

• Base de datos + auth reales → podés cobrar setup y un mensual por mantenerlo vivo.

• Un solo backend sirve para todos tus clientes → aprendés esto una vez y lo replicás en cada sistema que entregás.

Es la diferencia entre vender "una página" una sola vez y vender un sistema que te paga todos los meses.

Cómo cobrar esto

Un sistema con base de datos real no se cobra como una landing. Tiene más trabajo y, sobre todo, sigue funcionando para el negocio mes a mes. Rangos referenciales para LATAM:

• Setup inicial: 500 a 1.500 USD según el alcance (cuántas tablas, auth, paneles, reportes).

• Retainer mensual: 100 a 300 USD por mantenimiento, hosting, backups y cambios chicos.

El retainer es el que cambia el juego. El costo del Pro de Supabase (~25 USD/mes) sale de ahí y te queda margen. No estás vendiendo un trabajo único: estás armando un ingreso recurrente.

Tu turno

Agarrá uno de los sistemas demo (barbería, tatuajes o taller), creá un proyecto en Supabase siguiendo el Paso 0, conectá el MCP en read-only y corré el Prompt 2 para diseñar el schema real del sistema. Después pasá a read-only false y aplicá la primera migración.

Checklist de autoverificación:

→ ¿Creaste el proyecto en Supabase y tenés a mano el project_ref?

→ ¿claude /mcp muestra supabase como Authenticated?

→ ¿El Prompt 1 o 2 te mostró el plan y esperó tu OK antes de migrar?

→ Después de migrar, ¿get_advisors (Prompt 3) salió sin warnings críticos de RLS?

Si las cuatro dieron sí, tenés un backend de producción listo para cobrar.

Siguiente paso

Ya sabés montar el backend que sostiene cualquier sistema vendible. Ahora el cierre comercial:

→ Construí soluciones de IA y vendéselas a negocios

Y si querés productos listos para conectar a este backend:

• Sistema de gestión para barberías
• Sistema para estudios de tatuajes
• Sistema para talleres mecánicos

La mejor comunidad de IA

Esto no termina acá. En la comunidad compartimos lo que funciona de verdad: proyectos reales, precios que cierran y los nudos de llevar esto a clientes que pagan.

→ Sumate a la comunidad de WhatsApp 🚀