Exposer Supabase à ton agent via MCP

Le protocole MCP (Model Context Protocol) permet à Claude Code de se connecter à des outils externes et de les utiliser directement dans tes conversations. Supabase fournit un serveur MCP officiel qui expose ta base de données, tes fonctions Edge, ton auth et bien d'autres ressources à ton agent. Cette leçon te guide de la génération du token jusqu'au premier test dans le terminal.

Générer un personal access token

Le serveur MCP Supabase s'authentifie avec un personal access token lié à ton compte Supabase, pas à un projet en particulier. Un seul token suffit pour accéder à tous tes projets.

1. Ouvre le dashboard Supabase, clique sur ton avatar en bas à gauche, puis Account > Access Tokens.
2. Clique sur Generate new token.
3. Donne-lui un nom explicite, par exemple claude-code-mcp.
4. Copie le token immédiatement : il ne sera plus affiché après la fermeture de la fenêtre.

Ajouter le serveur MCP à Claude Code

Le serveur MCP Supabase fonctionne en mode HTTP : il tourne sur les serveurs de Supabase à l'adresse https://mcp.supabase.com/mcp. Tu n'as rien à installer localement. Tu indiques simplement à Claude Code où il se trouve et comment s'y authentifier.

Via la commande CLI (recommandé)

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

Remplace TON_ACCESS_TOKEN par le token que tu viens de générer. La commande enregistre le serveur dans ta configuration Claude Code au scope local (par défaut, propre à ton utilisateur sur cette machine).

Via un fichier .mcp.json (pour partager la config avec ton équipe)

Si tu travailles sur un projet versionné et que tu veux que toute l'équipe bénéficie du serveur MCP, crée un fichier .mcp.json à la racine du projet :

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

La notation ${SUPABASE_ACCESS_TOKEN} est résolue automatiquement depuis les variables d'environnement de ton shell. Chaque membre de l'équipe exporte sa propre variable, le token ne transite jamais dans le dépôt.

Vérifier la connexion

Une fois le serveur ajouté, vérifie qu'il est bien reconnu par Claude Code.

$claude mcp list

Tu dois voir supabase dans la liste avec son URL. Pour aller plus loin, lance Claude Code et tape /mcp : la commande affiche le statut en temps réel de chaque serveur (connecté, en attente, ou en erreur) et le nombre d'outils disponibles.

Tester avec une première requête

Lance Claude Code dans ton terminal, puis pose une question qui nécessite d'interroger ta base Supabase.

$claude

Une fois dans l'interface chat, essaie ce prompt :

Liste les tables de mon projet Supabase et décris leur structure.

Si plusieurs projets sont associés à ton compte, Claude Code te demandera lequel utiliser. Tu peux aussi cibler un projet précis dès le départ en ajoutant ?project_ref=TON_PROJECT_REF à l'URL du serveur MCP dans ta configuration.

Ce que le serveur MCP peut faire

Le serveur expose plusieurs groupes d'outils activés par défaut :

• Database : lister les tables et extensions, lire le journal des migrations, exécuter du SQL arbitraire.
• Development : récupérer l'URL de l'API, les clés publiques, générer les types TypeScript.
• Edge Functions : lister, inspecter et déployer tes fonctions.
• Debugging : consulter les logs de services et les conseils de sécurité.
• Docs : rechercher dans la documentation Supabase directement depuis l'agent.

Le groupe Storage est désactivé par défaut. Le groupe Branching nécessite un plan payant.