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.

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.

Before starting, ensure you have:

• A Seedfast account (free tier available 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

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

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@latest", "mcp"],
      "env": {
        "SEEDFAST_API_KEY": "sfk_live_your_api_key_here"
      }
    }
  }
}

Restart Claude Desktop to load the new configuration.

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@latest", "mcp"],
      "env": {
        "SEEDFAST_API_KEY": "sfk_live_your_api_key_here"
      }
    }
  }
}

Continue.dev provides MCP support for VS Code users.

Add to .continue/config.json:

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "npx",
          "args": ["-y", "seedfast@latest", "mcp"],
          "env": {
            "SEEDFAST_API_KEY": "sfk_live_your_api_key_here"
          }
        }
      }
    ]
  }
}

For terminal-based workflows with Claude Code:

Add to your .mcp.json:

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

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

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...)

Add API Key to MCP Config:

Add your API key to the env section of your MCP configuration (as shown in the configuration examples above):

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

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.

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

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

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

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"

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

Your assistant returns a preview of what would be seeded — which tables, estimated row counts, dependency order — 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

Your assistant executes the exact plan you just reviewed.

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.

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.

Don't Seed in Production Without Explicit Intent

Protect with separate API keys without production access, environment validation in CI/CD, and confirmation prompts in interactive contexts.

"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

• Verify JSON syntax in .cursor/mcp.json
• Restart Cursor completely
• Check that SEEDFAST_API_KEY is in the env section

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@latest --version