How to connect a Supabase MCP to Cursor (4 steps)

When you start writing something that touches the database, you need details that only show up in a real response.

What are the actual column types and constraints on a table? What do the row-level security policies on it really enforce? What fields does a Supabase Auth user object actually return?

Without the MCP connection, answering those questions means leaving the editor for the Supabase dashboard or SQL editor, running a query, and pasting the result back into the session where the integration code is being written.

To help your developers query Supabase without leaving Cursor, we'll show you how to connect Supabase with Merge Agent Handler's Supabase MCP server.

How it works

Merge Agent Handler connects Cursor to the Supabase API through the Merge CLI.

You install the CLI, authenticate once, and run a single setup command from your project root.

That command writes a ## Merge CLI section to your project's .cursorrules file, which tells Cursor's agent when to call merge search-tools and merge execute-tool to reach Supabase.

Merge will also manage your Supabase credentials, so you never store a project key locally or pass it around the team by hand.

Related: How to use the Supabase MCP in Claude Code

Prerequisites

Before getting started, you'll need the following:

• A Merge Agent Handler account
• Cursor installed
• pipx installed (run pipx --version to confirm, or install via pip install pipx)
• A Supabase account with access to the project you want to connect

If you want to connect Merge Agent Handler's Supabase MCP with internal or customer-facing agentic products, you can follow the steps in our docs.

1. Install the Merge CLI

Install the Merge CLI with pipx: pipx install merge-api

Confirm the installation succeeded: merge --version

2. Log in to Merge

Connect the CLI to your Merge Agent Handler account: merge login

This links the CLI to your account so Merge can make authorized requests against Supabase on your behalf.

3. Connect the CLI to Cursor

Run the following from the root of the project where you want to use Merge tools:

merge setup cursor

This writes a ## Merge CLI section to .cursorrules so Cursor knows to use the CLI for third-party services. The command is idempotent, so it's safe to re-run if you need to reset.

Related: The steps for connecting a Supabase MCP with Codex

4. Authenticate Supabase

Open a Cursor chat in your project and try a prompt such as:

Fetch the schema for my orders table, including column types and constraints, plus any row-level security policies on it, so I can write the query builder against the real structure.

The first time you invoke a Supabase tool, a Magic Link will appear to complete connector authentication.

{{this-blog-only-cta}}

Supabase MCP FAQ

In case you have more questions on setting up and using the Supabase MCP in Cursor, we've addressed several more commonly-asked questions below.

What can you do once the Supabase MCP is connected to Cursor?

With Supabase connected, Cursor can:

• Inspect a table's full schema before writing an ORM model: fetch real column types, defaults, and constraints so the model or query builder you write matches the database instead of a guess

• Check RLS policies before writing access-control logic: pull the real policy definitions on a table so the authorization code you write matches what the database will actually enforce

• Inspect a real auth user object before writing auth integration code: fetch a user record to see the identities, metadata, and provider fields Supabase Auth actually returns

• Validate pagination on a real table query: run a query that returns many rows to see how range-based pagination behaves before you implement your pagination loop

• Check a storage object listing before writing upload or sync code: fetch a real bucket listing to see the path, size, and metadata fields before you write the code that processes them

• Inspect an Edge Function's invocation payload before writing error handling: pull real invocation data so the retry or logging logic you write matches the real payload shape

Why use Merge Agent Handler vs. a self-hosted Supabase MCP server?

You can run a self-hosted MCP server that connects directly to your Supabase project.

For a solo developer on a single project, that's a workable setup: grab a project key, wire up a small server, and point Cursor at it.

It gets harder once more than one person needs access, or the project holds real user data.

Self-hosting means managing that Supabase key locally, rotating it by hand, and trusting that whoever has it doesn't overreach. There's no built-in way to scope which tables or operations a given agent or teammate can reach, so a key with full project access gets shared as-is.

Merge Agent Handler centralizes Supabase authentication and adds a control layer on top.

You can scope which Supabase operations a given agent is allowed to call, so a tool built to inspect schema for code generation doesn't also get write access to production tables, and every call is logged with the timestamp, tool name, and inputs.

Why connect Supabase to Cursor?

Developers writing code against Supabase have to work from the database's real structure: actual column types and constraints, RLS policies that determine what a query can actually return, and the specific shape of the objects Supabase Auth and Storage hand back.

That structure is easy to get wrong from memory or from an outdated migration file.

With the Supabase MCP connected, Cursor can pull real Supabase data directly in the chat panel.

You can fetch a table's schema while writing the model that represents it, check an RLS policy while writing the query that depends on it, or inspect a user object while writing auth logic. The data your code depends on and the code itself live in the same session, which cuts the round-trip to the dashboard or SQL editor.

Can I use Merge Agent Handler's Supabase MCP with my employees?

Yes, Agent Handler for Employees is built to help organizations provision, secure, and govern how employees connect AI tools like Cursor to operational tools like Supabase.

Common patterns include:

• Provisioning and access control via SCIM with identity providers like Okta and Microsoft Entra ID, so IT can manage which tables and projects an employee's agent can reach by role or team

• DLP and policy enforcement on tool calls, so admins can restrict which operations an employee's AI can run against production tables before the call is made

• User-level audit logging so security and IT teams can review which Supabase resources were queried or changed, by which employee identity, and when

The result is that employees can use the Supabase MCP to write queries against real table schemas, build auth integrations grounded in actual user object structure, write access-control logic tied to real RLS policies, and more, while IT keeps centralized control over which projects each agent can reach.