1# Supabase Authentication
2 
3Setting up OAuth with Supabase's OAuth 2.1 server. Supabase hosts `/authorize`, `/token`, `/register`, and `.well-known` discovery on your Supabase project — the MCP server only verifies the resulting JWTs.
4 
5**You host the consent UI.** Supabase redirects the browser to a URL you configure, and your route uses the Supabase JS SDK to load authorization details, render sign-in + consent, and submit the decision back to Supabase. mcp-use is not involved in that step — follow Supabase's [OAuth Server — Getting Started guide](https://supabase.com/docs/guides/auth/oauth-server/getting-started).
6 
7**Learn more:** [Supabase OAuth Server — MCP Authentication](https://supabase.com/docs/guides/auth/oauth-server/mcp-authentication) · [Standalone starter template](https://github.com/mcp-use/mcp-oauth-supabase-template) · [Runnable example](https://github.com/mcp-use/mcp-use/tree/main/libraries/typescript/packages/mcp-use/examples/server/oauth/supabase)
8 
9> This targets Supabase's **OAuth 2.1 server** — a different feature from Supabase Auth's social logins. Enable it explicitly in the dashboard under **Authentication → OAuth Server**.
10 
11---
12 
13## Quick Start
14 
15```typescript
16import { MCPServer, oauthSupabaseProvider, object } from "mcp-use/server";
17 
18const server = new MCPServer({
19  name: "my-server",
20  version: "1.0.0",
21  oauth: oauthSupabaseProvider(),
22});
23 
24server.tool(
25  { name: "whoami", description: "Get authenticated user info" },
26  async (_args, ctx) =>
27    object({
28      userId: ctx.auth.user.userId,
29      email: ctx.auth.user.email,
30    })
31);
32 
33server.listen();
34```
35 
36With a `.env` file:
37 
38```bash
39MCP_USE_OAUTH_SUPABASE_PROJECT_ID=your-project-id
40MCP_USE_OAUTH_SUPABASE_PUBLISHABLE_KEY=sb_publishable_...
41```
42 
43JWT verification and `.well-known` passthrough are automatic. You still need to mount your own consent route (see [Hosting the consent UI](#hosting-the-consent-ui) below).
44 
45---
46 
47## Setup
48 
491. Create (or select) a project in the [Supabase Dashboard](https://app.supabase.com/). Copy the **Project ID** from **Project Settings → General**.
502. **Authentication → OAuth Server** — enable the OAuth 2.1 server and set the **consent screen URL** to the route your MCP server will host (e.g. `http://localhost:3000/auth/consent`). Supabase appends `?authorization_id=<uuid>` when redirecting users there.
513. **Authentication → Sign In / Providers** — enable at least one sign-in method so users can authenticate before consenting:
52   - **Anonymous sign-ins** — one-click guest sessions, ideal for demos
53   - **Email + password**, **magic links**, or **OAuth providers** (Google, GitHub, etc.) — for real apps
544. Copy the **publishable key** (`sb_publishable_...`) from **Project Settings → API Keys**. You'll use it in the consent UI and in any tool that calls Supabase REST APIs.
55 
56---
57 
58## Environment Variables
59 
60| Variable | Required | Description |
61|----------|----------|-------------|
62| `MCP_USE_OAUTH_SUPABASE_PROJECT_ID` | Yes | Your Supabase project ID |
63| `MCP_USE_OAUTH_SUPABASE_PUBLISHABLE_KEY` | Recommended | Publishable key (`sb_publishable_...`) — used by the consent UI and any tools calling Supabase REST/APIs |
64| `MCP_USE_OAUTH_SUPABASE_JWT_SECRET` | Only for legacy HS256 projects | JWT secret for HS256 verification |
65 
66> New Supabase projects issue `sb_publishable_...` keys. Legacy projects using `anon` JWT keys still work, but prefer publishable keys going forward.
67 
68### Finding Your Credentials
69 
70- **Project ID**: Project Settings → **General** → Reference ID
71- **Publishable key**: Project Settings → **API Keys**
72- **JWT Secret** (legacy HS256 only): Project Settings → **JWT Settings** (Legacy)
73 
74---
75 
76## Configuration Options
77 
78Zero-config (reads from env vars):
79 
80```typescript
81oauth: oauthSupabaseProvider()
82```
83 
84Explicit config (overrides env vars):
85 
86```typescript
87oauth: oauthSupabaseProvider({
88  projectId: "my-project-id",
89  jwtSecret: process.env.MCP_USE_OAUTH_SUPABASE_JWT_SECRET,  // legacy HS256 only
90  verifyJwt: process.env.NODE_ENV === "production",
91  scopesSupported: ["openid", "profile", "email"],
92})
93```
94 
95| Option | Type | Default | Description |
96|--------|------|---------|-------------|
97| `projectId` | `string` | env var | Supabase project ID |
98| `jwtSecret` | `string?` | env var | JWT secret for HS256 tokens (legacy projects) |
99| `verifyJwt` | `boolean?` | `true` | Set `false` to skip JWT verification (**development only**) |
100| `scopesSupported` | `string[]?` | `["openid", "profile", "email"]` | Override advertised scopes |
101 
102---
103 
104## JWT Signing: ES256 vs HS256
105 
106The provider auto-detects the algorithm from the token header.
107 
108- **ES256 (new projects)** — asymmetric signing via elliptic curve keys. The provider fetches the JWKS endpoint automatically. No `jwtSecret` needed.
109- **HS256 (legacy projects)** — symmetric signing via a shared secret. Provide `MCP_USE_OAUTH_SUPABASE_JWT_SECRET` or `jwtSecret` in config.
110 
111---
112 
113## Hosting the consent UI
114 
115Supabase redirects the browser to the consent screen URL you configured. Your route must:
116 
1171. Sign the user in if they aren't already (anonymous, magic link, OAuth, etc. — whatever you enabled)
1182. Use the Supabase JS SDK to load the authorization details for `authorization_id`
1193. Render approve/deny UI
1204. Submit the decision back to Supabase and redirect to the resulting URL
121 
122Follow Supabase's [OAuth Server — Getting Started guide](https://supabase.com/docs/guides/auth/oauth-server/getting-started) for the canonical implementation. See the [runnable example](https://github.com/mcp-use/mcp-use/tree/main/libraries/typescript/packages/mcp-use/examples/server/oauth/supabase) for a wired-up version (look at `auth-routes.ts`).
123 
124---
125 
126## User Context
127 
128Supabase populates these fields on `ctx.auth.user`:
129 
130| Field | Type | Source |
131|-------|------|--------|
132| `userId` | `string` | `sub` or `user_id` claim |
133| `email` | `string?` | `email` claim |
134| `name` | `string?` | `user_metadata.name` or `user_metadata.full_name` |
135| `username` | `string?` | `user_metadata.username` |
136| `picture` | `string?` | `user_metadata.avatar_url` |
137| `roles` | `string[]?` | `role` claim (e.g. `["authenticated"]`) |
138| `permissions` | `string[]?` | Derived from AAL (e.g. `["aal:aal1"]`) |
139| `aal` | `string?` | Authentication Assurance Level |
140| `amr` | `array?` | Authentication Methods References |
141| `session_id` | `string?` | Supabase session ID |
142 
143---
144 
145## Making Supabase API Calls
146 
147Create a Supabase client scoped to the request using the user's access token so Row Level Security (RLS) policies see the caller as the authenticated user:
148 
149```typescript
150import { createClient } from "@supabase/supabase-js";
151 
152server.tool(
153  { name: "list-notes", description: "Fetch the user's notes" },
154  async (_args, ctx) => {
155    const supabase = createClient(
156      `https://${process.env.MCP_USE_OAUTH_SUPABASE_PROJECT_ID}.supabase.co`,
157      process.env.MCP_USE_OAUTH_SUPABASE_PUBLISHABLE_KEY!,
158      {
159        auth: {
160          persistSession: false,
161          autoRefreshToken: false,
162          detectSessionInUrl: false,
163        },
164        global: {
165          headers: { Authorization: `Bearer ${ctx.auth.accessToken}` },
166        },
167      }
168    );
169 
170    const { data, error: queryError } = await supabase.from("notes").select();
171    if (queryError) return error(`Failed to fetch notes: ${queryError.message}`);
172 
173    return object({ notes: data ?? [] });
174  }
175);
176```
177 
178**Key point:** The `Authorization` header uses the user's access token (for RLS); the publishable key is passed to `createClient` for SDK/API access.
179 
180---
181 
182## Example `.env`
183 
184```bash
185# Required: Supabase project ID (Dashboard → Project Settings → General)
186MCP_USE_OAUTH_SUPABASE_PROJECT_ID=your-project-id
187 
188# Recommended: Publishable key (Dashboard → Project Settings → API Keys)
189# Used by the consent UI and by tools calling Supabase REST/APIs
190MCP_USE_OAUTH_SUPABASE_PUBLISHABLE_KEY=sb_publishable_...
191 
192# Legacy HS256 projects only (Dashboard → Project Settings → JWT Settings)
193# New projects use ES256 + JWKS — leave this unset
194# MCP_USE_OAUTH_SUPABASE_JWT_SECRET=your-jwt-secret
195```
196 
197---
198 
199## Next Steps
200 
201- **Auth overview** → [overview.md](overview.md)
202- **WorkOS setup** → [workos.md](workos.md)
203- **Auth0 setup** → [auth0.md](auth0.md)
204- **Build tools** → [../server/tools.md](../server/tools.md)
205