MCP Usage Guide

See: Root AGENTS.md for quick reference (current version: docs/VERSIONS.md).

​

Cursor MCP Governance (Local + Cloud)

​

Security Baseline (REQUIRED)

• Never commit plaintext secrets in MCP configs.
• Use environment interpolation for credentials (for example: ${env:STITCH_API_KEY}).
• Prefer .cursor/mcp.json.example as the shared template and keep machine/user secrets out of source control.
• Treat MCP allowlists as convenience, not a security boundary; still enforce command and data review discipline.

​

Two Config Files Explained

• .cursor/mcp.json.example — Cursor IDE team template. Developers copy/merge this into local .cursor/mcp.json.
• .mcp.json — Claude Code MCP configuration for this repo.

​

Approved Repo MCP Servers

​

Cloud Compatibility Notes

• Cloud agents run in isolated Linux environments; avoid shell-specific assumptions in MCP setup scripts.
• HTTP and stdio MCP servers are preferred for cloud portability.
• Keep required env vars documented alongside cloud setup docs so cloud runs are reproducible.
• encore-api-surface is local-only when configured as http://localhost:3399/mcp; Cursor Cloud agents cannot reach a developer laptop localhost endpoint.

​

Encore API Surface MCP (encore-api-surface)

Purpose: Enable fast symbol/spec lookups from docs/api/index.json in local Cursor sessions via the custom MCP server.

​

Team Setup Workflow

1. Confirm index is available: docs/api/index.json is committed; regenerate only if stale or missing:
   npm run docs:api:generate
   
2. Start the local MCP server in a dedicated terminal:
   npm run mcp:serve
   
   Optional port override:
   MCP_PORT=3399 npm run mcp:serve
   
3. Configure Cursor MCP: copy .cursor/mcp.json.example to .cursor/mcp.json (or merge the new block into your existing local file).
4. Reload Cursor MCP: restart Cursor or use Cursor Settings -> MCP.
5. Verify tools are visible and callable:
   • lookup_symbol({ name, limit? })
   • symbols_for_spec({ spec_id })
   • semantic_search({ query, top_k? }) (optional)

​

Semantic Search Prerequisites (Optional)

• AI_GATEWAY_API_KEY
• BLOB_READ_WRITE_TOKEN
• npm run docs:api:embeddings

​

Limitations and Notes

• Local-only for Cursor IDE: this server URL points to localhost.
• Cursor Cloud should use committed API-surface artifacts (docs/api/index.json, docs/api/{core}.md) instead of this local MCP endpoint.
• v1 is trusted local use only (no auth layer).
• The server hot-reloads when docs/api/index.json changes.

​

Troubleshooting

​

Supabase MCP Usage (REQUIRED)

Purpose: AI agents MUST use Supabase MCP for read operations and documentation lookup. Use Supabase CLI for write operations (migrations, deployments).

​

When to Use Supabase MCP

• ✅ Reading project information (project URL, branch list, project details)
• ✅ Searching Supabase documentation (RLS policies, branching, migrations)
• ✅ Querying branch information (list branches, get branch details)
• ✅ Looking up API patterns (best practices, examples)
• ✅ Understanding Supabase features (branching, migrations, RLS)

• ❌ Creating migrations (use CLI: npx supabase migration new or supabase migration new)
• ❌ Deploying migrations (use CLI: npx supabase db push or supabase db push)
• ❌ Generating types (use CLI: npx supabase gen types typescript or supabase gen types typescript)
• ❌ Local development (use CLI: npx supabase start or supabase start)

​

When to Use Supabase CLI

• ✅ Creating migration files (npx supabase migration new or supabase migration new)
• ✅ Applying migrations (npx supabase db push, supabase migration up)
• ✅ Local development (npx supabase start, npx supabase db reset, or supabase start / supabase db reset if on PATH)
• ✅ Generating TypeScript types (npx supabase gen types typescript or supabase gen types typescript)
• ✅ Linking projects (npx supabase link --project-ref or supabase link)
• ✅ Managing branches (npx supabase --experimental branches create or supabase branches create)

​

Testing migrations locally (before committing)

1. Start local stack (if not running): npx supabase start (or supabase start if CLI on PATH)
2. Apply all migrations to local DB: npx supabase db reset (or supabase db reset if on PATH; or supabase migration up for pending only)
3. Run project validation: validate-migration --latest (or npx tsx scripts/database/validate-migration.ts --latest)
4. Run RLS tests as needed: npm run test:rls (or Cursor command test-rls)
5. Then commit and push. Use npx supabase db push (or supabase db push) only when targeting a linked remote (staging/production).

​

Supabase MCP / CLI Operation Matrix

​

Supabase MCP Read Operations

• Listing projects/branches and checking branch state
• Listing tables, migrations, extensions, advisors, and logs
• Retrieving edge function metadata/code for review
• Searching docs for RLS, branching, migration, and API patterns

​

Common Supabase Workflow

1. Use MCP to discover current state and docs patterns.
2. Use CLI to create/apply migrations and deploy execution changes.
3. Use MCP again to verify resulting project state and advisor outputs.

​

Branching Workflow

• Map to Git branches (e.g., staging branch → staging Git branch)
• Automatically sync migrations via GitHub integration
• Use for long-lived environments (staging, production)

• Created automatically for PRs (if GitHub integration enabled)
• Short-lived, deleted after PR merge
• Use for testing feature migrations

• main → Production Supabase project
• staging → Staging persistent branch
• develop → Development persistent branch (optional)
• Feature branches → Preview branches (auto-created)

• Enable in Supabase Dashboard → Settings → Integrations → GitHub
• Maps Git branches to Supabase branches/projects
• Automatic migration deployment on push
• Preview branches created for PRs

​

Data Isolation & Key Configuration (CRITICAL)

• ✅ Same Supabase URL for staging and production is CORRECT (using branching, not separate projects)
• ✅ Different anon keys per branch is REQUIRED (verify in dashboard)
• ✅ Data stays isolated - seed data in staging never appears in production
• ✅ Only migrations merge when PR is merged to main

• The one-time Lovable->Supabase migration completed in 2026-01; its test plan and checklist are archived at docs/archive/migration-2026-01/PRE_MIGRATION_TEST_PLAN.md and docs/archive/migration-2026-01/PRE_MIGRATION_CHECKLIST.md.
• For the current prod-promotion workflow, see docs/runbooks/PROD_MIGRATION_PROMOTION.md.

​

Fallow MCP Usage (OPTIONAL — Codebase Analysis)

Purpose: Fallow MCP exposes structured codebase analysis (dead code, duplication, complexity, boundaries) without manually parsing CLI output. Config file: .cursor/mcp.json — the fallow server is already configured. Restart Cursor after any MCP config change.

​

Tools Available

​

When to Use Fallow MCP

• ✅ Running the dead-code-auditor agent to identify orphans and unused exports
• ✅ Proposing file deletions — run analysis first to confirm the file is genuinely unused
• ✅ Reviewing a module for cleanup (replaces manual graph inspection)
• ✅ Checking complexity and duplication before or after refactors

• ✅ Running in CI: npm run deadcode:ci
• ✅ Generating full dead-code audits: npm run audit:unused-files
• ✅ Running local checks: npm run deadcode, npm run check:dupes, npm run check:health

​

Current Project Configuration

• Entry points: src/routes/**/*.tsx, supabase/functions/*/index.ts, scripts/**/*.ts
• Ignored files: Barrel indexes (src/cores/*/index.ts, src/platform/**/index.ts), docs workspace, test fixtures, supabase/functions/_shared
• Architecture boundaries: Zones for platform, cores, shared, and routes

​

CI Behavior

​

Related Commands and Agents

​

Context7 MCP Usage (REQUIRED)

Purpose: AI agents MUST use the Context7 MCP server to fetch up-to-date library documentation instead of relying on potentially outdated training data. This ensures accurate API usage for all project dependencies. Reference: See Context7 Documentation and Context7 Tips for best practices.

​

When to Use Context7

• ✅ Working with any project dependency (React, Supabase, TanStack Query, etc.)
• ✅ Implementing features using third-party library APIs
• ✅ Debugging issues related to library behavior
• ✅ Unsure about correct API usage, parameters, or return types
• ✅ Library version matters (this project uses specific versions - see package.json)

• ❌ Library APIs that may have changed between versions
• ❌ Deprecated methods or patterns
• ❌ New features in recent library releases

​

Project Dependencies (Use Context7 For)

​

Context7 Best Practices

// Before fetching docs, resolve the library ID
// Use: resolve-library-id for "tanstack react query"
// Returns: /tanstack/query (use this for get-library-docs)

// ✅ CORRECT: Specify version when fetching docs
// get-library-docs for "@tanstack/react-query" version "5.x"

// ❌ WRONG: Generic queries without version context
// "How do I use React Query?" (may return outdated v3/v4 patterns)

// ✅ GOOD: Specific topic queries
"TanStack Query v5 useMutation with optimistic updates"
"Supabase JS v2 RLS policies with auth.uid()"
"React Router v6 data loaders and actions"

// ❌ AVOID: Overly broad queries
"How to use React Query" (too general)

• Check AGENTS.md for project-specific patterns (e.g., staleTime/gcTime requirements)
• Review existing code in src/ for established conventions
• Ensure compatibility with project architecture

​

Context7 Workflow

​

Example: TanStack Query Usage

// 1. Fetch Context7 docs for TanStack Query v5 useQuery
// 2. Context7 provides current API signature and options
// 3. Cross-reference with AGENTS.md QueryClient requirements
// 4. Result: Correct implementation with project patterns

const { data, error, isLoading } = useQuery({
  queryKey: ['hr-employees', organizationId],
  queryFn: async () => {
    const { data, error } = await supabase
      .from('hr_employees')
      .select('*')
      .eq('organization_id', organizationId);
    if (error) throw error;
    return data;
  },
  // From Context7: v5 uses 'gcTime' not 'cacheTime'
  // From AGENTS.md: REQUIRED values for this project
  staleTime: 5 * 60 * 1000,
  gcTime: 10 * 60 * 1000,
  enabled: !!organizationId,
});

​

Anti-Patterns

• ❌ Assuming API stability - Always verify with Context7 for version-specific APIs
• ❌ Using deprecated patterns - Context7 shows current recommended patterns
• ❌ Ignoring breaking changes - v5 TanStack Query differs significantly from v4
• ❌ Guessing parameter names - Fetch docs to confirm exact API signatures

​

See Also

• Root AGENTS.md: AGENTS.md (current: docs/VERSIONS.md) - Quick reference
• Context7 Docs: https://context7.com/docs
• Supabase Branching: docs/database/migration-workflow.md (live); original playbook archived at docs/archive/migration-2026-01/COMPLETION_PLAN.md
• Fallow Docs: https://docs.fallow.tools
• Fallow VS Code Extension: https://marketplace.visualstudio.com/items?itemName=fallow-rs.fallow-vscode