> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Multi-Project Setup Guide

> This guide documents how to configure Supabase MCP (Model Context Protocol) to access multiple Supabase projects (e.g., staging and production) from within Cur…

**Version:** 1.0.0\
**Date:** 2026-01-15

## Overview

This guide documents how to configure Supabase MCP (Model Context Protocol) to access multiple Supabase projects (e.g., staging and production) from within Cursor IDE.

## Project Configuration

### Current Projects

| Project    | Project Reference      | URL                                        | Environment |
| ---------- | ---------------------- | ------------------------------------------ | ----------- |
| Production | `anuwknikgsijbameytzr` | `https://anuwknikgsijbameytzr.supabase.co` | Production  |
| Staging    | `rzfzikcargkoyhgqllap` | `https://rzfzikcargkoyhgqllap.supabase.co` | Staging     |

## Configuration Options

### Option 1: Hosted HTTP MCP Endpoints (Recommended)

Configure separate HTTP MCP server entries in your Cursor settings (mirrors `.cursor/mcp.json.example`):

```json theme={null}
{
  "mcpServers": {
    "supabase": {
      "url": "https://mcp.supabase.com/mcp?project_ref=rzfzikcargkoyhgqllap&read_only=true&features=database,debugging,development,docs,functions",
      "headers": {
        "Authorization": "Bearer ${env:SUPABASE_ACCESS_TOKEN}"
      }
    },
    "supabase-prod": {
      "url": "https://mcp.supabase.com/mcp?project_ref=anuwknikgsijbameytzr&read_only=true&features=database,debugging,development,docs,functions",
      "headers": {
        "Authorization": "Bearer ${env:SUPABASE_ACCESS_TOKEN}"
      }
    }
  }
}
```

**Usage:**

* Use `supabase` tools for staging operations
* Use `supabase-prod` tools for production operations

### Option 2: Environment-Based Project Switching (Single Entry)

Configure a single MCP server and switch projects using environment variables:

```json theme={null}
{
  "mcpServers": {
    "supabase": {
      "url": "https://mcp.supabase.com/mcp?project_ref=${env:SUPABASE_PROJECT_REF}&read_only=true&features=database,debugging,development,docs,functions",
      "headers": {
        "Authorization": "Bearer ${env:SUPABASE_ACCESS_TOKEN}"
      }
    }
  }
}
```

**Usage:**

```bash theme={null}
# For staging
export SUPABASE_PROJECT_REF=rzfzikcargkoyhgqllap
# Restart Cursor

# For production
export SUPABASE_PROJECT_REF=anuwknikgsijbameytzr
# Restart Cursor
```

### Option 3: Legacy stdio MCP Server (Compatibility)

Legacy `npx @supabase/mcp-server-supabase@latest` stdio setup can still be used in environments that do not support hosted HTTP MCP. Prefer Option 1 for current Cursor repo alignment.

### Option 4: OAuth Client Per Environment (Enterprise)

For enhanced security in production environments, register separate OAuth clients for each environment:

1. **Create OAuth Clients** in Supabase Dashboard:
   * Go to Settings → API → OAuth Clients
   * Create `mcp-staging` client for staging project
   * Create `mcp-production` client for production project

2. **Configure MCP with OAuth**:
   ```json theme={null}
   {
     "mcpServers": {
       "supabase": {
         "command": "npx",
         "args": [
           "-y", "@supabase/mcp-server-supabase@latest",
           "--project-ref", "rzfzikcargkoyhgqllap",
           "--oauth-client-id", "${env:MCP_STAGING_CLIENT_ID}",
           "--oauth-client-secret", "${env:MCP_STAGING_CLIENT_SECRET}"
         ]
       }
     }
   }
   ```

## Security Considerations

### Access Token Management

* **Personal Access Token**: Generated from Supabase Dashboard → Account → Access Tokens
* Store in environment variable: `SUPABASE_ACCESS_TOKEN`
* **Never** commit access tokens to version control
* Rotate tokens regularly

### Environment Isolation

| Environment | Recommended Access                            |
| ----------- | --------------------------------------------- |
| Staging     | Full MCP access (read/write)                  |
| Production  | Read-only MCP access OR separate OAuth client |

### Best Practices

1. **Use staging by default** for AI-assisted operations
2. **Require explicit confirmation** before production operations
3. **Log all MCP operations** for audit purposes
4. **Rotate access tokens** after team member departures

## Available MCP Tools

### Staging Project (`mcp_supabase_*`)

| Tool                                     | Purpose                       |
| ---------------------------------------- | ----------------------------- |
| `mcp_supabase_execute_sql`               | Execute SQL queries           |
| `mcp_supabase_apply_migration`           | Apply database migrations     |
| `mcp_supabase_list_tables`               | List database tables          |
| `mcp_supabase_list_migrations`           | List applied migrations       |
| `mcp_supabase_search_docs`               | Search Supabase documentation |
| `mcp_supabase_get_project_url`           | Get project URL               |
| `mcp_supabase_generate_typescript_types` | Generate TypeScript types     |
| `mcp_supabase_list_edge_functions`       | List Edge Functions           |
| `mcp_supabase_get_logs`                  | Get service logs              |

### Production Project (`mcp_supabase_prod_*`)

Same tools as staging, prefixed with `_prod`:

* `mcp_supabase_prod_execute_sql`
* `mcp_supabase_prod_list_tables`
* etc.

## Verification

### Check Current Connection

```sql theme={null}
-- Run via MCP to verify project
SELECT current_database(), current_user;
```

### Verify Project Isolation

```sql theme={null}
-- Check for seed data (should only exist in staging)
SELECT COUNT(*) FROM pf_organizations WHERE id::text LIKE '00000000-%';
-- Expected: 2 (staging), 0 (production)
```

## Troubleshooting

### MCP Connection Issues

1. **Verify access token** is set correctly
2. **Check project reference** matches intended environment
3. **Restart Cursor** after configuration changes
4. **Check logs** in Cursor Developer Tools

### Wrong Project Connected

If operations are being applied to the wrong project:

1. **Stop immediately** and assess damage
2. Check `mcp_settings.json` configuration
3. Verify environment variables
4. Revert any unintended changes

## Related Documentation

* [Supabase MCP Usage Guide](/development/MCP_USAGE)
* [Pre-Migration Test Plan (archived 2026-01 migration)](https://github.com/Encore-OS/encoreos/blob/development/docs/archive/migration-2026-01/PRE_MIGRATION_TEST_PLAN.md)
* [AGENTS.md](https://github.com/Encore-OS/encoreos/blob/development/AGENTS.md) - Supabase MCP Usage section

***

## Change Log

| Version | Date       | Changes                                          |
| ------- | ---------- | ------------------------------------------------ |
| 1.0.0   | 2026-01-15 | Initial version with multi-project setup options |