Skip to main content

Setup

1. Create Supabase Project

  1. Go to Supabase Dashboard
  2. Create a new project or select existing one
  3. Note your Project ID and API URL

2. Get JWT Secret (HS256 Only)

For HS256 tokens (legacy):
  1. Go to Project SettingsAPI
  2. Copy the JWT Secret under “JWT Settings”
For ES256 tokens (new):
  • No JWT secret needed, JWKS is used automatically

3. Configure Authentication

  1. Go to AuthenticationProviders
  2. Enable desired authentication providers (Email, Google, GitHub, etc.)
  3. Configure redirect URLs

Configuration

Basic Configuration (ES256)

For new Supabase projects using ES256 tokens:
import { McpServer, supabase } from 'mcp-use/server'

const server = new McpServer({
  name: 'my-server',
  version: '1.0.0',
  oauth: supabase({
    projectId: process.env.MCP_USE_OAUTH_SUPABASE_PROJECT_ID!,
    // ES256 tokens use JWKS automatically
  })
})

server.listen(3000)

Configuration with HS256 (Legacy)

For projects still using HS256 tokens:
const server = new McpServer({
  oauth: supabase({
    projectId: process.env.MCP_USE_OAUTH_SUPABASE_PROJECT_ID!,
    jwtSecret: process.env.MCP_USE_OAUTH_SUPABASE_JWT_SECRET!
  })
})

Environment Variables

# .env
MCP_USE_OAUTH_SUPABASE_PROJECT_ID=your-project-id
SUPABASE_URL=https://your-project-id.supabase.co
SUPABASE_ANON_KEY=eyJhbGci...
MCP_USE_OAUTH_SUPABASE_JWT_SECRET=your-jwt-secret  # Only for HS256

Full Configuration Options

const server = new McpServer({
  oauth: supabase({
    // Required
    projectId: 'your-project-id',
    
    // Required for HS256 tokens (legacy)
    jwtSecret: process.env.MCP_USE_OAUTH_SUPABASE_JWT_SECRET,
    
    // Optional: Supabase URL (defaults to supabase.co)
    supabaseUrl: 'https://your-project-id.supabase.co',
    
    // OAuth mode: 'proxy' (default) or 'direct'
    mode: 'proxy',
    
    // JWT verification
    verifyJwt: process.env.NODE_ENV === 'production',
    
    // Custom user info extraction
    getUserInfo: (payload) => ({
      userId: payload.sub,
      email: payload.email,
      name: payload.user_metadata?.name,
      roles: payload.app_metadata?.roles || [],
      permissions: payload.app_metadata?.permissions || [],
    })
  })
})

Token Types

New Supabase projects use ES256 tokens with JWKS:
const server = new McpServer({
  oauth: supabase({
    projectId: process.env.MCP_USE_OAUTH_SUPABASE_PROJECT_ID!
    // No jwtSecret needed - uses JWKS automatically
  })
})
Benefits:
  • More secure (asymmetric encryption)
  • No shared secret to manage
  • Automatic key rotation support

HS256 (Legacy)

Older projects may still use HS256:
const server = new McpServer({
  oauth: supabase({
    projectId: process.env.MCP_USE_OAUTH_SUPABASE_PROJECT_ID!,
    jwtSecret: process.env.MCP_USE_OAUTH_SUPABASE_JWT_SECRET!
  })
})
Check your token type:
  1. Go to Supabase Dashboard → Project SettingsAPI
  2. Look for “JWT Algorithm” in JWT Settings
  3. If it says “HS256”, you need the JWT secret
  4. If it says “ES256”, omit the JWT secret

Resources

Next Steps