Seedfast

Preenche um banco de dados PostgreSQL com dados de teste sintéticos gerados a partir do seu schema ativo, com cada chave estrangeira apontando para uma linha existente. Planeje, execute e inspecione execuções de seed a partir de um agente de IA.

Ver em seedfa.stExperimente este MCPPatrocinado

Documentação

Guia de Configuração do MCP

O Model Context Protocol (MCP) permite que assistentes de IA interajam diretamente com ferramentas de desenvolvimento. O servidor MCP do Seedfast traz o seeding inteligente de banco de dados para o seu fluxo de trabalho com IA — sem necessidade de alternar de contexto.

Este guia explica como conectar o Seedfast MCP ao Claude Desktop, Cursor IDE, VS Code ou Claude Code CLI.

Entendendo a Arquitetura do MCP

Antes de mergulhar na configuração, é útil entender o que o MCP realmente faz:

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

O servidor MCP atua como uma ponte entre seu assistente de IA e o backend do Seedfast. Quando você pede ao Claude para "popular meu banco de dados com usuários de teste", o assistente invoca ferramentas MCP que executam as operações reais de seeding.

Pré-requisitos

Antes de começar, certifique-se de ter:

Uma conta Seedfast (plano gratuito em seedfa.st)
Banco de dados PostgreSQL acessível a partir da sua máquina
Node.js 18+ instalado (para o servidor MCP baseado em npx)
Um dos seguintes: Claude Desktop, Cursor IDE, VS Code com Continue.dev ou Claude Code CLI

Instalação

Nenhuma instalação separada é necessária. O servidor MCP está integrado ao CLI do Seedfast e é executado via npx diretamente a partir da sua configuração.

Fixe a versão

Cada exemplo abaixo solicita uma versão exata em vez de seedfast@latest. Isso é importante porque sua configuração MCP é um arquivo que todo o time executa, e @latest é re-resolvido a cada inicialização do servidor. Lançamos atualizações com frequência suficiente para que duas pessoas no mesmo branch na mesma semana possam acabar em builds diferentes, o que transforma "funciona na minha máquina" em uma pergunta que ninguém consegue responder apenas pela configuração.

Fixe a versão e atualize-a quando você escolher:

npm view seedfast version   # what's current

Para um experimento local descartável, @latest é suficiente. Qualquer coisa commitada, compartilhada ou executada em CI deve especificar uma versão. Uma observação que vale saber: o CLI conversa com a API do Seedfast, então uma versão fixa que você deixa intocada por muitos meses pode eventualmente ficar defasada em relação ao que a API espera. Trate a atualização como manutenção de rotina, e não como algo que você faz apenas quando uma execução falha.

Mantenha a chave da API fora do arquivo

Quatro dos cinco clientes aqui podem ler a chave do seu ambiente em vez de armazená-la na configuração, que é o que você deseja para qualquer arquivo que viva em um repositório. Cada um escreve isso de forma diferente, e as seções abaixo usam a sintaxe correta para cada um. O Claude Desktop é a exceção e precisa de um valor literal, embora sua configuração fique no diretório de suporte de aplicativos do seu sistema operacional, e não no seu projeto, então não é algo que você commitaria por acidente.

Exporte a chave uma vez no seu perfil de shell:

export SEEDFAST_API_KEY="sfk_live_your_actual_key_here"

Configurar o Claude Desktop

O Claude Desktop é o cliente oficial da Anthropic com suporte nativo a MCP.

Localize seu arquivo de configuração:

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

Adicione o servidor Seedfast:

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

O Claude Desktop não expande variáveis neste arquivo, então a chave precisa ser escrita por extenso. Como a configuração fica no diretório de suporte de aplicativos e não em um projeto, isso é um problema menor do que parece, mas o arquivo contém uma credencial utilizável em texto puro e merece o mesmo cuidado que qualquer outro dotfile que faça isso.

Reinicie o Claude Desktop para carregar a nova configuração.

Configurar o Cursor IDE

O Cursor executa servidores MCP em um ambiente isolado (sandbox). A autenticação é configurada diretamente na seção env da configuração MCP.

Adicione em .cursor/mcp.json ou nas configurações globais:

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

O Cursor interpola ${env:NAME} em command, args, env, url e headers, então .cursor/mcp.json pode ser commitado como está e cada pessoa fornece sua própria chave por meio do ambiente.

Configurar o VS Code com Continue.dev

O Continue.dev fornece suporte a MCP para usuários do VS Code.

Adicione em .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 }}"
          }
        }
      }
    ]
  }
}

O Continue resolve ${{ secrets.NAME }} em args e env usando seu próprio cofre de segredos, então a chave nunca aparece em config.json.

Configurar o Claude Code CLI

Para fluxos de trabalho baseados em terminal com o Claude Code:

Adicione ao seu .mcp.json:

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

O Claude Code expande ${VAR} e ${VAR:-default} em command, args, env, url e headers. Como .mcp.json deve ser commitado para que todos no time usem os mesmos servidores, referenciar a variável é exatamente o objetivo: o arquivo descreve a configuração e seu shell fornece a credencial.

Verificar a Instalação

Após a configuração, verifique se o servidor MCP está acessível. No seu assistente de IA, pergunte:

Use seedfast_doctor to check the installation

Você deve ver uma saída confirmando que o servidor MCP está em execução e autenticado:

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

Configurar a Autenticação

O Seedfast MCP usa autenticação baseada em configuração por meio da seção env na sua configuração MCP.

Obtenha sua chave de API:

Faça login em seedfa.st
Navegue até Configurações → Chaves de API
Clique em Criar nova chave
Copie a chave (formato: sfk_live_xxxxx...)

Aponte a configuração para a chave:

Exporte-a no seu perfil de shell para que o valor fique em um único lugar:

export SEEDFAST_API_KEY="sfk_live_your_actual_key_here"

Em seguida, referencie-a na seção env. Cada cliente tem sua própria sintaxe:

Cliente	Arquivo de configuração	Valor a usar
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`	a chave literal, sem expansão

O Codex é o diferente na forma, não na intenção: em vez de substituir um valor, ele coloca o nome da variável na lista de permissões e encaminha o que seu shell já tem.

Em CI, defina SEEDFAST_API_KEY como um segredo de pipeline e a mesma configuração commitada continua funcionando sem edição local.

Seu Primeiro Seed com IA

Com tudo configurado, tente sua primeira operação de seeding.

Teste a conexão com o banco de dados:

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

Crie um plano de seeding:

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

Isso gera um plano sem executá-lo, para que você possa revisar o que será populado.

Execute o seeding:

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

Seu assistente executará o seed e reportará o progresso ao longo do processo.

Exemplo de Sessão

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

Ferramentas MCP Disponíveis

Ferramentas principais:

seedfast_doctor — Verifica a instalação do CLI, o ambiente e o status de autenticação
seedfast_connections_test — Testa a conectividade com o banco de dados
seedfast_run — Executa o seeding do banco de dados
seedfast_run_status — Verifica o progresso do seeding
seedfast_run_cancel — Cancela a operação em execução

Ferramentas de gerenciamento de planos:

seedfast_plan — Cria um plano de seeding analisando o esquema do banco de dados
seedfast_plans_list — Lista todos os planos de seeding na sessão atual
seedfast_plan_get — Obtém um plano de seeding por ID
seedfast_plan_create — Cria um plano de seeding manualmente (sem CLI)
seedfast_plan_update — Atualiza um plano de seeding existente
seedfast_plan_delete — Exclui um plano de seeding

Recursos MCP: Além das Ferramentas

O Seedfast MCP expõe não apenas ferramentas, mas também recursos — endpoints de dados somente leitura que os assistentes de IA podem acessar para obter contexto.

Recursos disponíveis:

seedfast://plans/{planId} — Obtém detalhes específicos de um plano
seedfast://runs/{runId}/summary — Obtém status e resultados de execução
seedfast://runs/{runId}/log — Transmite eventos de execução como NDJSON

Escrita de Escopo: Padrões de Prompt MCP

O parâmetro --scope é como você comunica a intenção ao mecanismo de IA do Seedfast. Esses padrões de prompt MCP produzem melhores resultados — mais rápido.

Seja específico, não genérico

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

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

Seja explícito sobre esquemas

"Popular todas as tabelas" pode popular apenas um esquema dependendo do contexto. Use "popular todas as tabelas em todos os esquemas" quando você realmente quiser um seed completo do banco de dados.

Especifique relacionamentos explicitamente

Quando dados relacionais são importantes para seus testes, declare os relacionamentos explicitamente:

# 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 escopo negativo para exclusões

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

Padrão Planejar-Depois-Executar

Para ambientes semelhantes a produção ou grandes conjuntos de dados, sempre revise antes de popular. Peça ao seu assistente para planejar primeiro, examine o que ele propõe e depois aprove.

Etapa 1: Peça um plano

"Crie um plano de seeding para as tabelas products, warehouses e stock_levels"

Seu assistente retorna uma prévia do que seria populado — quais tabelas, contagens estimadas de linhas, como elas se relacionam — sem gravar nada no banco de dados ainda:

Tables (3):
  - products
  - warehouses
  - stock_levels

Preview: Will seed 3 tables...

Etapa 2: Revise

Verifique se o plano inclui as tabelas que você deseja e exclui qualquer coisa sensível — logs de auditoria, dados arquivados, qualquer coisa que você não queira tocar.

Etapa 3: Aprove

"Parece bom, execute esse plano"

Seu assistente executa exatamente o plano que você acabou de revisar.

Expectativas de Desempenho

Escopo estreito = seeding mais rápido

Menos tabelas significa conclusão mais rápida. Tempos aproximados de execução na contagem padrão de linhas (~5 linhas por tabela), com números reais dependendo da contagem de linhas e da complexidade do esquema:

Tabela única: 5-15 segundos
5-10 tabelas relacionadas: 30-60 segundos
Esquema completo (50+ tabelas): 2-5 minutos

Para iteração de desenvolvimento, popule apenas o que seu recurso atual precisa.

Lendo Resultados de Execução

Quando o seeding é concluído, você obtém um resumo por tabela. Se algumas tabelas falharem, a execução continua com as demais, e o resumo informa exatamente quais foram concluídas e quais não foram:

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

Investigue as tabelas com falha individualmente e ajuste o escopo ou corrija o problema subjacente no esquema antes de executar novamente.

Anti-Padrões a Evitar

Não faça seeding em produção sem intenção explícita

O Seedfast grava linhas onde quer que sua string de conexão aponte, e não tem como distinguir um banco de produção de um de desenvolvimento. Não há lista de permissões de hosts, nenhuma verificação de ambiente e nenhuma etapa de confirmação antes de uma execução. Qualquer proteção que você queira aqui, você constrói do seu lado. As duas que não custam nada são manter a string de conexão de produção fora de qualquer ambiente que o agente possa ler e condicionar o job de CI à sua própria condição de branch ou ambiente. Restringir privilégios do banco de dados vale a pena testar antes de confiar nisso, porque uma função com permissões reduzidas pode falhar nos inserts diretamente, em vez de limitá-los.

Vale saber sobre o raio de impacto, pois isso determina o quanto de proteção vale a pena. Uma execução apenas insere. Ela não faz drop, truncate ou update, então o modo de falha são linhas indesejadas em uma tabela ativa, e não perda de dados.

Solução de Problemas

"npx: command not found"

O Node.js não está instalado ou não está no seu PATH. Instale o Node.js 18+ em nodejs.org.

Erro "Not authenticated" ou "SEEDFAST_API_KEY not configured"

Verifique se sua chave de API está configurada na configuração MCP:

Abra seu arquivo de configuração MCP (veja as seções de configuração acima para a localização)
Verifique se a seção env contém SEEDFAST_API_KEY
Verifique se a chave começa com sfk_live_
Reinicie seu assistente de IA para recarregar a configuração

Você também pode verificar o status de autenticação perguntando:

Run seedfast_doctor to check the installation

A saída esperada deve mostrar: Auth: OK (SEEDFAST_API_KEY configured)

O Claude Desktop não vê o servidor

Verifique a sintaxe JSON no arquivo de configuração
Certifique-se de que o Claude Desktop foi totalmente reiniciado (não apenas minimizado)
Verifique o console do Developer Tools para erros

Problemas no Cursor IDE

Pacote npm não encontrado

Se você vir erros sobre o pacote não encontrado, tente limpar o cache do npm:

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

Use a mesma versão que sua configuração fixa, para que um sucesso aqui diga algo sobre o build que você realmente executa.