Seedfast

Documentation

MCP Setup Guide

The Model Context Protocol (MCP) enables AI assistants to interact directly with developer tools. Seedfast's MCP server brings intelligent database seeding into your AI workflow — no context switching required.

This guide walks through connecting Seedfast MCP to Claude Desktop, Cursor IDE, VS Code, or Claude Code CLI.

Understanding MCP Architecture

Before diving into configuration, it helps to understand what MCP actually does:

┌──────────────────────┐       ┌──────────────────────┐       ┌──────────────────────┐
│   AI Assistant       │ ◄───► │   Seedfast MCP       │ ◄───► │   Your Database      │
│   (Claude/Cursor)    │       │   Server             │       │   (PostgreSQL)       │
│                      │       │                      │       │                      │
│   Natural language   │       │   JSON-RPC protocol  │       │   SQL execution      │
│   commands           │       │   Tool orchestration │       │   Data generation    │
└──────────────────────┘       └──────────────────────┘       └──────────────────────┘

The MCP server acts as a bridge between your AI assistant and Seedfast's backend. When you ask Claude to "seed my database with test users," the assistant invokes MCP tools that execute the actual seeding operations.

Prerequisites

Before starting, ensure you have:

• A Seedfast account (free plan at seedfa.st)
• PostgreSQL database accessible from your machine
• Node.js 18+ installed (for npx-based MCP server)
• One of: Claude Desktop, Cursor IDE, VS Code with Continue.dev, or Claude Code CLI

Installation

No separate installation required. The MCP server is built into the Seedfast CLI and runs via npx directly from your configuration.

Pin the version

Every example below asks for an exact version rather than seedfast@latest. That matters because your MCP config is a file your whole team runs from, and @latest re-resolves on every server start. We ship often enough that two people on the same branch in the same week can end up on different builds, which turns "works on my machine" into a question nobody can answer from the config alone.

Pin it, and bump the pin when you choose to:

npm view seedfast version   # what's current

For a throwaway local experiment, @latest is fine. Anything committed, shared, or running in CI should name a version. One caveat worth knowing: the CLI talks to the Seedfast API, so a pin you leave untouched for many months can eventually fall behind what the API expects. Treat bumping it as routine maintenance rather than something you do only when a run breaks.

Keep the API key out of the file

Four of the five clients here can read the key from your environment instead of storing it in the config, which is what you want for any file that lives in a repository. Each one spells it differently, and the sections below use the right syntax for each. Claude Desktop is the exception and needs a literal value, though its config sits in your OS application-support directory rather than your project, so it is not something you would commit by accident.

Export the key once in your shell profile:

export SEEDFAST_API_KEY="sfk_live_your_actual_key_here"

Configure Claude Desktop

Claude Desktop is the official Anthropic client with native MCP support.

Locate your config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Add the Seedfast server:

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

Claude Desktop does not expand variables in this file, so the key has to be written out in full. Because the config lives in your application-support directory and not in a project, that is a smaller problem than it looks, but the file does hold a usable credential in plain text and deserves the same care as any other dotfile that does.

Restart Claude Desktop to load the new configuration.

Configure Cursor IDE

Cursor runs MCP servers in a sandboxed environment. Authentication is configured directly in the MCP config's env section.

Add to .cursor/mcp.json or global settings:

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

Cursor interpolates ${env:NAME} in command, args, env, url and headers, so .cursor/mcp.json can be checked in as it stands and each person supplies their own key through the environment.

Configure VS Code with Continue.dev

Continue.dev provides MCP support for VS Code users.

Add to .continue/config.json:

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "npx",
          "args": ["-y", "seedfast@2.6.0", "mcp"],
          "env": {
            "SEEDFAST_API_KEY": "${{ secrets.SEEDFAST_API_KEY }}"
          }
        }
      }
    ]
  }
}

Continue resolves ${{ secrets.NAME }} in args and env against its own secret store, so the key never appears in config.json.

Configure Claude Code CLI

For terminal-based workflows with Claude Code:

Add to your .mcp.json:

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

Claude Code expands ${VAR} and ${VAR:-default} in command, args, env, url and headers. Since .mcp.json is meant to be committed so everyone on the team picks up the same servers, referencing the variable is the whole point: the file describes the setup and your shell supplies the credential.

Verify Installation

After configuration, verify the MCP server is accessible. In your AI assistant, ask:

Use seedfast_doctor to check the installation

You should see output confirming the MCP server is running and authenticated:

CLI Status: OK
Version: 1.26.0
Auth: OK (SEEDFAST_API_KEY configured)
Platform: darwin/arm64
MCP Server Version: 1.0.0

Configure Authentication

Seedfast MCP uses config-based authentication via the env section in your MCP configuration.

Get Your API Key:

1. Log in to seedfa.st
2. Navigate to Settings → API Keys
3. Click Create New Key
4. Copy the key (format: sfk_live_xxxxx...)

Point the config at the key:

Export it in your shell profile so the value lives in one place:

export SEEDFAST_API_KEY="sfk_live_your_actual_key_here"

Then reference it from the env section. Each client has its own syntax:

Client	Config file	Value to use
Claude Code	.mcp.json	${SEEDFAST_API_KEY}
Cursor	.cursor/mcp.json	${env:SEEDFAST_API_KEY}
Continue.dev	.continue/config.json	${{ secrets.SEEDFAST_API_KEY }}
Codex CLI	config.toml	env_vars = ["SEEDFAST_API_KEY"]
Claude Desktop	claude_desktop_config.json	the literal key, no expansion

Codex is the odd one out in shape rather than intent: instead of substituting a value it whitelists the variable name and forwards whatever your shell already has.

In CI, set SEEDFAST_API_KEY as a pipeline secret and the same committed config keeps working without a local edit.

Your First AI-Powered Seed

With everything configured, try your first seeding operation.

Test Database Connection:

Test the database connection to postgresql://myuser:mypass@localhost:5432/mydb

Create a Seeding Plan:

Create a seeding plan for my HR schema for just employees, departments, and salaries tables

This generates a plan without executing it, so you can review what will be seeded.

Execute Seeding:

Seed my database at postgresql://myuser:mypass@localhost:5432/mydb — seed all tables in all schemas

Your assistant will run the seed and report progress as it goes.

Example Session

You: Seed postgresql://postgres:postgres@localhost:5432/mydb
    with all tables in all schemas

AI:  Seeding started.

     Progress: 5/22 tables (23%), 25 rows...
     Progress: 12/22 tables (55%), 62 rows...
     Progress: 22/22 tables (100%), 117 rows

     Seeding complete!
     - Tables seeded: 22/22 (100%)
     - Total rows: 117
     - Status: Success

Available MCP Tools

Core Tools:

• seedfast_doctor — Verify CLI installation, environment, and auth status
• seedfast_connections_test — Test database connectivity
• seedfast_run — Execute database seeding
• seedfast_run_status — Check seeding progress
• seedfast_run_cancel — Cancel running operation

Plan Management Tools:

• seedfast_plan — Create seeding plan by analyzing database schema
• seedfast_plans_list — List all seeding plans in current session
• seedfast_plan_get — Get a seeding plan by ID
• seedfast_plan_create — Create a seeding plan manually (without CLI)
• seedfast_plan_update — Update an existing seeding plan
• seedfast_plan_delete — Delete a seeding plan

MCP Resources: Beyond Tools

Seedfast MCP exposes not just tools but also resources — read-only data endpoints that AI assistants can access for context.

Available Resources:

• seedfast://plans/{planId} — Get specific plan details
• seedfast://runs/{runId}/summary — Get run status and results
• seedfast://runs/{runId}/log — Stream run events as NDJSON

Scope Writing: MCP Prompt Patterns

The --scope parameter is how you communicate intent to Seedfast's AI engine. These MCP prompt patterns produce better results — faster.

Be Specific, Not Generic

# Too broad - seeds entire database, slow
"Seed all tables"

# Better - targets relevant subsystem
"Seed user authentication tables: users, sessions, password_resets"

Be Explicit About Schemas

"Seed all tables" may only seed one schema based on context. Use "seed all tables in all schemas" when you actually want a full database seed.

Specify Relationships Explicitly

When relational data matters for your tests, state relationships explicitly:

# Implicit relationships - AI may or may not connect them
"Seed users and orders"

# Explicit relationships - guarantees connected data
"Seed users with related orders and line items"

Use Negative Scoping for Exclusions

# Exclude sensitive or irrelevant tables
"Seed all tables in public schema except audit_logs and system_configs"

Plan-Then-Execute Pattern

For production-like environments or large datasets, always review before seeding. Ask your assistant to plan first, look at what it proposes, then approve.

Step 1: Ask for a plan

"Create a seeding plan for products, warehouses, and stock_levels tables"

Your assistant returns a preview of what would be seeded — which tables, estimated row counts, how they relate — without writing anything to the database yet:

Tables (3):
  - products
  - warehouses
  - stock_levels

Preview: Will seed 3 tables...

Step 2: Review

Check that the plan includes the tables you want and excludes anything sensitive — audit logs, archived data, anything you don't want touched.

Step 3: Approve

"Looks good, run that plan"

Your assistant executes the exact plan you just reviewed.

Performance Expectations

Narrow Scope = Faster Seeding

Fewer tables means faster completion. Approximate run times at the default row count (~5 rows per table), with real numbers depending on row count and schema complexity:

• Single table: 5-15 seconds
• 5-10 related tables: 30-60 seconds
• Full schema (50+ tables): 2-5 minutes

For development iteration, seed only what your current feature needs.

Reading Run Results

When seeding completes, you get a per-table summary. If some tables fail, the run continues with the rest, and the summary tells you exactly which ones landed and which didn't:

Summary:
  Success: false
  Total Tables: 10
  Succeeded: 8
  Failed: 2 (orders, payments)

Investigate failed tables individually and adjust scope or fix the underlying schema issue before re-running.

Anti-Patterns to Avoid

Don't Seed in Production Without Explicit Intent

Seedfast writes rows wherever your connection string points, and it has no way to tell a production database from a development one. There is no host allow-list, no environment check, and no confirmation step before a run. Whatever guard you want here, you build on your side. The two that cost nothing are keeping the production connection string out of any environment the agent can read, and gating the CI job on your own branch or environment condition. Narrowing database privileges is worth testing before you rely on it, because a role with reduced grants can fail the inserts outright rather than limiting them.

Worth knowing about the blast radius, since it shapes how much guarding is worth it. A run only inserts. It does not drop, truncate or update, so the failure mode is unwanted rows in a live table rather than lost data.

Troubleshooting

"npx: command not found"

Node.js isn't installed or not in your PATH. Install Node.js 18+ from nodejs.org.

"Not authenticated" or "SEEDFAST_API_KEY not configured" error

Verify your API key is configured in MCP config:

1. Open your MCP config file (see configuration sections above for location)
2. Check that the env section contains SEEDFAST_API_KEY
3. Verify the key starts with sfk_live_
4. Restart your AI assistant to reload the config

You can also verify auth status by asking:

Run seedfast_doctor to check the installation

Expected output should show: Auth: OK (SEEDFAST_API_KEY configured)

Claude Desktop doesn't see the server

• Verify JSON syntax in config file
• Ensure Claude Desktop was fully restarted (not just minimized)
• Check Developer Tools console for errors

Cursor IDE issues

npm package not found

If you see errors about the package not being found, try clearing npm cache:

npm cache clean --force
npx -y seedfast@2.6.0 --version

Use the same version your config pins, so a success here tells you something about the build you actually run.