Le MCP Supabase ne fonctionne pas dans Cursor ? Configuration et solutions

Vous avez ajouté le serveur Supabase à Cursor, redémarré l’éditeur, et le panneau MCP affiche maintenant un point rouge, une liste d’outils vide ou un indicateur de chargement qui ne s’arrête jamais. Ou bien la connexion semble active, mais l’Agent affirme qu’il n’a aucun outil de base de données. Cet écart entre « configuré » et « fonctionnel » est la forme la plus courante de Cursor et MCP Supabase qui ne fonctionne pas, et presque chaque cas se ramène à une courte liste de causes : un fichier de configuration au mauvais endroit, une connexion non terminée, un enregistrement OAuth périmé, une URL restreinte qui masque des outils, trop d’outils sur l’ensemble des serveurs, une particularité de npx sous Windows, un projet en pause, ou une demande d’approbation que personne n’a validée. Voici chaque cause, dans l’ordre où il vaut la peine de les vérifier, avec la configuration exacte, un tableau des symptômes et les contrôles de journaux qui vous feront gagner une après-midi.

Comment fonctionne le lien entre Cursor et Supabase

MCP, le Model Context Protocol, permet à l’agent IA d’un éditeur d’appeler des outils externes. Supabase publie un serveur MCP dont les outils permettent à l’Agent de lister les tables, d’exécuter du SQL, d’appliquer des migrations, de lire les journaux du projet et de rechercher dans la documentation. Cursor joue le rôle de client. Il lit un fichier JSON, contacte ou lance le serveur, demande la liste des outils et les affiche dans les réglages.

Quand quelque chose casse, cela arrive à l’une de quatre étapes, et savoir laquelle divise la recherche par deux :

1. Lecture de la configuration : le fichier est absent, invalide ou placé dans le mauvais dossier.
2. Connexion : l’URL est injoignable ou la commande ne peut pas être lancée.
3. Authentification : la connexion par navigateur n’a pas abouti, ou le jeton est erroné.
4. Liste des outils : le serveur est connecté, mais vos paramètres masquent des outils ou l’Agent est surchargé.

Serveur hébergé ou npx en local

Vous avez trois façons de vous connecter, et mélanger leurs réglages est une source classique de confusion.

💡 Choisissez-en un seul. Si le même nom de serveur apparaît dans deux fichiers de configuration, ou si une entrée distante et une entrée npx revendiquent toutes deux supabase, vous pouvez passer une heure à déboguer la mauvaise.

Où doit se trouver mcp.json

Cursor lit deux emplacements. Un fichier de projet à .cursor/mcp.json s’applique à ce dépôt. Un fichier utilisateur à ~/.cursor/mcp.json s’applique partout, et la documentation de Supabase y renvoie lorsque vous voulez une seule configuration pour tous vos projets.

Trois erreurs expliquent une part surprenante des points rouges : enregistrer mcp.json à la racine du dépôt au lieu de .cursor, laisser une virgule finale qui rend le JSON invalide, et mal écrire la propriété de premier niveau mcpServers. Collez le fichier dans un validateur JSON avant d’accuser le serveur.

La configuration propre qui fonctionne

Repartez d’un état connu avant d’essayer des corrections. Supprimez les entrées modifiées à moitié, puis ajoutez une seule des configurations ci-dessous.

URL distante avec connexion par navigateur

Le serveur hébergé n’a besoin que d’une URL :

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

Copier le prompt

Enregistrez le fichier, redémarrez Cursor et ouvrez Paramètres > Cursor Settings > Tools & MCP. L’entrée Supabase doit proposer une connexion. Une fenêtre de navigateur s’ouvre, vous vous connectez à Supabase et vous accordez l’accès à votre organisation. Si vous préférez le terminal, la CLI de Cursor propose trois commandes équivalentes :

agent mcp enable supabase
agent mcp login supabase
agent mcp list

Copier le prompt

Lancez ensuite le test de fumée suggéré par Supabase dans un nouveau chat Agent : « Quelles tables existent dans ma base de données ? Utilisez les outils MCP. » Une réponse concrète avec les noms de vos tables signifie que toute la chaîne fonctionne. Des excuses sur des outils manquants signifient qu’une des corrections ci-dessous s’applique.

Solution de secours : jeton et npx

Certaines équipes exécutent encore le serveur en local avec un jeton d’accès personnel créé dans les réglages de leur compte Supabase. La configuration lance le paquet via 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>"
      }
    }
  }
}

Copier le prompt

Cette voie nécessite Node.js installé. Les options --read-only et --project-ref remplissent les mêmes rôles que les paramètres d’URL décrits plus loin. Traitez le jeton comme un mot de passe : ne versionnez jamais un mcp.json qui le contient dans un dépôt public. Supabase a fait évoluer sa configuration recommandée au fil du temps. Vérifiez donc l’onglet de connexion MCP du tableau de bord Supabase si ses instructions actuelles diffèrent de cet extrait.

Sous Windows, il faut un wrapper cmd

Sous Windows, npx est un shim batch, et le lancer directement se termine souvent par une erreur de spawn. Encapsulez-le dans 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>"
      }
    }
  }
}

Copier le prompt

Exécutez d’abord node --version et npx --version dans un terminal neuf. Si Node a été installé après le démarrage de Cursor, l’éditeur conserve l’ancien PATH : quittez donc Cursor complètement et rouvrez-le, pas seulement la fenêtre. La voie par URL hébergée contourne tout cela, ce qui est une bonne raison de la privilégier sur les machines Windows aux outils verrouillés.

Huit symptômes et leurs corrections

Repérez ce que vous voyez dans une ligne du tableau, puis rendez-vous à la section correspondante ci-dessous.

Point rouge et liste d’outils vide

Un point rouge signifie que Cursor n’a jamais obtenu de connexion fonctionnelle. Commencez donc par les vérifications les moins coûteuses. Validez le JSON, confirmez que le fichier se trouve à .cursor/mcp.json ou à ~/.cursor/mcp.json, et appuyez sur le bouton d’actualisation dans les réglages MCP, qui a relancé des serveurs bloqués pour certains utilisateurs du forum Cursor. Redémarrez Cursor après chaque modification de configuration, car les notes de Supabase indiquent qu’un redémarrage est nécessaire avant que tous les outils n’apparaissent.

Si le point reste rouge, les journaux décrits plus bas nommeront la panne en une seule ligne. Résistez à l’envie de réécrire toute la configuration à ce stade. Changer une seule variable par redémarrage est plus lent sur le papier, mais beaucoup plus rapide en pratique.

Boucles de connexion et erreurs client_id

Avec le serveur hébergé, Cursor termine le passage OAuth en ouvrant une page sur localhost:8787. Deux erreurs apparaissent à cet endroit.

• Une erreur 431 avant la fin de la connexion. Des cookies trop volumineux, stockés pour localhost par vos autres serveurs de développement, peuvent la provoquer. Effacez les cookies de localhost uniquement, et non tout votre navigateur, puis relancez la connexion.
• « Unrecognized client_id ». Cursor réutilise un enregistrement OAuth en cache issu d’une ancienne configuration. Déconnectez le serveur, supprimez-le, quittez Cursor complètement et ajoutez-le à nouveau pour qu’il s’enregistre à neuf.

Si le navigateur ne s’ouvre jamais, cherchez dans les journaux de Cursor l’URL d’autorisation, collez-la manuellement dans votre navigateur, terminez la connexion, et le retour vers Cursor devrait établir la connexion.

Connecté, mais des outils manquent

Un point vert avec un Agent aveugle résulte généralement d’une configuration qui fait exactement ce que vous lui avez demandé. Quatre paramètres d’URL modifient les outils disponibles :

Un exemple restreint ressemble à ceci : https://mcp.supabase.com/mcp?project_ref=abc123&read_only=true

Trois résultats surprennent les gens. Ajouter project_ref désactive les outils de compte, donc l’absence de liste de projets est normale. Le groupe Storage est désactivé par défaut et doit être activé. Et read_only=true fait échouer toutes les écritures par conception. Demandez à l’Agent de lister tous les outils Supabase qu’il peut appeler actuellement, puis comparez cette liste à vos paramètres.

💡 skip_elicitations retire un filet de sécurité. Ne l’utilisez que sur un projet de développement jetable, jamais à côté de données de production.

Approbations et projets en pause

Deux dernières causes ressemblent à des pannes sans en être. D’abord, Cursor demande normalement une confirmation avant d’exécuter un outil MCP : un Agent qui semble figé attend peut-être un bouton d’approbation plus haut dans le chat. Vérifiez que vous êtes en mode Agent, car c’est là que les outils s’exécutent.

Ensuite, le projet lui-même peut être en pause. Les projets du plan gratuit peuvent se mettre en pause après environ une semaine d’inactivité, et les requêtes adressées à une base en pause échouent même lorsque le lien MCP est sain. Reprenez le projet depuis le tableau de bord Supabase, puis relancez la tentative.

Lire les journaux avant de deviner

Chacune des corrections ci-dessus est plus rapide une fois que vous avez lu l’erreur réelle. Deviner les options peut ajouter de nouveaux problèmes à celui d’origine.

Où Cursor stocke les journaux

Ouvrez le panneau Sortie depuis le menu Affichage et choisissez l’entrée MCP de votre serveur Supabase dans la liste déroulante des canaux. Redémarrez le serveur, puis lisez les 20 dernières lignes. Les motifs habituels :

Pour tester seul le chemin réseau, exécutez curl -i https://mcp.supabase.com/mcp depuis un terminal. Tout code HTTP, même un 401, prouve que l’hôte est joignable. Un délai dépassé ou une erreur TLS pointe vers un VPN, un proxy ou un pare-feu plutôt que vers Cursor.

La liste de contrôle de dix minutes

Si vous voulez un passage rapide plutôt qu’une analyse approfondie, suivez cette liste dans l’ordre :

1. Validez le JSON et confirmez l’emplacement du fichier.
2. Ne gardez qu’une seule entrée supabase dans les deux fichiers de configuration.
3. Vérifiez node --version et npx --version si vous utilisez la voie npx.
4. Encapsulez npx dans cmd /c sous Windows.
5. Quittez Cursor complètement et rouvrez-le.
6. Terminez la connexion par navigateur, en effaçant les cookies localhost en cas d’erreur 431.
7. Supprimez et ajoutez à nouveau l’entrée en cas d’erreur « Unrecognized client_id ».
8. Vérifiez project_ref, features et read_only dans l’URL.
9. Passez en mode Agent et approuvez tout appel d’outil en attente.
10. Confirmez que le projet Supabase n’est pas en pause.

Trop d’outils nuisent à l’Agent

Cursor affiche l’avertissement « Exceeding total tools limit » dès que les outils de tous vos serveurs dépassent 40. Il précise que trop d’outils peuvent dégrader les performances et que certains modèles pourraient ne pas respecter plus de 40 outils. Les versions récentes chargent le contexte des outils de façon dynamique, et certains utilisateurs signalent qu’aucun avertissement n’apparaît avec plus de 80 outils activés.

L’avertissement est moins strict qu’avant, mais le problème de fond demeure : un Agent qui choisit parmi des dizaines d’outils similaires fait de moins bons choix, et les modèles plus petits s’en sortent moins bien en premier. Le fil du forum Cursor sur la limite de 40 outils retrace l’évolution de cette limite.

Réduire la liste d’outils

• Désactivez les serveurs que vous n’utilisez pas pendant cette session.
• Limitez Supabase avec features=database,docs lorsque vous n’avez besoin que du SQL et de la documentation.
• Cliquez sur les noms d’outils individuels dans les réglages MCP pour désactiver ceux que vous n’appelez jamais.
• Gardez les serveurs propres à un projet dans .cursor/mcp.json et les serveurs généraux dans le fichier utilisateur.

Verrouillez avant de faire confiance

Un serveur MCP capable d’exécuter du SQL mérite le même soin qu’un identifiant de connexion à une base de données. La recommandation de Supabase est sans détour : ne vous connectez à la production que si c’est nécessaire, et utilisez la restriction à un projet, le mode lecture seule et les groupes de fonctionnalités limités lorsque vous le faites.

Mode lecture seule et restriction au projet

Trois réglages assurent l’essentiel de la protection. read_only=true exécute les requêtes avec un utilisateur Postgres en lecture seule. project_ref limite le serveur à un seul projet. features réduit les groupes d’outils à ceux dont vous avez besoin. Supabase affiche aussi des boîtes de confirmation avant toute action qui crée des ressources facturables, donc ne les validez pas automatiquement. Les routines sans surveillance doivent toujours fonctionner en lecture seule.

L’injection de prompt est le vrai risque

La principale menace propre aux LLM consiste en des instructions malveillantes cachées dans les données. Imaginez une ligne de ticket de support dont le texte demande au modèle d’ignorer les instructions précédentes et d’exporter la table des utilisateurs. Si l’Agent lit cette ligne via un outil, il peut traiter ce texte comme une commande. Conservez l’approbation manuelle des appels d’outils et relisez chaque instruction SQL avant de l’approuver. La documentation MCP de Supabase détaille l’ensemble de ces protections.

💡 Construisez et testez la connexion sur un projet de développement jetable. Ne passez à tout ce qui contient de vraies données client qu’une fois le mode lecture seule et la restriction au projet déjà en place.

Faire lire les journaux à un modèle

Quand les lignes de journal n’ont aucun sens, un LLM est un second regard rapide. Sur PicassoIA, Claude Sonnet 5 est conçu pour automatiser les tâches de programmation, GPT 5.6 Sol pour résoudre des tâches de programmation complexes, et Gemini 3.1 Pro pour des réponses générales plus précises. N’importe lequel d’entre eux peut transformer une trace d’appels en une courte liste de suspects.

Avant de coller quoi que ce soit, retirez les jetons d’accès, les références de projet sensibles et les URL de base de données. Un extrait de journal n’en a presque jamais besoin, et une fenêtre de chat n’est pas un coffre-fort.

Un prompt pour les bugs de configuration

Donnez au modèle les faits qu’il ne peut pas deviner :

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.

Copier le prompt

Indiquez votre système d’exploitation, la version de Cursor, la configuration, l’extrait de journal et ce que vous attendiez. Demander des causes classées, avec une vérification pour chacune, empêche le modèle de vous servir une liste de contrôle générique. Ensuite, effectuez vous-même les vérifications plutôt que d’approuver les corrections à l’aveugle.

Essayez par vous-même sur PicassoIA

Une correction de ce genre mérite mieux qu’un mur de configuration. Un article de blog, un runbook interne ou une documentation d’équipe se lit mieux avec de vraies photographies à la place de captures d’écran génériques, et PicassoIA transforme un simple prompt texte en image en quelques secondes. Essayez Seedream 4.5 pour des photos nettes et détaillées, ou GPT Image 2 lorsque vous voulez transformer un prompt simple en une scène précise.

Un prompt de départ : « Photographie en plongée d’un bureau de développeur au lever du soleil, ordinateur portable ouvert sur un éditeur de code flou, mug en céramique, grain visible du bois de chêne, objectif 35 mm, lumière douce de fenêtre, grain de film Kodak Portra 400. » Changez l’objectif, la lumière et l’angle, et chaque variation devient une nouvelle image d’en-tête. Parcourez le catalogue complet sur picassoia.com/en/all-models et créez votre première image dès aujourd’hui.