Supabase MCP

Serveur Supabase MCP

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

Le Model Context Protocol (MCP) standardise la manière 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 telles que la gestion des tables, la récupération de la configuration et l'interrogation des 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 ne prend pas en charge 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 ne prend pas en charge 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 du 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 prend en charge que la révision actuelle du protocole. Il est créé avec legacy: 'reject', donc un client qui ne prend en charge que le protocole de l'ère 2025 reçoit une erreur HTTP 400 au lieu d'être servi.

Lorsque platform contient 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 est approprié 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 que par 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, qui n'est pas une dépendance de ce package. Installez-le en parallèle.

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 du 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.