Exponer Supabase a tu agente vía MCP

El protocolo MCP (Model Context Protocol) permite a Claude Code conectarse a herramientas externas y utilizarlas directamente en tus conversaciones. Supabase proporciona un servidor MCP oficial que expone tu base de datos, tus funciones Edge, tu auth y muchos otros recursos a tu agente. Esta lección te guía desde la generación del token hasta la primera prueba en el terminal.

Generar un personal access token

El servidor MCP de Supabase se autentica con un personal access token vinculado a tu cuenta de Supabase, no a un proyecto en concreto. Un único token es suficiente para acceder a todos tus proyectos.

1. Abre el dashboard de Supabase, haz clic en tu avatar en la parte inferior izquierda y luego en Account > Access Tokens.
2. Haz clic en Generate new token.
3. Dale un nombre descriptivo, por ejemplo claude-code-mcp.
4. Copia el token de inmediato: no se mostrará de nuevo después de cerrar la ventana.

Añadir el servidor MCP a Claude Code

El servidor MCP de Supabase funciona en modo HTTP: se ejecuta en los servidores de Supabase en la dirección https://mcp.supabase.com/mcp. No necesitas instalar nada localmente. Solo tienes que indicarle a Claude Code dónde está y cómo autenticarse.

Mediante el comando CLI (recomendado)

$claude mcp add --transport http supabase https://mcp.supabase.com/mcp --header "Authorization: Bearer TU_ACCESS_TOKEN"

Reemplaza TU_ACCESS_TOKEN por el token que acabas de generar. El comando registra el servidor en tu configuración de Claude Code con el scope local (por defecto, propio de tu usuario en esta máquina).

Mediante un archivo .mcp.json (para compartir la configuración con tu equipo)

Si trabajas en un proyecto versionado y quieres que todo el equipo se beneficie del servidor MCP, crea un archivo .mcp.json en la raíz del proyecto:

{
  "mcpServers": {
    "supabase": {
      "type": "http",
      "url": "https://mcp.supabase.com/mcp",
      "headers": {
        "Authorization": "Bearer ${SUPABASE_ACCESS_TOKEN}"
      }
    }
  }
}

La notación ${SUPABASE_ACCESS_TOKEN} se resuelve automáticamente desde las variables de entorno de tu shell. Cada miembro del equipo exporta su propia variable y el token nunca transita por el repositorio.

Verificar la conexión

Una vez añadido el servidor, comprueba que Claude Code lo reconoce correctamente.

$claude mcp list

Deberías ver supabase en la lista con su URL. Para ir más lejos, lanza Claude Code y escribe /mcp: el comando muestra el estado en tiempo real de cada servidor (conectado, en espera o con error) y el número de herramientas disponibles.

Probar con una primera consulta

Lanza Claude Code en tu terminal y plantea una pregunta que requiera consultar tu base de datos de Supabase.

$claude

Una vez en la interfaz de chat, prueba este prompt:

Lista las tablas de mi proyecto de Supabase y describe su estructura.

Si hay varios proyectos asociados a tu cuenta, Claude Code te pedirá cuál usar. También puedes apuntar a un proyecto concreto desde el principio añadiendo ?project_ref=TU_PROJECT_REF a la URL del servidor MCP en tu configuración.

Lo que puede hacer el servidor MCP

El servidor expone varios grupos de herramientas activados por defecto:

• Database: listar tablas y extensiones, leer el registro de migraciones, ejecutar SQL arbitrario.
• Development: obtener la URL de la API, las claves públicas, generar tipos TypeScript.
• Edge Functions: listar, inspeccionar y desplegar tus funciones.
• Debugging: consultar los logs de servicios y los consejos de seguridad.
• Docs: buscar en la documentación de Supabase directamente desde el agente.

El grupo Storage está desactivado por defecto. El grupo Branching requiere un plan de pago.