Database Schema Changes with MCP: A Step-by-Step Playbook (Supabase and Neon)

Schema changes are the database edits that ship with features: a new column, an index, a renamed table. A developer writes the migration, tests it somewhere safe, and applies it without breaking the app. With MCP (Model Context Protocol), a coding agent can inspect the schema, draft the migration and run it on a disposable branch through the Supabase or Neon MCP servers.

Both vendors are blunt about production risk, and this playbook follows their advice as of October 2026. The agent drafts and tests. A developer reviews the SQL and approves the step that touches the real database.

What you need

• Supabase MCP server or Neon MCP server, depending on where your Postgres lives. See our Supabase MCP server profile and Neon MCP server profile.
• A coding agent with repo access, such as Claude Code or Cursor. Setup guides: Claude Code to Supabase and Claude Code to Neon.
• A non-production target. For Neon, that's a branch. For Supabase, a development project or a branch; Supabase's MCP docs say branching is experimental and needs a paid plan.
• Your migration tool of record (Supabase CLI migrations, Prisma, Drizzle or plain SQL files), so the agent writes changes where your team expects them.

The workflow

1. Describe the change in plain words. For example: "Add a nullable referral_code column to customers with a unique index."
2. Inspect the current schema. On Supabase, list_tables and list_migrations show tables and applied migrations. On Neon, get_database_tables and describe_table_schema return tables, columns, types and constraints, per Neon's README.
3. Draft the migration. The agent writes the SQL into your repo's migration folder. Ask it to include a rollback statement and to flag locking risks, such as adding an index on a large table.
4. Test on a branch. On Neon, prepare_database_migration "creates a temporary branch to apply and test the migration safely before affecting the main branch," per the README. The agent then runs test queries on that branch with run_sql. On Supabase, create_branch makes a development branch (it can trigger a cost confirmation), and apply_migration runs the change there.
5. Compare before and after. Neon's compare_database_schema produces a SQL schema diff against another branch. On Supabase, get_advisors returns security and performance advisors, which can catch a missing index or an open table policy.
6. Regenerate types if you use them. Supabase's generate_typescript_types rebuilds TypeScript types from the new schema.
7. Human review. A developer reads the SQL, the diff and the advisor output, and runs the app's tests against the branch.
8. Apply. On Neon, complete_database_migration merges the change into the main branch and removes the temporary resources. On Supabase, merge_branch brings branch changes into the parent project; Supabase's docs say to review changes before merging. Many teams prefer to apply production migrations through CI rather than through the agent.
9. Commit and record. Commit the migration file, then confirm with list_migrations (Supabase) or a schema check that production matches the repo.

Example prompts

• "List the tables in the public schema and describe the customers table, including indexes and constraints."
• "Write a migration that adds a nullable referral_code text column with a unique index. Save it in supabase/migrations and include a rollback."
• "Prepare this migration on a temporary Neon branch, then run a test insert and a select to prove the unique index works."
• "Compare the schema on the migration branch with its parent and show me the SQL diff."
• "Run the Supabase advisors and tell me if this change introduced any security or performance warnings."

Guardrails

• Keep agents off production by default. Neon's MCP server guide recommends MCP "for development and testing only" and says, "Never connect MCP agents to production databases." Supabase allows production only when the task needs production evidence.
• Use read-only mode for anything exploratory. Neon's ?readonly=true removes write tools and runs run_sql in a READ ONLY transaction. Supabase's read_only=true runs SQL as a read-only Postgres user.
• Limit the database role. Neon's roleName option makes all SQL run as a Postgres role you choose, so normal grants apply. Neon notes management API tools are not restricted by that role.
• Scope and trim. Supabase recommends scoping to one project and restricting tool groups with the features option. Neon offers category filters such as schema and querying.
• Approve every write. Supabase says to "keep manual approval enabled for interactive work, and review each tool call before you run it." Neon's README says to "always review and authorize actions requested by the LLM before execution."
• Watch for prompt injection. Supabase calls prompt injection "the primary attack vector unique to LLMs." Data in your tables, such as a support ticket, can carry instructions. Read prompt injection through MCP and the MCP Security Center.

What to measure

• Migrations tested on a branch before apply, as a share of all migrations. Aim for all of them.
• Failed or rolled-back migrations before and after adding the agent.
• Review time per migration, from draft to approved.
• Advisor warnings introduced by agent-drafted changes and caught before merge.
• Drift incidents, where production schema doesn't match the repo.

Track your own history for a few sprints. Don't borrow outside benchmarks.

Next step

See more workflows in the MCP playbooks hub. If you want an agent-assisted migration flow set up with branches, scoped roles and CI apply, our Claude Code development team can help.

Frequently asked questions