Configuration

After setting up the database, configure environment variables to connect A²D to Supabase and external services.

Overview

A²D uses environment variables for all configuration. These are stored in .env.local (gitignored) for local development and in your hosting platform for production.

Time required: ~5 minutes

Required Environment Variables

Setup Steps

Step 1: Create Environment File

Copy the example environment file:

cp .env.example .env.local

Step 2: Get Supabase Credentials

1. Go to your Supabase project dashboard
2. Navigate to Settings → API
3. Copy the following values

Project URL

Located at the top of the API settings page:

https://your-project-ref.supabase.co

API Keys

Under “Project API keys” section:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6...
# ~300 characters
# Safe to expose in browser

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6...
# ~300 characters
# NEVER expose in browser!

Step 3: Edit .env.local

Open .env.local in your code editor and paste your values:

# .env.local - Supabase Configuration
NEXT_PUBLIC_SUPABASE_URL=https://your-project-ref.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
SUPABASE_SERVICE_ROLE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

# Application Configuration
NEXT_PUBLIC_APP_URL=http://localhost:3000

Replace the placeholder values with your actual Supabase credentials.

Environment Variable Details

NEXT_PUBLIC_SUPABASE_URL

Purpose: Supabase project endpoint for database connections

Format: https://[project-ref].supabase.co

Exposure: Public (prefixed with NEXT_PUBLIC_ = accessible in browser)

Example: https://abcdefghijklmnop.supabase.co

NEXT_PUBLIC_SUPABASE_ANON_KEY

Purpose: Public API key for client-side Supabase queries

Security: Safe to expose in browser - RLS policies still enforce data isolation

Format: Long JWT token starting with eyJ

Length: ~300+ characters

How it works:

• Allows anonymous database access
• Combined with user JWT for authenticated requests
• RLS policies filter data automatically
• Cannot bypass multi-tenant isolation

SUPABASE_SERVICE_ROLE_KEY

Purpose: Admin key for server-side operations that bypass RLS

Security: CRITICAL - Full database access, never expose

Powers:

• Bypasses all Row Level Security policies
• Can read/write any data across all organizations
• Used for user signup and admin operations

Usage in A²D:

• User signup (before JWT exists)
• Public MCP endpoints (server-specific access)
• Admin operations with manual filtering

Format: Long JWT token starting with eyJ

NEXT_PUBLIC_APP_URL

Purpose: Application base URL for redirects, callbacks, and MCP endpoint generation

Local development: http://localhost:3000

Production: Your deployed domain (e.g., https://ma2d.yourdomain.com)

Used for:

• Authentication redirects
• MCP endpoint URL generation
• Email template links
• OAuth callbacks

Verify Configuration

Test that environment variables are loaded correctly:

Start Development Server

npm run dev

Check Console Output

You should NOT see errors like:

• ❌ “Missing environment variable NEXT_PUBLIC_SUPABASE_URL”
• ❌ “Supabase client initialization failed”

You should see:

• ✅ ”✓ Ready in Xs”
• ✅ ”○ Compiling /“

Open Application

Navigate to http://localhost:3000

The landing page should load without errors.

Test Signup Flow

1. Click “Sign Up” button
2. Fill in:
   • Email: test@example.com
   • Password: SecurePassword123!
   • Organization Name: Test Organization
3. Click “Create Account”

Expected result: ✅ User account created, redirected to dashboard

If it fails:

• Check environment variables are correct
• Verify no extra spaces or line breaks in keys
• Restart dev server: Stop (Ctrl+C) and run npm run dev again

Production Configuration

For production deployment (Vercel, Netlify, etc.), configure environment variables in your hosting platform.

Vercel

1. Go to vercel.com/dashboard
2. Select your project
3. Navigate to Settings → Environment Variables
4. Add each variable:

Name: NEXT_PUBLIC_SUPABASE_URL
Value: https://your-prod-project.supabase.co
Environments: ✓ Production ✓ Preview ✓ Development

Name: NEXT_PUBLIC_SUPABASE_ANON_KEY
Value: eyJhbGciOi... (your production anon key)
Environments: ✓ Production ✓ Preview ✓ Development

Name: SUPABASE_SERVICE_ROLE_KEY
Value: eyJhbGciOi... (your production service role key)
Environments: ✓ Production ✓ Preview ✓ Development

Name: NEXT_PUBLIC_APP_URL
Value: https://your-app.vercel.app
Environments: ✓ Production

5. Click “Save” for each variable
6. Redeploy if already deployed

Other Hosting Platforms

Configure environment variables according to your platform:

# Site settings → Build & deploy → Environment
# Add each variable in the web UI

# Project → Variables tab
# Add each variable

# Set via CLI
fly secrets set NEXT_PUBLIC_SUPABASE_URL=https://...
fly secrets set NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ...
fly secrets set SUPABASE_SERVICE_ROLE_KEY=eyJ...
fly secrets set NEXT_PUBLIC_APP_URL=https://...

# App settings → Environment variables
# Add each variable

Security Best Practices

DO ✅

• Store .env.local locally (never commit)
• Use different credentials for development and production
• Rotate service_role key if compromised
• Use environment-specific projects (dev, staging, prod Supabase projects)
• Verify .gitignore includes .env.local and .env
• Use password manager to store credentials securely

DON’T ❌

• Don’t commit .env.local or .env files to git
• Don’t share service_role key via email/chat/Slack
• Don’t use production credentials in development
• Don’t expose service_role key in client-side code
• Don’t hardcode credentials in source code
• Don’t screenshot keys and share publicly

Multiple Environments

For complex setups, use different environment files:

.env.local          # Local development (gitignored)
.env.development    # Development server (gitignored)
.env.staging        # Staging environment (gitignored)
.env.production     # Production (gitignored, set in hosting platform)

Best practice: Use separate Supabase projects for each environment:

• ma2d-dev - Development
• ma2d-staging - Staging
• ma2d-production - Production

Optional Environment Variables

For Enhanced Development

# .env.local - Development optimizations
NODE_ENV=development

# Disable telemetry
NEXT_TELEMETRY_DISABLED=1

# Custom port
PORT=3001

For Production Monitoring

# Production only
# Error tracking (optional)
SENTRY_DSN=https://...

# Analytics (optional)
NEXT_PUBLIC_GA_ID=G-XXXXXXXXXX

Troubleshooting

”Invalid API key” error

Cause: Wrong API key format, expired key, or using wrong key type

Solution:

1. Copy keys again from Supabase dashboard (Settings → API)
2. Ensure no extra spaces or line breaks when pasting
3. Verify you’re using:
   • anon key for NEXT_PUBLIC_SUPABASE_ANON_KEY
   • service_role key for SUPABASE_SERVICE_ROLE_KEY
4. Check keys start with eyJ (JWT format)

“Failed to create organization” during signup

Cause: Service role key missing, incorrect, or not loaded

Solution:

1. Verify SUPABASE_SERVICE_ROLE_KEY is set in .env.local
2. Check it’s the service_role key (not anon key)
3. Restart dev server after adding:

   # Stop server (Ctrl+C)
   npm run dev
4. Clear browser cache and try again

Changes to .env.local not taking effect

Cause: Next.js doesn’t hot-reload environment variables

Solution:

1. Stop dev server (Ctrl+C)
2. Restart: npm run dev
3. Hard refresh browser:
   • Mac: Cmd+Shift+R
   • Windows/Linux: Ctrl+Shift+R

”Connection refused” or “Network error”

Cause: Incorrect Supabase URL or project is paused

Solution:

1. Verify URL format: https://[ref].supabase.co (no trailing slash)
2. Check project is not paused:
   • Free tier projects auto-pause after 7 days of inactivity
   • Go to Supabase dashboard → Unpause project
3. Test URL in browser - should show Supabase page

Environment variable not defined in browser

Cause: Missing NEXT_PUBLIC_ prefix

Solution:

• Variables needed in browser must have NEXT_PUBLIC_ prefix
• Server-only variables (like SUPABASE_SERVICE_ROLE_KEY) should not have the prefix
• Restart dev server after changing

Example:

# ✅ Available in browser
NEXT_PUBLIC_API_URL=https://api.example.com

# ❌ Only available on server
SUPABASE_SERVICE_ROLE_KEY=secret-key

Configuration Checklist

Before proceeding, verify:

• .env.local file created
• NEXT_PUBLIC_SUPABASE_URL set correctly
• NEXT_PUBLIC_SUPABASE_ANON_KEY set correctly
• SUPABASE_SERVICE_ROLE_KEY set correctly (server-side only)
• NEXT_PUBLIC_APP_URL set correctly
• Development server starts without errors
• Can access http://localhost:3000
• Signup flow works
• Can log in and see dashboard

Next Steps

Configuration complete! Now you can:

1. Create Your First MCP Server - Quick start guide
2. Explore Features - Learn about all capabilities
3. Deploy to Production - Deploy to Vercel

Need Help? See Authentication Troubleshooting or check the FAQ.