Seed an Empty Postgres Database Without Leaving Claude Code

You have a feature branch open in Claude Code and the integration tests are ready to run, but the dev database behind them is empty. Claude Code MCP database seeding closes that last gap without a detour, letting the agent already sitting in your editor fill the schema with valid rows before a single test fires. Ask the model to write a seed script instead and you tend to get inserts whose foreign keys point at rows that were never created, a failure the generate test data with AI playbook walks through in depth.

This page stays deliberately narrow. One config block, one prompt, and an empty Postgres database comes back populated, all from the tool you already keep open. I run this a dozen times a day against branch databases, so what follows is the exact path from zero to seeded rather than a survey of every option.

When Claude Code starts, it reads your project's .mcp.json and launches the Seedfast server through npx, which then advertises a small set of tools over the Model Context Protocol. The one that matters here is seedfast_run. You hand the agent a scope in plain English and it forwards that scope to seedfast_run. From there the engine reads your live Postgres schema and walks the foreign-key graph to work out a safe insert order before it writes a single row, so the parent a child points at is already in place by the time that child arrives.

That division of labor keeps the data coherent, since the agent stays in the part it does well, describing intent and reasoning about your feature, and hands the relational bookkeeping to code that reads the real schema rather than guessing at it. Ordering belongs to the seeder — it resolves inserts across the graph and breaks a cycle only on a nullable back-edge where the schema permits one — while enforcement of referential integrity never leaves the database. The deeper argument for why a language model loses the relational thread lives in the same playbook, so I won't relitigate it here.

Two things have to exist before the agent can seed anything, a Seedfast account and an API key, so log in at seedfa.st, open Settings → API Keys, and create one; it comes back in the sfk_live_... format. Treat that key like any other credential and keep the real value out of version control, because anything you commit to .mcp.json travels with the repo. Teams that check the file in usually commit it with the placeholder and paste the real key only into their local copies.

Add Seedfast to the project's .mcp.json at the repository root:

{
  "mcpServers": {
    "seedfast": {
      "command": "npx",
      "args": ["-y", "seedfast@latest", "mcp"],
      "env": {
        "SEEDFAST_API_KEY": "sfk_live_your_api_key_here"
      }
    }
  }
}

You'll need Node.js 18 or newer on the machine, since the server runs through npx. Restart Claude Code so it picks up the new config, then confirm the wiring by asking the agent to run seedfast_doctor, which reports whether the CLI is healthy and your key authenticated. If you're setting up Cursor, VS Code, or Claude Desktop instead, or you hit a snag along the way, the MCP setup guide carries the config for every client and the troubleshooting steps.

With the server wired up, a real session reads like a sentence. Say you're building order history and the tests need customers who actually own something. You would type roughly this:

Seed customers with related orders and line items, a few rows each

Claude Code reads that, calls seedfast_run with the scope, and the engine seeds the three tables in dependency order so every order points at a real customer and every line item at a real order. And because scope controls scale as much as shape, you ask for a few rows each when a unit test just needs something to assert against, and for thousands when you want to watch a query plan buckle under load.

How long it takes tracks how much you asked for. A single table lands in five to fifteen seconds, five to ten related tables in thirty to sixty, and a full schema in two to five minutes, so the order-history seed above finishes while you're still reading the test you're about to run. Once it's done, ask the agent for the run summary and it reports which tables succeeded along with the total rows written, or run a quick SELECT count(*) yourself and read the numbers straight from the database.

There is an honest worry sitting underneath all of this. You are handing an agent a write path into a database, which is a reasonable thing to feel cautious about, so the single rule that keeps it boring is to point Seedfast at a dev or branch database only, the same discipline you would already apply to any seed script a teammate wrote. The blast radius stays small for a structural reason too, since Seedfast needs no production data to do its job; it reads the schema and writes fresh rows generated from scratch, so nothing about your real customer records has to come anywhere near the run.

That same seed call drops straight into CI, where the MCP wrapper gives way to the plain CLI. The pipeline version of the workflow, fresh rows for every pull request with no hand-maintained seed.sql in sight, has its own write-up in synthetic data for CI/CD.

Claude Code, Anthropic's agentic coding tool, supports MCP servers natively and reads their configuration from a project-scoped .mcp.json at the repository root. Once you add an mcpServers block naming the command to launch, Claude Code starts that server at boot and its tools, Seedfast's included, become available to the agent mid-conversation.

Seedfast can seed anything from a single table to every table across every schema, described to Claude Code in plain language rather than SQL. A scope such as "seed customers with related orders and line items" populates one connected slice, while "seed all tables in all schemas" fills the whole database. Because the engine re-reads your live schema on each run, a table you added this morning flows through without extra wiring. Sensitive tables stay out when you name them as exclusions in the scope.

A seed run from Claude Code usually finishes in well under a minute, and even a full schema of fifty-plus tables stays inside a few minutes. Expect five to fifteen seconds when a single table is in scope and two to five minutes at the everything-at-once end, which is why scoping the seed to the feature at hand keeps the wait short.

Yes, the same server block works unchanged in Cursor, VS Code, Claude Desktop, and Claude Code, because each client launches Seedfast through the identical npx command. Only the file it lives in moves around, with Cursor reading .cursor/mcp.json and VS Code keeping the block in its own MCP settings. The MCP setup guide spells out the location for each client, and Codex CLI takes the same npx command in TOML form, covered in its own walkthrough.

Seedfast turns the empty-database step into one line inside Claude Code, reading your live schema and writing valid, connected rows off it with no production data involved. Start on the 30-day free trial, no card required, and the first rows usually land a couple of minutes after the config block goes in.