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.

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: npm install -g @anthropic-ai/claude-code
• Un proyecto en Supabase (supabase.com)
• 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.

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.

Próximos pasos

1. Instalá el MCP siguiendo los 4 pasos de arriba con ?project_ref=...&read_only=true.
2. Verificá con el Prompt 3 (auditoría) que tu base está sana.
3. Pasá a read-only false y arrancá con el Prompt 1 (auth) o Prompt 2 (schema desde cero).

Si todavía no tenés un proyecto donde meter esto, podés usar como base alguno de los sistemas open source — todos arrancan con datos mock en localStorage y están pensados para migrar a Supabase con estos mismos prompts:

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