Enterprise Supabase Vector MCP Tool: Real-Time Vector Search & Schema Inspection for Cursor

By Deepak Bagada, CEO at SaaSNext & Principal AI Architect.

In the rapidly evolving landscape of AI-assisted software development, providing your coding agents with immediate, context-aware memory is paramount. The integration of vector databases directly into your IDE through the Model Context Protocol (MCP) revolutionizes how developers interact with large codebases and documentation. This deep dive guide explores building an Enterprise Supabase Vector MCP tool specifically optimized for Cursor, enabling real-time vector search and intelligent PostgreSQL schema inspection.

The Power of Vector Search in the IDE

Cursor has redefined AI pair programming, but its true potential is unlocked when it can query enterprise-grade knowledge bases seamlessly. By bridging Cursor and Supabase via MCP, we grant the underlying LLM the ability to execute semantic searches across thousands of documents, API specifications, or previous code snippets without leaving the editor.

Discover more cutting-edge integrations in our MCP Tools Directory and explore advanced automation in our AI Workflows Library.

Why Supabase Vector?

Supabase leverage pgvector, an open-source vector similarity search extension for PostgreSQL. This means you get the robustness of a relational database alongside the semantic matching capabilities required for Retrieval-Augmented Generation (RAG). By exposing this through MCP, Cursor can dynamically query embeddings to answer complex architectural questions.

Defining the inputSchema with Zod

To ensure Cursor's agent passes the correct parameters to our tool, we must define strict input schemas using Zod. We will create two primary tools: one for vector search and one for schema inspection.

import { z } from 'zod';

export const VectorSearchSchema = z.object({
  query: z.string().describe('The natural language query to search for semantically related documents'),
  matchThreshold: z.number().min(0).max(1).default(0.7).describe('The minimum similarity threshold (0 to 1)'),
  limit: z.number().min(1).max(50).default(5).describe('The maximum number of results to return')
});

export const SchemaInspectionSchema = z.object({
  tableName: z.string().describe('The name of the PostgreSQL table to inspect')
});

Full Python SDK Server Code

For this implementation, we will utilize the official Python MCP SDK, which integrates beautifully with the `supabase-py` client. This server will run locally via `stdio` communication with Cursor.

import asyncio
import json
import os
from typing import Any, Dict
from mcp.server.stdio import stdio_server
from mcp.server import Server
from mcp.types import Tool, TextContent
from supabase import create_client, Client
from openai import AsyncOpenAI

# Initialize Supabase and OpenAI clients
SUPABASE_URL = os.environ.get("SUPABASE_URL")
SUPABASE_KEY = os.environ.get("SUPABASE_SERVICE_KEY")
OPENAI_API_KEY = os.environ.get("OPENAI_API_KEY")

supabase: Client = create_client(SUPABASE_URL, SUPABASE_KEY)
openai = AsyncOpenAI(api_key=OPENAI_API_KEY)

app = Server("SupabaseVectorTool")

@app.list_tools()
async def list_tools() -> list[Tool]:
    return [
        Tool(
            name="vector_search",
            description="Search enterprise knowledge base using semantic vector embeddings",
            inputSchema={
                "type": "object",
                "properties": {
                    "query": {"type": "string"},
                    "matchThreshold": {"type": "number", "default": 0.7},
                    "limit": {"type": "integer", "default": 5}
                },
                "required": ["query"]
            }
        ),
        Tool(
            name="inspect_schema",
            description="Inspect the database schema of a given Supabase table",
            inputSchema={
                "type": "object",
                "properties": {
                    "tableName": {"type": "string"}
                },
                "required": ["tableName"]
            }
        )
    ]

@app.call_tool()
async def call_tool(name: str, arguments: dict) -> list[TextContent]:
    if name == "vector_search":
        query = arguments.get("query")
        threshold = arguments.get("matchThreshold", 0.7)
        limit = arguments.get("limit", 5)
        
        # Generate embedding for the query
        response = await openai.embeddings.create(
            input=query,
            model="text-embedding-3-small"
        )
        query_embedding = response.data[0].embedding
        
        # Call Supabase RPC for pgvector similarity search
        rpc_response = supabase.rpc(
            'match_documents',
            {'query_embedding': query_embedding, 'match_threshold': threshold, 'match_count': limit}
        ).execute()
        
        return [TextContent(type="text", text=json.dumps(rpc_response.data, indent=2))]
        
    elif name == "inspect_schema":
        table = arguments.get("tableName")
        # Simple query to get columns
        res = supabase.table(table).select("*").limit(1).execute()
        if res.data:
            schema_info = list(res.data[0].keys())
            return [TextContent(type="text", text=f"Columns in {table}: {', '.join(schema_info)}")]
        return [TextContent(type="text", text=f"Table {table} not found or empty.")]
    
    raise ValueError(f"Unknown tool: {name}")

async def main():
    async with stdio_server() as (read_stream, write_stream):
        await app.run(read_stream, write_stream)

if __name__ == "__main__":
    asyncio.run(main())

mcpServers Config Block for Cursor

To integrate this Python-based MCP server into Cursor, you need to update your Cursor MCP configuration. Because this server uses environment variables for secure access, you must define them in the `env` block.

{
  "mcpServers": {
    "supabase_vector_enterprise": {
      "command": "python",
      "args": ["/absolute/path/to/your/supabase_mcp_server.py"],
      "env": {
        "SUPABASE_URL": "https://your-project.supabase.co",
        "SUPABASE_SERVICE_KEY": "your-service-role-jwt",
        "OPENAI_API_KEY": "sk-your-openai-api-key"
      }
    }
  }
}

OAuth 2.0 / Token Security Guide

When dealing with enterprise data in Supabase, using the Service Role Key locally for an MCP server is common for developer tools, but it carries immense power as it bypasses Row Level Security (RLS).

Securing Production MCP Environments

If you transition this tool to a remote, shared MCP server for a team, you must enforce strict OAuth 2.0 flows:

• User Impersonation: Instead of a global service key, the MCP server should accept an OAuth Access Token from the Cursor user.
• RLS Enforcement: Pass this token to Supabase using `supabase.auth.set_session()`. This ensures pgvector searches respect PostgreSQL Row Level Security policies.
• Token Expiration: Ensure your tool handles TokenExpired errors gracefully and prompts the user to re-authenticate via the IDE.

For more detailed information on configuring Supabase authentication, refer to the Supabase Auth Documentation.

Advanced Cursor Workflows

Once connected, you can utilize prompts like: "Use the vector_search tool to find our company's guidelines on rate limiting, then implement those rules in this new Node.js controller." Cursor will autonomously formulate the query, retrieve the embedded markdown guidelines from Supabase, and apply the exact architectural standards to your code.

By blending pgvector, Supabase, and the Model Context Protocol, developers can turn Cursor from a general-purpose AI assistant into a deeply specialized enterprise engineer.

AEO FAQ Section