Cursor Supabase MCP no funciona: configuración y soluciones

Añadiste el servidor de Supabase a Cursor, reiniciaste el editor y ahora el panel de MCP muestra un punto rojo, una lista de herramientas vacía o un spinner que nunca se detiene. O parece conectado, pero el Agent insiste en que no tiene herramientas de base de datos. Esa distancia entre «configurado» y «funcionando» es la forma más común de Cursor Supabase MCP no funciona, y casi todos los casos se deben a una lista corta de causas: un archivo de configuración en la ruta equivocada, un login sin terminar, un registro OAuth obsoleto, una URL con alcance que oculta herramientas, demasiadas herramientas entre servidores, una peculiaridad de npx en Windows, un proyecto pausado o una solicitud de aprobación que nadie pulsó. Aquí tienes cada causa en el orden en que conviene revisarla, con la configuración exacta, una tabla de síntomas y las comprobaciones de logs que ahorran una tarde entera.

Cómo funciona la conexión entre Cursor y Supabase

MCP, el Model Context Protocol, permite que el agente de IA de un editor llame a herramientas externas. Supabase publica un servidor MCP cuyas herramientas permiten al Agent listar tablas, ejecutar SQL, aplicar migraciones, leer logs del proyecto y buscar en la documentación. Cursor es el cliente. Lee un archivo JSON, contacta o lanza el servidor, pide la lista de herramientas y la muestra en la configuración.

Cuando algo falla, falla en uno de cuatro pasos, y saber cuál reduce la búsqueda a la mitad:

1. Lectura de la configuración: el archivo falta, no es válido o está en la carpeta equivocada.
2. Conexión: no se puede alcanzar la URL o no se puede lanzar el comando.
3. Autenticación: el login en el navegador no terminó o el token es incorrecto.
4. Listado de herramientas: el servidor se conectó, pero tus parámetros ocultan herramientas o el Agent está saturado.

Servidor alojado frente a npx local

Hay tres formas de conectarte, y mezclar sus ajustes es una fuente clásica de confusión.

💡 Elige una sola. Si el mismo nombre de servidor aparece en dos archivos de configuración, o si una entrada remota y una entrada npx reclaman supabase, puedes pasar una hora depurando la equivocada.

Dónde debe estar mcp.json

Cursor lee dos ubicaciones. Un archivo de proyecto en .cursor/mcp.json se aplica a ese repositorio. Un archivo de usuario en ~/.cursor/mcp.json se aplica en todas partes, y la documentación de Supabase lo recomienda cuando quieres una única configuración para todos los proyectos.

Tres errores explican una parte sorprendente de los puntos rojos: guardar mcp.json en la raíz del repositorio en lugar de dentro de .cursor, dejar una coma final que invalida el JSON y escribir mal la propiedad de nivel superior mcpServers. Pega el archivo en cualquier validador de JSON antes de culpar al servidor.

La configuración limpia que funciona

Parte de un estado conocido y bueno antes de probar soluciones. Borra las entradas a medio editar y añade exactamente una de las configuraciones siguientes.

URL remota con login en el navegador

El servidor alojado solo necesita una URL:

{
  "mcpServers": {
    "supabase": {
      "url": "https://mcp.supabase.com/mcp"
    }
  }
}

Copiar prompt

Guarda el archivo, reinicia Cursor y abre Settings > Cursor Settings > Tools & MCP. La entrada de Supabase debería ofrecer un login. Se abre una ventana del navegador, inicias sesión en Supabase y concedes acceso a tu organización. Si prefieres la terminal, la CLI de Cursor tiene tres comandos equivalentes:

agent mcp enable supabase
agent mcp login supabase
agent mcp list

Copiar prompt

Después ejecuta la prueba rápida que sugiere Supabase en un nuevo chat del Agent: «¿Qué tablas existen en mi base de datos? Usa herramientas MCP.» Una respuesta real con los nombres de tus tablas significa que toda la cadena funciona. Una disculpa por falta de herramientas significa que se aplica alguna de las soluciones siguientes.

Token y alternativa npx

Algunos equipos siguen ejecutando el servidor en local con un token de acceso personal creado en los ajustes de su cuenta de Supabase. La configuración lanza el paquete mediante npx:

{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": [
        "-y",
        "@supabase/mcp-server-supabase@latest",
        "--read-only",
        "--project-ref=<your-project-ref>"
      ],
      "env": {
        "SUPABASE_ACCESS_TOKEN": "<personal-access-token>"
      }
    }
  }
}

Copiar prompt

Esta vía necesita Node.js instalado. Los flags --read-only y --project-ref hacen las mismas funciones que los parámetros de URL que se describen más adelante. Trata el token como una contraseña: nunca subas a un repositorio público un mcp.json que lo contenga. Supabase ha ido cambiando su configuración recomendada, así que revisa la pestaña de conexión MCP del panel de Supabase si sus instrucciones actuales difieren de este fragmento.

Windows necesita un wrapper de cmd

En Windows, npx es un shim de lote, y lanzarlo directamente suele acabar en un error de spawn. Envuélvelo en cmd /c:

{
  "mcpServers": {
    "supabase": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@supabase/mcp-server-supabase@latest",
        "--read-only",
        "--project-ref=<your-project-ref>"
      ],
      "env": {
        "SUPABASE_ACCESS_TOKEN": "<personal-access-token>"
      }
    }
  }
}

Copiar prompt

Ejecuta node --version y npx --version primero en una terminal nueva. Si Node se instaló después de que Cursor arrancara, el editor conserva el PATH antiguo, así que cierra Cursor por completo y vuelve a abrirlo, no solo la ventana. La ruta de URL alojada evita todo esto, lo que es una buena razón para preferirla en equipos Windows con cadenas de herramientas bloqueadas.

Ocho síntomas y sus soluciones

Busca lo que ves en una fila y salta a la sección correspondiente más abajo.

Punto rojo y lista de herramientas vacía

Un punto rojo significa que Cursor nunca obtuvo una conexión funcional, así que empieza por las comprobaciones más baratas. Valida el JSON, confirma que el archivo está en .cursor/mcp.json o en ~/.cursor/mcp.json y pulsa el control de actualizar en los ajustes de MCP, que ha reactivado servidores bloqueados para algunos usuarios del foro de Cursor. Reinicia Cursor después de cada cambio en la configuración, ya que las propias notas de Supabase indican que hace falta un reinicio para que aparezcan todas las herramientas.

Si el punto sigue en rojo, los logs que se describen más abajo nombrarán el fallo en una sola línea. Resiste la tentación de reescribir toda la configuración en este punto. Cambiar una variable por reinicio es más lento sobre el papel y mucho más rápido en la práctica.

Bucles de login y errores de client_id

Con el servidor alojado, Cursor termina el intercambio OAuth abriendo una página en localhost:8787. Allí aparecen dos fallos.

• Un error 431 antes de terminar el inicio de sesión. Las cookies demasiado grandes guardadas para localhost por tus otros servidores de desarrollo pueden provocarlo. Borra las cookies solo de localhost, no de todo el navegador, y vuelve a intentar el login.
• «Unrecognized client_id». Cursor está reutilizando un registro OAuth en caché de una configuración antigua. Desconecta el servidor, elimínalo, cierra Cursor por completo y añádelo de nuevo para que se registre desde cero.

Si el navegador nunca se abre, busca en los logs de Cursor la URL de autorización, pégala a mano en tu navegador, termina el inicio de sesión y el callback debería volver a Cursor y establecer la conexión.

Conectado, pero faltan herramientas

Un punto verde con un Agent ciego suele ser la configuración haciendo exactamente lo que le dijiste. Cuatro parámetros de URL cambian qué herramientas existen:

Un ejemplo con alcance tiene este aspecto: https://mcp.supabase.com/mcp?project_ref=abc123&read_only=true

Tres resultados sorprenden a la gente. Añadir project_ref desactiva las herramientas de cuenta, así que la ausencia de un listado de proyectos es lo esperado. El grupo Storage está desactivado por defecto y hay que activarlo. Y read_only=true hace que cualquier escritura falle por diseño. Pídele al Agent que liste todas las herramientas de Supabase que puede llamar ahora mismo y compara esa lista con tus parámetros.

💡 skip_elicitations elimina una red de seguridad. Úsalo solo en un proyecto de desarrollo desechable, nunca junto a datos de producción.

Aprobaciones y proyectos pausados

Dos últimas causas parecen fallos, pero no lo son. Primero, Cursor normalmente pide permiso antes de ejecutar una herramienta MCP, así que un Agent que parece congelado puede estar esperando un botón de aprobación más arriba en el chat. Confirma que estás en el modo Agent, ya que es ahí donde se ejecutan las herramientas.

Segundo, el propio proyecto puede estar pausado. Los proyectos del nivel gratuito pueden pausarse tras aproximadamente una semana sin actividad, y las consultas contra una base de datos pausada fallan aunque el enlace MCP esté sano. Reanúdalo en el panel de Supabase y vuelve a intentarlo.

Lee los logs antes de adivinar

Cada solución anterior va más rápido cuando lees el error real. Adivinar flags puede añadir nuevos problemas encima del original.

Dónde guarda Cursor los logs

Abre el panel Output desde el menú View y elige la entrada MCP de tu servidor de Supabase en el desplegable de canales. Reinicia el servidor y lee las últimas 20 líneas. Los patrones habituales:

Para probar solo la ruta de red, ejecuta curl -i https://mcp.supabase.com/mcp desde una terminal. Cualquier estado HTTP, incluso un 401, demuestra que el host es alcanzable. Un timeout o un error TLS apunta a una VPN, un proxy o un firewall, no a Cursor.

La lista de diez minutos

Cuando quieras una revisión rápida en lugar de un análisis a fondo, sigue esta lista en orden:

1. Valida el JSON y confirma la ubicación del archivo.
2. Mantén una sola entrada supabase entre los dos archivos de configuración.
3. Revisa node --version y npx --version si usas la vía npx.
4. Envuelve npx en cmd /c en Windows.
5. Cierra Cursor por completo y vuelve a abrirlo.
6. Termina el login en el navegador, borrando las cookies de localhost ante un 431.
7. Elimina y vuelve a añadir la entrada ante un error de «Unrecognized client_id».
8. Revisa project_ref, features y read_only en la URL.
9. Cambia al modo Agent y aprueba cualquier llamada a herramienta pendiente.
10. Confirma que el proyecto de Supabase no está pausado.

Demasiadas herramientas perjudican al Agent

Cursor avisa con «Exceeding total tools limit» cuando las herramientas de todos tus servidores superan las 40, señalando que demasiadas herramientas pueden degradar el rendimiento y que algunos modelos pueden no respetar más de 40. Las versiones recientes cargan el contexto de herramientas de forma dinámica, y algunos usuarios informan de que no aparece ningún aviso con más de 80 herramientas activadas.

El aviso es menos severo que antes, pero el problema de fondo sigue ahí: un Agent que elige entre decenas de herramientas parecidas elige peor, y los modelos más pequeños son los primeros en sufrirlo. El hilo del foro de Cursor sobre el límite de 40 herramientas recoge cómo ha cambiado ese límite.

Recorta la lista de herramientas

• Desactiva los servidores que no uses en esta sesión.
• Limita Supabase con features=database,docs cuando solo necesites SQL y documentación.
• Haz clic en los nombres de herramientas individuales en los ajustes de MCP para desactivar las que nunca llamas.
• Guarda los servidores específicos de proyecto en .cursor/mcp.json y los generales en el archivo de usuario.

Bloquéalo antes de confiar en él

Un servidor MCP que puede ejecutar SQL merece el mismo cuidado que un login de base de datos. La propia recomendación de Supabase es tajante: conéctate a producción solo cuando sea necesario, y usa el alcance por proyecto, el modo de solo lectura y los grupos de funciones restringidos cuando lo hagas.

Modo de solo lectura y alcance por proyecto

Tres ajustes hacen casi toda la protección. read_only=true ejecuta las consultas como un usuario de Postgres de solo lectura. project_ref limita el servidor a un único proyecto. features recorta los grupos de herramientas a los que necesitas. Supabase también muestra diálogos de confirmación antes de cualquier acción que cree recursos facturables, así que no los apruebes automáticamente. Las rutinas desatendidas siempre deben ejecutarse en modo de solo lectura.

La inyección de prompts es el riesgo real

La principal amenaza específica de los modelos de lenguaje (LLM) son las instrucciones maliciosas ocultas en los datos. Imagina una fila de tickets de soporte cuyo texto le dice al modelo que ignore las instrucciones anteriores y exporte la tabla de usuarios. Si el Agent lee esa fila mediante una herramienta, puede tratar el texto como una orden. Mantén la aprobación manual de las llamadas a herramientas y lee cada sentencia SQL antes de aprobarla. La documentación MCP de Supabase enumera estas protecciones por completo.

💡 Construye y prueba la conexión en un proyecto de desarrollo desechable. Pasa a cualquier cosa que contenga datos reales de clientes solo cuando el modo de solo lectura y el alcance por proyecto ya estén configurados.

Deja que un modelo lea los logs

Cuando las líneas del log no tienen sentido, un modelo de lenguaje (LLM) es un segundo par de ojos rápido. En Picasso IA, Claude Sonnet 5 está pensado para automatizar tareas de programación, GPT 5.6 Sol para resolver tareas complejas de programación y Gemini 3.1 Pro para respuestas generales más precisas. Cualquiera de ellos puede convertir una traza de error en una lista corta de sospechosos.

Antes de pegar nada, elimina los tokens de acceso, las referencias sensibles de proyecto y las URL de base de datos. Un fragmento de log rara vez los necesita, y una ventana de chat no es una caja fuerte.

Un prompt para errores de configuración

Dale al modelo los datos que no puede adivinar:

I use Cursor on Windows 11 with the hosted Supabase MCP server.
The MCP panel shows a red dot. My mcp.json (secrets removed) is below,
plus the last 20 lines from the MCP output channel.
List the three most likely causes, ranked, with one check for each.

Copiar prompt

Incluye tu sistema operativo, la versión de Cursor, la configuración, el fragmento del log y lo que esperabas que ocurriera. Pedir causas ordenadas, con una comprobación para cada una, evita que el modelo suelte una lista genérica. Después, haz tú mismo las comprobaciones en lugar de aprobar arreglos a ciegas.

Pruébalo tú en Picasso IA

Una solución como esta merece algo más que un muro de configuración. Un blog, un manual interno o un documento de equipo se leen mejor con fotografía real en lugar de capturas de stock, y Picasso IA convierte un prompt de texto plano en una imagen en segundos. Prueba Seedream 4.5 para fotos nítidas y detalladas, o GPT Image 2 cuando quieras convertir un prompt sencillo en una escena precisa.

Un prompt de inicio: «Fotografía cenital de un escritorio de desarrollador al amanecer, equipo abierto con un editor de código desenfocado, taza de cerámica, veta visible de roble, objetivo de 35 mm, luz suave de ventana, grano de película Kodak Portra 400.» Cambia el objetivo, la luz y el ángulo, y cada variación se convierte en una imagen de cabecera nueva. Explora el catálogo completo en picassoia.com/en/all-models y crea tu primera imagen hoy.