How to Use SupaForge with AI Agents

Why an Agent?

“Why does this work on staging but not in production?” is a question an agent can now answer for itself. SupaForge runs as an MCP server: the agent compares your environments, reads exactly what differs — a missing policy, a grant, an auth setting — and proposes the SQL that fixes it. Nothing is written until you say so.

1. Give It a Project

The server reads supaforge.config.json in your project. If you don't have one, run supaforge init there, or write it with connection strings taken from the environment:

{
  "environments": {
    "staging": {
      "dbUrl": "$STAGING_DATABASE_URL",
      "projectRef": "STAGING_REF",
      "accessToken": "$SUPABASE_ACCESS_TOKEN"
    },
    "production": {
      "dbUrl": "$PRODUCTION_DATABASE_URL",
      "projectRef": "PROD_REF",
      "accessToken": "$SUPABASE_ACCESS_TOKEN"
    }
  },
  "source": "staging",
  "target": "production"
}

2. Add the Server

Cursor

Add SupaForge to Cursor — one click, then approve it. It uses the folder you have open as the project.

VS Code

Install SupaForge in VS Code for Copilot's agent mode, again using the open folder.

Claude Desktop

Download supaforge-<version>-<platform>.mcpb for your machine from the latest release and open it. Claude asks for your project directory.

Claude Code

The plugin adds the server and a skill that teaches Claude to preview fixes and ask before applying them:

/plugin marketplace add akalsoftware/claude-plugins
/plugin install supaforge@akalsoftware

Or just the server:

claude mcp add supaforge -- npx -y @akal/supaforge mcp

Any Other Client

{
  "mcpServers": {
    "supaforge": {
      "command": "npx",
      "args": ["-y", "@akal/supaforge", "mcp", "--project", "/path/to/project"]
    }
  }
}

It is in the MCP Registry as io.github.akalsoftware/supaforge, so clients that browse the registry find it there.

3. Ask

• “What has drifted between staging and production?”
• “Are there tables in production without RLS?”
• “Show me the SQL to bring production's policies in line, but don't run it.”
• “Snapshot production before we change anything.”

What the Agent Can Do

• scan_drift and get_check_result — read-only. They compare and report, and write nothing.
• apply_fixes — marked destructive, so your client asks before running it. It previews unless told otherwise, and it never drops anything: destructive fixes are held back, for you to run with the CLI's --allow-destructive if you mean them.
• take_snapshot and create_migration — write local files only.

Keeping It Safe

• Read the plan before approving. The fixes are plain SQL in the order they would run.
• Keep production credentials out of the agent's reach unless you mean it to act there: point the config at environment variables, and give production a read-only role for scans.
• One project per server. It reads the config in its own project and refuses another path unless started with --allow-config-path, so a prompt cannot point it at a different project's credentials.