Supabase MCP

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

Servidor Supabase MCP

Conecta tus proyectos de Supabase a Cursor, Claude, Windsurf y otros asistentes de IA.

El Protocolo de Contexto de Modelos (MCP) estandariza cómo los Modelos de Lenguaje de Gran Escala (LLMs) se comunican con servicios externos como Supabase. Conecta asistentes de IA directamente con tu proyecto de Supabase y les permite realizar tareas como gestionar tablas, obtener configuración y consultar datos. Consulta la lista completa de herramientas.

Configuración

1. Sigue nuestras mejores prácticas de seguridad

Antes de configurar el servidor MCP, te recomendamos leer nuestras mejores prácticas de seguridad para comprender los riesgos de conectar un LLM a tus proyectos de Supabase y cómo mitigarlos.

2. Configura tu cliente MCP

Para configurar el servidor Supabase MCP en tu cliente, visita nuestra documentación de configuración. También puedes generar una URL MCP personalizada para tu proyecto visitando la pestaña de conexión MCP en el panel de Supabase.

Tu cliente MCP te pedirá automáticamente que inicies sesión en Supabase durante la configuración. Asegúrate de elegir la organización que contiene el proyecto con el que deseas trabajar.

La mayoría de los clientes MCP requieren la siguiente información:

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

Si no ves tu cliente MCP listado en nuestra documentación, consulta la documentación MCP de tu cliente y copia la información MCP anterior en su formato esperado (json, yaml, etc.).

CLI

Si estás ejecutando Supabase localmente con Supabase CLI, puedes acceder al servidor MCP en http://localhost:54321/mcp. Actualmente, el servidor MCP en entornos CLI ofrece un subconjunto limitado de herramientas y no incluye OAuth 2.1.

Autoalojado

Para Supabase autoalojado, consulta la página Habilitar servidor MCP. Actualmente, el servidor MCP en entornos autoalojados ofrece un subconjunto limitado de herramientas y no incluye OAuth 2.1.

Opciones de configuración y herramientas

Consulta la documentación del Servidor Supabase MCP para ver la lista completa de herramientas disponibles y opciones de configuración.

La documentación también incluye un constructor de URL interactivo para completar las opciones de configuración por ti.

Uso con el cliente MCP del AI SDK

El paquete @supabase/mcp-server-supabase exporta createToolSchemas() para completar los esquemas de entrada y salida del cliente MCP del AI SDK de Vercel. Esto permite que las herramientas de Supabase MCP se traten como herramientas estáticas con validación en el lado del cliente y tipos TypeScript inferidos para sus entradas y salidas.

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() acepta opciones de filtrado similares a los parámetros de URL del servidor MCP:

• features: Restringe a grupos de funciones específicos (por ejemplo, ['database', 'docs']). El valor predeterminado son todos los grupos de funciones predeterminados.
• projectScoped: Cuando es true, omite project_id de los esquemas de entrada de las herramientas y excluye las herramientas a nivel de cuenta; úsalo al conectarte a un servidor configurado con project_ref. El valor predeterminado es false.
• readOnly: Cuando es true, excluye las herramientas de mutación; úsalo al conectarte a un servidor configurado con read_only=true. El valor predeterminado es 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,
  }),
});

[!NOTA] Este servidor no envía structuredContent en los resultados de las herramientas MCP. El AI SDK recurre a analizar JSON desde el texto de content.

Para más información, consulta Definición de esquemas y Salidas de herramientas tipadas en la documentación del AI SDK.

Autoalojamiento del endpoint MCP

El paquete @supabase/mcp-server-supabase exporta createSupabaseMcpHandler() para servir las herramientas a través de HTTP desde tu propio endpoint. Acepta las mismas SupabaseMcpServerOptions que createSupabaseMcpServer(), siendo lo más importante platform.

El manejador solo habla la revisión actual del protocolo. Se crea con legacy: 'reject', por lo que un cliente que solo hable el protocolo de la era 2025 recibe un HTTP 400 en lugar de ser atendido.

Cuando platform lleva una credencial por solicitud, crea el manejador por solicitud y ciérralo cuando la respuesta termine. El manejador cierra sobre el platform que proporciones, por lo que uno compartido atiende cada solicitud con esa plataforma.

Un manejador de larga duración es adecuado cuando el platform está destinado a compartirse, por ejemplo, un token de cuenta de servicio. Créalo una vez y close() al apagar en lugar de por respuesta, ya que close() desmonta el enrutador de suscripciones y rechaza solicitudes posteriores.

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 proviene de @modelcontextprotocol/node. Tu código lo importa directamente, así que instálalo junto.

Observabilidad

Pasa un observer a createSupabaseMcpServer para recopilar los resultados del ciclo de vida de las solicitudes y los hechos integrados de Supabase. Aquí, platform es tu adaptador de plataforma existente:

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

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

El servidor no reenvía automáticamente las cargas útiles de solicitudes o respuestas al observador. Los hechos integrados de Supabase usan un conjunto cerrado de campos y valores acotados; los hechos personalizados no reciben validación automática de privacidad. Omitir observer omite todo el trabajo de observación. Los fallos del observador, clasificador y sumidero no cambian el comportamiento de las solicitudes, pero el trabajo síncrono del observador y clasificador puede bloquear las solicitudes.

Otros servidores MCP

@supabase/mcp-server-postgrest

El servidor MCP de PostgREST te permite conectar a tus propios usuarios a tu aplicación a través de la API REST. Consulta más detalles en su README del proyecto.

Recursos

• Protocolo de Contexto de Modelos: Aprende más sobre MCP y sus capacidades.
• Del desarrollo a la producción: Aprende cómo promover cambios de forma segura a entornos de producción.

Para desarrolladores

Consulta CONTRIBUTING para obtener detalles sobre cómo contribuir a este proyecto.

Licencia

Este proyecto está licenciado bajo Apache 2.0. Consulta el archivo LICENSE para más detalles.