Skip to main content

Supabase

Use Supabase with Mastra in two ways:

  • Agent tools let an agent query tables, call database functions, and manage storage and auth users in Supabase through Mastra Connect.
  • Server authentication verifies requests to your Mastra server with Supabase, using the @mastra/auth-supabase package.

Connect
Direct link to Connect

Before you start, complete the Connect setup to install @mastra/connect and configure your platform project.

Agent tools
Direct link to Agent tools

Give agents tools to query and change table rows, call database functions, and manage storage buckets, files, and auth users in Supabase.

Connect an account with the supabase provider ID. Run this command from the directory that contains your .env file:

mastra connect add supabase

Then pass tools() to the agent and select the provider:

src/mastra/agents/supabase-agent.ts
import { Agent } from '@mastra/core/agent'
import { tools } from '@mastra/connect'

export const supabaseAgent = new Agent({
id: 'supabase-agent',
name: 'Supabase agent',
instructions:
'You help people query and change table rows, call database functions, and manage storage buckets, files, and auth users in Supabase.',
model: '__GATEWAY_OPENAI_MODEL_LUNA__',
tools: tools({ providers: ['supabase'] }),
})

The agent gets 27 Supabase tools, with keys such as supabase_copy_storage_object. See Supabase tools for the full list, and the tools() parameters to restrict tools or require approval before a call runs.

Server authentication
Direct link to Server authentication

The @mastra/auth-supabase package provides authentication for Mastra using Supabase Auth. It verifies incoming requests using Supabase's authentication system and integrates with the Mastra server using the auth option.

Prerequisites
Direct link to Prerequisites

This example uses Supabase Auth. Ensure you add your Supabase credentials to your .env file and ensure your Supabase project is configured correctly.

.env
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_ANON_KEY=your-anon-key
note

Review your Supabase Row Level Security (RLS) settings to ensure proper data access controls.

Installation
Direct link to Installation

Before you can use the MastraAuthSupabase class you have to install the @mastra/auth-supabase package.

npm install @mastra/auth-supabase@latest

Usage example
Direct link to Usage example

src/mastra/index.ts
import { Mastra } from '@mastra/core'
import { MastraAuthSupabase } from '@mastra/auth-supabase'

export const mastra = new Mastra({
server: {
auth: new MastraAuthSupabase({
url: process.env.SUPABASE_URL,
anonKey: process.env.SUPABASE_ANON_KEY,
}),
},
})
note

The default authorizeUser method checks the isAdmin column in the users table in the public schema. To customize user authorization, provide a custom authorizeUser function when constructing the provider.

Visit MastraAuthSupabase for all available configuration options.

Client-side setup
Direct link to Client-side setup

When using Supabase auth, you'll need to retrieve the access token from Supabase on the client side and pass it to your Mastra requests.

Retrieving the access token
Direct link to Retrieving the access token

Use the Supabase client to authenticate users and retrieve their access token:

lib/auth.ts
import { createClient } from '@supabase/supabase-js'

const supabase = createClient('<supabase-url>', '<supabase-key>')

const authTokenResponse = await supabase.auth.signInWithPassword({
email: "<user's email>",
password: "<user's password>",
})

const accessToken = authTokenResponse.data?.session?.access_token
note

Refer to the Supabase documentation for other authentication methods like OAuth, magic links, and more.

Configuring MastraClient
Direct link to configuring-mastraclient

When auth is enabled, all requests made with MastraClient must include a valid Supabase access token in the Authorization header:

lib/mastra/mastra-client.ts
import { MastraClient } from '@mastra/client-js'

export const mastraClient = new MastraClient({
baseUrl: 'https://<mastra-api-url>',
headers: {
Authorization: `Bearer ${accessToken}`,
},
})
note

The access token must be prefixed with Bearer in the Authorization header.

Visit Mastra Client SDK for more configuration options.

Making authenticated requests
Direct link to Making authenticated requests

Once MastraClient is configured with the Supabase access token, you can send authenticated requests:

src/components/test-agent.tsx
import { mastraClient } from '../../lib/mastra-client'

export const TestAgent = () => {
async function handleClick() {
const agent = mastraClient.getAgent('weatherAgent')

const response = await agent.generate("What's the weather like in New York")

console.log(response)
}

return <button onClick={handleClick}>Test Agent</button>
}