Neon MCP — Casos de uso, Instalar & Demo ao vivo

Por que usar

Principais recursos

Branches copy-on-write instantâneos — perfeitos para testar migrações
Gerenciamento de projetos, filiais, funções e banco de dados
Execute SQL em qualquer branch (leitura ou gravação)
Recuperação de string de conexão para qualquer ramificação
Nativo: construído e mantido pela Neon

Demo ao vivo

Como fica na prática

neon.replay ▶ pronto

0/0

Instalar

Escolha seu cliente

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "neon": {
      "command": "npx",
      "args": [
        "-y",
        "@neondatabase/mcp-server-neon"
      ]
    }
  }
}

Abra Claude Desktop → Settings → Developer → Edit Config. Reinicie após salvar.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "neon": {
      "command": "npx",
      "args": [
        "-y",
        "@neondatabase/mcp-server-neon"
      ]
    }
  }
}

Cursor usa o mesmo esquema mcpServers que o Claude Desktop. Config de projeto vence a global.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "neon": {
      "command": "npx",
      "args": [
        "-y",
        "@neondatabase/mcp-server-neon"
      ]
    }
  }
}

Clique no ícone MCP Servers na barra lateral do Cline, depois "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "neon": {
      "command": "npx",
      "args": [
        "-y",
        "@neondatabase/mcp-server-neon"
      ]
    }
  }
}

Mesmo formato do Claude Desktop. Reinicie o Windsurf para aplicar.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "neon",
      "command": "npx",
      "args": [
        "-y",
        "@neondatabase/mcp-server-neon"
      ]
    }
  ]
}

O Continue usa um array de objetos de servidor em vez de um map.

~/.config/zed/settings.json

{
  "context_servers": {
    "neon": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "@neondatabase/mcp-server-neon"
        ]
      }
    }
  }
}

Adicione em context_servers. Zed recarrega automaticamente ao salvar.

claude mcp add neon -- npx -y @neondatabase/mcp-server-neon

Uma linha só. Verifique com claude mcp list. Remova com claude mcp remove.

Casos de uso

Usos do mundo real: Neon

Teste uma migração destrutiva do Postgres em uma ramificação copy-on-write

👤 Engenheiros executando alterações de esquema em um banco de dados de dados reais ⏱ ~20 min intermediate

Quando usar: Você tem uma migração (DROP COLUMN, big UPDATE, reconstrução de índice) e deseja executá-la em dados em formato de produto sem arriscar a produção.

Pré-requisitos

Chave de API Neon — console.neon.tech → Conta → Chaves de API

Fluxo

Crie um branch a partir do main

No projeto Neon <id>, crie um branch chamado 'test-drop-legacy' do branch principal. Retorne a cadeia de conexão da nova ramificação.✓ Copiado

→ Ramificação criada em <2 segundos, string de conexão retornada
Aplicar a migração na filial

Conecte-se à nova ramificação e execute: <colar migração SQL>. Relate contagens de linhas e quaisquer erros.✓ Copiado

→ A migração é concluída; conta faz sentido
Verifique e limpe

Execute consultas de sanidade nas tabelas alteradas. Se os resultados parecerem corretos, diga-me e aplicarei ao principal. Em seguida, exclua o branch de qualquer maneira.✓ Copiado

→ Verificação + filial excluída para evitar cobranças de armazenamento

Resultado: Confiança de que sua migração funciona com dados reais, sem risco de produção.

Armadilhas

A filial consome armazenamento proporcional ao quanto você escreve nela — Exclua filiais imediatamente após o teste – filiais abandonadas com gravações pesadas aumentam a conta
Branch é um snapshot — não vê gravações que acontecem no main após a criação do branch — Filial próxima ao horário de aplicação; ou use a viagem no tempo Neon para ramificar a partir de um carimbo de data/hora específico

Combine com: github · postgres

Crie um banco de dados efêmero por PR para testes de integração

👤 Equipes executando testes de integração de CI em Postgres reais ⏱ ~15 min intermediate

Quando usar: Cada PR precisa de seu próprio banco de dados isolado; As simulações do SQLite não são suficientes.

Fluxo

Crie uma filial com o nome do PR

Crie uma ramificação Neon no projeto <id> chamada 'pr-482' de main. Retorne a string de conexão.✓ Copiado

→ Branch pronto, string de conexão retornada
Execute o conjunto de testes nele

Defina DATABASE_URL para essa string de conexão. Execute npm run test:integration e relate os resultados.✓ Copiado

→ Testes executados, resumo de aprovação/reprovação
Derrubar

Exclua a ramificação 'pr-482'.✓ Copiado

→ Filial removida

Resultado: Testes de integração de banco de dados real com isolamento de segundos para ativação, sem contaminação de estado compartilhado.

Armadilhas

Limites de ramificação por projeto em planos inferiores — Os limites do nível gratuito são importantes; atualize ou implemente um varredor max-N-branches

Combine com: github

Dê a Claude acesso seguro somente leitura a um Neon DB de produção

👤 Engenheiros depurando dados de produção sem fornecer poder de gravação ao modelo ⏱ ~10 min beginner

Quando usar: Você deseja investigar um problema de produção, mas está nervoso com uma falha no UPDATE.

Fluxo

Crie uma função somente leitura

No projeto Neon <id>, crie uma função 'claude_readonly' com acesso somente SELECT no esquema público. Retorne sua string de conexão.✓ Copiado

→ Função criada; string de conexão retornada
Conecte-se via Postgres MCP

Use essa string de conexão com o Postgres MCP. Confirme que posso executar SELECT, mas não INSERT.✓ Copiado

→ SELECT funciona, erros INSERT com 'permissão negada'
Investigue o problema

Agora consulte a tabela de pedidos para obter o user_id afetado 99214. Qual é o estado da linha e há algo incomum?✓ Copiado

→ Diagnóstico concreto a partir de dados reais

Resultado: Uma sessão produtiva de depuração de produto com segurança somente leitura comprovada.

Armadilhas

Esquecer de definir o escopo de tabelas futuras – novas tabelas não são cobertas — Use ALTER DEFAULT PRIVILEGES para garantir que novas tabelas concedam SELECT a claude_readonly automaticamente

Combine com: postgres

Revise a evolução do esquema entre filiais antes de mesclar

👤 DBAs e engenheiros de plataforma ⏱ ~25 min advanced

Quando usar: Cada ramificação de recursos tem suas próprias alterações de esquema; você deseja ver a diferença cumulativa.

Fluxo

Listar filiais e seus estados

Liste todas as ramificações do Neon para o projeto <id>. Para cada um, dê-me uma descrição de uma linha de como seu esquema difere do principal.✓ Copiado

→ Resumo do delta do esquema por ramificação
Compare dois ramos em detalhes

Para filiais 'pagamentos de recursos' vs principais: compare as tabelas, colunas, índices e restrições. Formate como uma migração SQL.✓ Copiado

→ Diferença SQL revisável
Identifique conflitos

Se ambos os pagamentos de recursos e autenticação de recursos forem mesclados, as alterações de esquema entrarão em conflito? Onde?✓ Copiado

→ Lista específica de conflitos, não “nenhuma questão óbvia”

Resultado: Mesclar ordem e conflitos conhecidos antes de chegarem ao principal.

Armadilhas

Diff perde alterações dentro de visualizações materializadas ou processos armazenados — Seja explícito - peça ao Claude para também diferenciar pg_proc e visualizar definições, não apenas tabelas

Combine com: github

Combinações

Combine com outros MCPs para 10× de alavancagem

neon + github

Banco de dados efêmero por PR para testes de CI, com comentários de PR mostrando informações de conexão

Quando o PR # 482 abrir, crie um branch Neon 'pr-482', execute migrações + sementes nele, poste a string conn como um comentário privado no PR.✓ Copiado

neon + postgres

Use o Postgres MCP para consultas somente leitura mais seguras quando o Neon ativar o branch

Crie uma ramificação Neon com função somente leitura 'claude_ro'. Em seguida, use o Postgres MCP com essa string de conexão para investigar o problema do usuário-99214.✓ Copiado

neon + filesystem

Aplique arquivos de migração SQL locais a uma ramificação do Neon em ordem

Leia todos os arquivos .sql em /db/migrations/ na ordem dos nomes. Aplique-os em sequência ao 'staging' do branch Neon.✓ Copiado

Ferramentas

O que este MCP expõe

Ferramenta	Entradas	Quando chamar	Custo
list_projects	none	Veja seus projetos Neon	free
describe_project	project_id	Obtenha uma visão geral de um projeto	free
create_branch	project_id, name?, parent_id?, parent_lsn? or parent_timestamp?	Bifurque uma ramificação para teste ou bancos de dados por PR	branch storage billed by writes
list_branches	project_id	Filiais de estoque	free
delete_branch	project_id, branch_id	Limpeza após o teste – importante para controlar o custo de armazenamento	free
get_connection_string	project_id, branch_id?, role_name?, database_name?	Obtenha uma string de conexão com escopo para uma ramificação/função/db	free
run_sql	project_id, branch_id?, sql: str	Execute SQL em qualquer branch	compute time billed
describe_table_schema	project_id, branch_id?, table_name	Inspecione uma tabela sem escrever o SQL você mesmo	free
create_role / drop_role	project_id, role_name	Gerenciar funções para acesso com escopo	free
create_database / list_databases	project_id, name	Configurações de vários bancos de dados por projeto	free

Custo e limites

O que custa rodar

Cota de API: Limites padrão da API Neon por plano
Tokens por chamada: A maioria das operações é pequena; Escala de resultados SQL com contagem de linhas – sempre LIMIT consultas exploratórias
Monetário: MCP grátis; O nível Neon Free cobre pequenos projetos, planos pagos cobram horas de computação e armazenamento
Dica: As filiais são quase gratuitas até acumularem gravações. A surpresa número 1 em termos de custo são as filiais esquecidas – defina uma política de varredura ou sempre exclua após o uso.

Segurança

Permissões, segredos, alcance

Escopos mínimos: scope API key to a single project when possible

Armazenamento de credenciais: Chave de API no ambiente var NEON_API_KEY

Saída de dados: Chamadas para API console.neon.tech; Tráfego SQL para o endpoint regional do seu projeto

Nunca conceda: org-wide admin keys to long-running agents

run_sql pode sofrer mutação. Para o branch principal prod, prefira criar uma função somente leitura e conectar-se via Postgres MCP.
As ramificações herdam dados do pai no momento da criação – elas contêm todas as PII que o pai contém. Trate-os como sensíveis.

Solução de problemas

Erros comuns e correções

401 Unauthorized

Chave de API inválida ou revogada. Gere um novo em console.neon.tech → Conta → Chaves de API.

Verificar: curl -H 'Authorization: Bearer $NEON_API_KEY' https://console.neon.tech/api/v2/projects

Branch creation fails: 'limit reached'

Você atingiu o limite de agências do seu plano. Exclua ramificações não utilizadas ou atualize.

run_sql times out on a long migration

Instruções de longa duração podem exceder o tempo limite padrão. Use psql com a string de conexão para operações muito longas ou divida a migração.

Connection string works once then fails (compute paused)

A computação de nível gratuito Neon é suspensa automaticamente. A primeira conexão o desperta (inicialização a frio ~1s); conexões subsequentes estão bem. Não trate a latência da primeira chamada como falha.

Alternativas

Neon vs. outros

Alternativa	Quando usar	Troca
Supabase MCP	Você deseja autenticação, funções de borda, armazenamento além do Postgres	Superfície mais pesada; ramificação restrita ao plano Pro
Postgres MCP	Você só precisa de acesso SQL somente leitura e não usa ramificação	Sem gerenciamento de filial/projeto
AWS RDS via aws MCP	Você está no Postgres gerenciado pela AWS (RDS/Aurora)	Sem ramificação; o provisionamento é mais pesado e mais lento

Mais

Recursos

📖 Leia o README oficial no GitHub

🐙 Ver issues abertas

🔍 Ver todos os 400+ servidores MCP e Skills