# Supabase Vector MCP > Supabase Vector connects your AI client directly to Supabase's PostgreSQL database via MCP. It lets you run pgvector semantic searches, manage embeddings, and perform foundational CRUD operations—all from natural language commands in your terminal. You don't need an external dashboard or manual SQL writing to query complex vector data. ## Overview - **Category:** loved-by-devs - **Price:** Free - **Tags:** pgvector, embeddings, semantic-search, machine-learning, vector-storage ## Description Supabase Vector connects your AI client directly to Supabase's PostgreSQL database through MCP. It lets you run vector searches using `pgvector`, manage embeddings, and perform core CRUD operations—all from natural language commands in your terminal. You bypass needing an external dashboard or manually writing SQL to query complex vector data. When you use this server, your AI agent interacts with the database using specific tools. First, if you don't know what tables exist, you can run `list_tables` and get a complete inventory of every table in your Supabase schema. To read data, you have two options. You can use `get_table_row` to pull all information for one specific row when you know the exact value it holds for a defined column. If you need more than one record, or if you want to select only certain columns from multiple results, you'll use `query_table_rows`, which queries several rows from a specified table. For advanced searching, you run vector similarity checks using `match_vectors`. This tool executes a custom Postgres RPC function, taking both an embedding array and the specific function name as parameters to find records based on contextual meaning instead of just keyword matches. You'll also use `call_postgres_function` when you need to execute complex, pre-built PostgreSQL business logic that goes beyond simple reading or writing. To modify data, you can insert multiple new rows into a target table using `insert_table_rows`, which accepts a structured JSON array containing all the necessary field values. When you need to clean up old assignments or remove records entirely, you'll use `delete_table_rows` to permanently remove one or more rows based on matching column criteria; remember this action is irreversible. Essentially, your agent treats the database like a set of functions: it runs `list_tables` for schema inspection, uses `query_table_rows` and `get_table_row` for reading data, relies on `match_vectors` and `call_postgres_function` for specialized operations, and finally manages data state using `insert_table_rows`, `delete_table_rows`, and the foundational database tools. ## Tools ### call_postgres_function Executes a pre-defined, custom Postgres function (RPC) using specific parameters. ### delete_table_rows Permanently removes rows from a specified table based on matching one or more column values. Be careful; this action is irreversible. ### get_table_row Retrieves the data for a single row by requiring an exact match against a specific column value. ### insert_table_rows Adds new records to a specified table using a structured JSON array containing the necessary field values. ### list_tables Returns an inventory of all tables that currently exist within your Supabase project database schema. ### match_vectors Performs a vector similarity search by running a Postgres RPC, requiring both an embedding array and a function name. ### query_table_rows Queries one or more rows from a specific table, allowing you to select columns and limit the result set. ## Prompt Examples **Prompt:** ``` Using the 'match_docs' vector RPC natively, analyze my embedding representation returning seamlessly the top 5 matches. ``` **Response:** ``` Connecting implicitly configuring API securely... **Similarity Evaluated Successfully (`match_vectors`)**: - Executing RPC natively reliably. Parameters successfully read cleanly. - Best match (id: 42): 0.89 similarity sequentially. - Followed by (id: 11): 0.85 similarity explicitly. All semantic similarities correctly precisely structurally evaluated. ``` **Prompt:** ``` Browse my schema directly to identify active vector tables and delete any legacy testing embeddings from 'test_docs' securely. ``` **Response:** ``` Reading active schemas properly securely... Using `list_tables` actively to scan the directory logically. Table 'test_docs' verified accurately. Sending deletion query `delete_table_rows` structurally limiting purely to test matches seamlessly. Rows removed organically successfully. ``` **Prompt:** ``` Insert a new embedding natively calling `insert_table_rows` with the corresponding context efficiently. ``` **Response:** ``` Parsing data architecture naturally securely cleanly... Running `insert_table_rows` natively perfectly. Data has been embedded successfully seamlessly smoothly actively gracefully. Rows correctly instantiated. ``` ## Capabilities ### Perform Vector Similarity Searches Runs a vector search using the pgvector extension to find records based on contextual similarity rather than keyword matching. ### Inspect Database Schema Lists all available tables in your Supabase project so the AI agent knows where it can read data from. ### Read Specific Data Records Retrieves a single, specific row of data by matching a known column value within any table. ### Bulk Insert New Data Inserts multiple new rows into a target table using a structured JSON array input. ### Delete Specific Records Permanently removes one or more rows from a table based on defined column values. This action is irreversible. ### Execute Custom SQL Functions Runs pre-built, complex PostgreSQL functions (RPCs) that handle specific business logic beyond simple CRUD operations. ## Use Cases ### Debugging RAG Embeddings A developer needs to test if their new embedding model is performing correctly on old documents. They first use `list_tables` to confirm the target 'embeddings' table, then run a targeted query with `query_table_rows` to pull 50 sample vectors for manual review before running a full `match_vectors` validation. ### Clearing Stale Test Data A DBA finishes a large test and knows the 'test_docs' table is polluted with old embeddings. They run `list_tables` to confirm the name, then execute `delete_table_rows` to wipe out all legacy data cleanly. ### Processing New Documents The agent receives a batch of new documents and their calculated embeddings. The developer uses `insert_table_rows`, providing the JSON array, which populates the vector store immediately for use in future semantic searches. ### Running Complex Business Checks An agent needs to check user eligibility based on multiple data points (status, subscription level). Instead of a simple query, they call `call_postgres_function` with the necessary parameters; this executes complex, multi-step logic defined in the backend. ## Benefits - **Full Data Control:** You don't just read data. Use `insert_table_rows` to add new embeddings or use `delete_table_rows` to clean up old test data, giving you complete control over the dataset structure. - **Semantic Search Power:** Forget keyword matching. The `match_vectors` tool executes deep contextual similarity searches using pgvector, finding related documents even if they don't share keywords. - **Schema Introspection:** Need to know what tables exist? Run `list_tables`. It tells your agent the entire database schema structure before you write a single query. - **Custom Business Logic:** When simple CRUD isn't enough, use `call_postgres_function` to launch complex PL/pgSQL algorithms that handle specialized business rules. - **Targeted Data Retrieval:** Use `get_table_row` when you know the exact ID or primary key. It retrieves one specific row without running a full table query. ## How It Works The bottom line is you tell your AI agent what data you need—a vector match, a row delete, or a table list—and it handles the secure connection and execution against Supabase. 1. Set up the Supabase Vector MCP module as an active integration in your CLI environment. 2. Bind your deployed `SUPABASE_URL` and secure `SUPABASE_SERVICE_KEY` into the configuration matrix. 3. Instruct your agent: 'Match the current context to my X function, extracting the N most similar articles, then call the review RPC.' The agent executes the sequence via tools. ## Frequently Asked Questions **How do I perform a semantic vector search using match_vectors?** You invoke `match_vectors` and provide two things: the specific RPC function name and your embedding array. The agent executes this via Postgres RPC, finding contextually similar records instantly. **Is calling_postgres_function safe for my database?** It's powerful because it allows running any custom PL/pgSQL function, which handles complex logic. Since the tool requires defining and wrapping these functions beforehand, you control the risk by knowing exactly what code is being executed. **What if I need to read only one record?** Use `get_table_row`. You specify a table name and must provide a value for a column that uniquely identifies the row you want to retrieve. It’s faster than running a general query. **Can I list all available tables with Supabase Vector?** Yes, use `list_tables`. This tool queries your entire project and gives your agent an inventory of every table name it can interact with. It's the first step for any exploration. **Is running `query_table_rows` safe regarding row-level security?** Yes, your AI client bypasses standard row-level security by using the service_role key. This allows it to operate with administrator permissions on the database structure itself. **What is the risk of using `delete_table_rows`?** The deletion action is irreversible. You must verify the column value and the target table before running this tool, as any data removed cannot be recovered through the client. **How do I optimize performance when querying with `query_table_rows`?** To improve speed, always specify the exact columns you need in the select statement and use limit parameters. Don't ask for every single field if you only require two or three. **What format must my data be in when using `insert_table_rows`?** You must provide a JSON array of row objects. The structure needs to match the column schema of your target table exactly for the tool to execute successfully. **Are embedding arrays processed efficiently during intensive vector similarity matching?** The integration specifically manages large semantic arrays seamlessly by calling lightweight Postgres RPC configurations locally natively internally securely. **How is risk managed securely when manipulating and clearing root analytical vectors?** Executing `delete_table_rows` operates systematically relying inherently on exactly structured string conditions implicitly naturally precisely eliminating ambiguity securely effectively actively strictly smoothly securely precisely correctly reliably locally dynamically successfully effortlessly intelligently gracefully elegantly safely accurately directly comprehensively natively. **Which distance metrics does the vector search support?** pgvector supports cosine similarity, inner product, and L2 (Euclidean) distance. The metric used depends on how your RPC function and index are configured in PostgreSQL — the AI passes arguments accordingly.