Supabase MCP

npx add-mcp 'https://mcp.supabase.com/mcp'

Serveur Supabase MCP

Connectez vos projets Supabase à Cursor, Claude, Windsurf et d'autres assistants IA.

Le Model Context Protocol (MCP) standardise la façon dont les grands modèles de langage (LLM) communiquent avec des services externes comme Supabase. Il connecte directement les assistants IA à votre projet Supabase et leur permet d'effectuer des tâches comme la gestion de tables, la récupération de configuration et l'interrogation de données. Consultez la liste complète des outils.

Configuration

1. Suivez nos bonnes pratiques de sécurité

Avant de configurer le serveur MCP, nous vous recommandons de lire nos bonnes pratiques de sécurité pour comprendre les risques liés à la connexion d'un LLM à vos projets Supabase et comment les atténuer.

2. Configurez votre client MCP

Pour configurer le serveur Supabase MCP sur votre client, consultez notre documentation de configuration. Vous pouvez également générer une URL MCP personnalisée pour votre projet en visitant l'onglet de connexion MCP dans le tableau de bord Supabase.

Votre client MCP vous demandera automatiquement de vous connecter à Supabase lors de la configuration. Assurez-vous de choisir l'organisation qui contient le projet avec lequel vous souhaitez travailler.

La plupart des clients MCP nécessitent les informations suivantes :

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

Si votre client MCP n'apparaît pas dans notre documentation, consultez la documentation MCP de votre client et copiez les informations MCP ci-dessus dans le format attendu (json, yaml, etc.).

CLI

Si vous exécutez Supabase localement avec Supabase CLI, vous pouvez accéder au serveur MCP à l'adresse http://localhost:54321/mcp. Actuellement, le serveur MCP dans les environnements CLI offre un sous-ensemble limité d'outils et aucune authentification OAuth 2.1.

Auto-hébergé

Pour Supabase auto-hébergé, consultez la page Activation du serveur MCP. Actuellement, le serveur MCP dans les environnements auto-hébergés offre un sous-ensemble limité d'outils et aucune authentification OAuth 2.1.

Options de configuration et outils

Consultez la documentation du Serveur Supabase MCP pour la liste complète des outils disponibles et des options de configuration.

La documentation propose également un générateur d'URL interactif pour remplir les options de configuration à votre place.

Utilisation avec le client MCP de l'AI SDK

Le package @supabase/mcp-server-supabase exporte createToolSchemas() pour remplir les schémas d'entrée et de sortie du client MCP de l'AI SDK de Vercel. Cela permet de traiter les outils Supabase MCP comme des outils statiques avec validation côté client et types TypeScript déduits pour leurs entrées et sorties.

import { createToolSchemas } from '@supabase/mcp-server-supabase';
import { createMCPClient } from '@ai-sdk/mcp';
import { streamText } from 'ai';

const mcpClient = await createMCPClient({
  transport: {
    type: 'http',
    url: 'https://mcp.supabase.com/mcp',
  },
});

const tools = await mcpClient.tools({
  schemas: createToolSchemas(),
});

const result = streamText({ model, tools, prompt: '...' });

for (const step of await result.steps) {
  for (const toolResult of step.staticToolResults) {
    if (toolResult.toolName === 'get_project_url') {
      toolResult.input;  // { project_id: string }
      toolResult.output; // { url: string }
    }
  }
}

createToolSchemas() accepte des options de filtrage similaires aux paramètres d'URL du serveur MCP :

• features : Restreindre à des groupes de fonctionnalités spécifiques (par exemple ['database', 'docs']). Par défaut, tous les groupes de fonctionnalités par défaut.
• projectScoped : Lorsque true, omet project_id des schémas d'entrée des outils et exclut les outils au niveau du compte — à utiliser lors de la connexion à un serveur configuré avec project_ref. Par défaut, false.
• readOnly : Lorsque true, exclut les outils de mutation — à utiliser lors de la connexion à un serveur configuré avec read_only=true. Par défaut, false.

const mcpClient = await createMCPClient({
  transport: {
    type: 'http',
    url: 'https://mcp.supabase.com/mcp?project_ref=<project-ref>&read_only=true&features=database,docs',
  },
});

const tools = await mcpClient.tools({
  schemas: createToolSchemas({
    features: ['database', 'docs'],
    projectScoped: true,
    readOnly: true,
  }),
});

[!NOTE] Ce serveur n'envoie pas structuredContent dans les résultats des outils MCP. L'AI SDK revient à l'analyse du JSON à partir du texte content.

Pour plus d'informations, consultez Définition de schéma et Sorties d'outils typées dans la documentation de l'AI SDK.

Auto-hébergement du point de terminaison MCP

Le package @supabase/mcp-server-supabase exporte createSupabaseMcpHandler() pour servir les outils via HTTP depuis votre propre point de terminaison. Il accepte les mêmes SupabaseMcpServerOptions que createSupabaseMcpServer(), notamment platform.

Le gestionnaire ne parle que la révision actuelle du protocole. Il est créé avec legacy: 'reject', donc un client qui ne parle que le protocole de l'ère 2025 reçoit une erreur HTTP 400 au lieu d'être servi.

Lorsque platform transporte une information d'identification par requête, créez le gestionnaire par requête et fermez-le lorsque la réponse se termine. Le gestionnaire se ferme sur le platform que vous fournissez, donc un gestionnaire partagé sert chaque requête avec cette plateforme.

Un gestionnaire à longue durée de vie convient lorsque le platform est destiné à être partagé, par exemple un jeton de compte de service. Créez-le une fois et close() à l'arrêt plutôt qu'à chaque réponse, car close() démonte le routeur d'abonnement et refuse les requêtes ultérieures.

import { createServer } from 'node:http';
import { toNodeHandler } from '@modelcontextprotocol/node';
import { createSupabaseMcpHandler } from '@supabase/mcp-server-supabase';
import { createSupabaseApiPlatform } from '@supabase/mcp-server-supabase/platform/api';

const server = createServer((req, res) => {
  const accessToken = getAccessTokenFromRequest(req); // your own auth

  const handler = createSupabaseMcpHandler({
    platform: createSupabaseApiPlatform({ accessToken }),
  });

  // `close()` aborts in-flight exchanges, so close on `res` finishing rather
  // than when the handler resolves, which would cut streaming responses short.
  res.on('close', () => {
    handler.close().catch((error) => console.error(error));
  });

  toNodeHandler(handler)(req, res).catch((error) => console.error(error));
});

toNodeHandler provient de @modelcontextprotocol/node. Votre code l'importe directement, installez-le donc en parallèle.

Observabilité

Passez un observer à createSupabaseMcpServer pour collecter les résultats du cycle de vie des requêtes et les faits intégrés de Supabase. Ici, platform est votre adaptateur de plateforme existant :

import { createSupabaseMcpServer } from '@supabase/mcp-server-supabase';

const server = createSupabaseMcpServer({
  platform,
  observer: (context) => ({
    record(fact) {
      console.info(fact);
    },
    end(result) {
      console.info({ ...context, ...result });
    },
  }),
});

Le serveur ne transmet pas automatiquement les charges utiles de requête ou de réponse à l'observateur. Les faits intégrés de Supabase utilisent un ensemble fermé de champs et de valeurs bornés ; les faits personnalisés ne reçoivent aucune validation de confidentialité automatique. L'omission de observer ignore tout le travail d'observation. Les échecs d'observateur, de classificateur et de récepteur ne modifient pas le comportement des requêtes, mais le travail synchrone d'observateur et de classificateur peut bloquer les requêtes.

Autres serveurs MCP

@supabase/mcp-server-postgrest

Le serveur MCP PostgREST vous permet de connecter vos propres utilisateurs à votre application via l'API REST. Voir plus de détails dans son README de projet.

Ressources

• Model Context Protocol : En savoir plus sur MCP et ses capacités.
• Du développement à la production : Apprenez à promouvoir en toute sécurité les modifications vers les environnements de production.

Pour les développeurs

Consultez CONTRIBUTING pour plus de détails sur la façon de contribuer à ce projet.

Licence

Ce projet est sous licence Apache 2.0. Voir le fichier LICENSE pour plus de détails.