Neon

Neon MCP Server

Neon MCP Server é uma ferramenta de código aberto que permite interagir com seus bancos de dados Postgres Lakebase na Neon em linguagem natural.

O Model Context Protocol (MCP) é um protocolo padronizado projetado para gerenciar o contexto entre modelos de linguagem de grande porte (LLMs) e sistemas externos. Este repositório fornece um servidor MCP remoto para Neon.

O servidor MCP da Neon atua como uma ponte entre solicitações em linguagem natural e a API da Neon. Construído sobre o MCP, ele traduz suas solicitações nas chamadas de API necessárias, permitindo que você gerencie tarefas como criar projetos e branches, executar consultas e realizar migrações de banco de dados de forma integrada.

Alguns dos principais recursos do servidor MCP da Neon incluem:

• Interação em linguagem natural: Gerencie bancos de dados da Neon usando comandos conversacionais intuitivos.
• Gerenciamento simplificado de banco de dados: Execute ações complexas sem escrever SQL ou usar diretamente a API da Neon.
• Acessibilidade para não desenvolvedores: Capacite usuários com diferentes níveis de conhecimento técnico a interagir com os bancos de dados da Neon.
• Suporte a migração de banco de dados: Aproveite os recursos de branching da Neon para alterações de esquema de banco de dados iniciadas por meio de linguagem natural.

Por exemplo, no Claude Code, ou em qualquer cliente MCP, você pode usar linguagem natural para realizar tarefas com a Neon, como:

• Let's create a new Postgres database, and call it "my-database". Let's then create a table called users with the following columns: id, name, email, and password.
• I want to run a migration on my project called "my-project" that alters the users table to add a new column called "created_at".
• Can you give me a summary of all of my Neon projects and what data is in each one?

[!WARNING]
Considerações de segurança do Neon MCP Server
O Neon MCP Server concede capacidades poderosas de gerenciamento de banco de dados por meio de solicitações em linguagem natural. Sempre revise e autorize as ações solicitadas pelo LLM antes da execução. Garanta que apenas usuários e aplicativos autorizados tenham acesso ao Neon MCP Server.

O Neon MCP Server é destinado apenas ao desenvolvimento local e integrações com IDEs. Não recomendamos usar o Neon MCP Server em ambientes de produção. Ele pode executar operações poderosas que podem levar a alterações acidentais ou não autorizadas.

Para mais informações, consulte Diretrizes de segurança do MCP →.

Configurando o Neon MCP Server

Existem algumas opções para configurar o Neon MCP Server:

1. Configuração rápida com chave de API (Cursor, VS Code e Claude Code): Execute neon@latest init para configurar automaticamente o MCP Server da Neon, habilidades de agente e a extensão do VS Code com um único comando.
2. Servidor MCP remoto (autenticação baseada em OAuth): Conecte-se ao servidor MCP gerenciado da Neon usando OAuth para autenticação. Este método é mais conveniente, pois elimina a necessidade de gerenciar chaves de API. Além disso, você receberá automaticamente os recursos e melhorias mais recentes assim que forem lançados.
3. Servidor MCP remoto (autenticação baseada em chave de API): Conecte-se ao servidor MCP gerenciado da Neon usando chave de API para autenticação. Este método é útil se você quiser conectar um agente remoto à Neon quando o OAuth não estiver disponível. Além disso, você receberá automaticamente os recursos e melhorias mais recentes assim que forem lançados.

Pré-requisitos

• Um aplicativo cliente MCP.
• Uma conta Neon.
• Node.js (>= v18.0.0): Baixe em nodejs.org.
• Se o IP Allow estiver habilitado, adicione 34.192.103.46 e 23.22.233.166 à sua lista de permissões (mcp.neon.tech IPs estáticos).

Para desenvolvimento, você precisará do Node.js 22+ (o pnpm é fornecido via Corepack — execute corepack enable para ativá-lo).

Opção 1. Configuração rápida com chave de API

Não quer criar uma chave de API manualmente?

Execute neon@latest init para configurar automaticamente o MCP Server da Neon com um único comando:

npx neon@latest init

Isso funciona com Cursor, VS Code (GitHub Copilot) e Claude Code. Ele autenticará via OAuth, criará uma chave de API da Neon para você e configurará seu editor automaticamente.

Opção 2. Servidor MCP remoto hospedado (autenticação baseada em OAuth)

Conecte-se ao servidor MCP gerenciado da Neon usando OAuth para autenticação. Esta é a configuração mais fácil, não requer instalação local deste servidor e não precisa de uma chave de API da Neon configurada no cliente.

Execute o seguinte comando para adicionar o Neon MCP Server para todos os agentes e editores detectados no seu workspace:

npx add-mcp https://mcp.neon.tech/mcp

Adicione a flag -g para adicionar o Neon MCP Server à lista global de servidores MCP em vez do escopo do projeto.

Alternativamente, você pode adicionar a seguinte entrada "Neon" ao arquivo de configuração do servidor MCP do seu cliente (por exemplo, mcp.json, mcp_config.json):

{
  "mcpServers": {
    "Neon": {
      "type": "http",
      "url": "https://mcp.neon.tech/mcp"
    }
  }
}

Kiro: Adicione o seguinte ao seu arquivo de configuração MCP do Kiro (~/.kiro/settings/mcp.json para global, ou .kiro/settings/mcp.json para escopo do projeto):

{
  "mcpServers": {
    "Neon": {
      "url": "https://mcp.neon.tech/mcp"
    }
  }
}

Ou use o botão de instalação com um clique no topo deste README. Para mais informações, consulte a documentação MCP do Kiro.

• Reinicie ou atualize seu cliente MCP.
• Uma janela de OAuth será aberta no seu navegador. Siga as instruções para autorizar seu cliente MCP a acessar sua conta Neon.

Com a autenticação baseada em OAuth, o servidor MCP operará, por padrão, em projetos sob sua conta pessoal da Neon. Para acessar ou gerenciar projetos que pertencem a uma organização, você deve fornecer explicitamente o org_id ou o project_id no seu prompt para o cliente MCP.

Opção 3. Servidor MCP remoto hospedado (autenticação baseada em chave de API)

O Servidor MCP remoto também suporta autenticação usando uma chave de API no cabeçalho Authorization se o seu cliente suportar.

Crie uma chave de API da Neon no Console da Neon. Em seguida, execute o seguinte comando para adicionar o Neon MCP Server para todos os agentes e editores detectados no seu workspace:

npx add-mcp https://mcp.neon.tech/mcp --header "Authorization: Bearer <$NEON_API_KEY>"

Alternativamente, você pode adicionar a seguinte entrada "Neon" ao arquivo de configuração do servidor MCP do seu cliente (por exemplo, mcp.json, mcp_config.json):

{
  "mcpServers": {
    "Neon": {
      "type": "http",
      "url": "https://mcp.neon.tech/mcp",
      "headers": {
        "Authorization": "Bearer <$NEON_API_KEY>"
      }
    }
  }
}

Forneça uma chave de API de uma organização para limitar o acesso apenas aos projetos da organização.

Escopos e modo somente leitura

O Neon MCP suporta os escopos OAuth read, write e * (* significa ambos). Seu cliente MCP pode solicitar esses escopos diretamente, ou você pode fazer a seleção na interface de permissões do OAuth.

O modo somente leitura restringe quais ferramentas estão disponíveis, desabilitando operações de escrita, como criar projetos, branches ou executar migrações. As ferramentas somente leitura incluem listar projetos, descrever esquemas, consultar dados e visualizar métricas de desempenho.

Você pode definir o modo somente leitura de duas maneiras:

1. Seleção de escopo OAuth (recomendado): No OAuth, selecione somente leitura desmarcando Acesso total na interface de autorização.
2. Parâmetro de consulta readonly: Adicione ?readonly=true à URL do seu servidor MCP:

{
  "mcpServers": {
    "Neon": {
      "url": "https://mcp.neon.tech/mcp?readonly=true"
    }
  }
}

Como o parâmetro de consulta se comporta:

• Fluxo de chave de API: readonly=true é a forma de habilitar o modo somente leitura (não há troca de escopo OAuth neste fluxo).
• Fluxo OAuth: readonly=true substitui o escopo OAuth. Sem ele, o modo somente leitura é determinado pelo escopo selecionado na interface de consentimento do OAuth.

O cabeçalho HTTP legado x-read-only também é suportado como fallback (prioridade menor que o parâmetro de consulta).

Observação: O modo somente leitura restringe quais ferramentas estão disponíveis. Além disso, a ferramenta run_sql permanece disponível apenas para consultas somente leitura.

Parâmetros de consulta de URL para controle de acesso

O contexto de concessão (categorias de escopo, escopo de projeto, modo somente leitura) é configurado por meio de parâmetros de consulta de URL na URL do servidor MCP. A configuração viaja com cada solicitação e entra em vigor imediatamente — sem necessidade de nova autenticação.

Parâmetro	Descrição	Exemplo
readonly	Habilita o modo somente leitura (true/false)	?readonly=true
category	Restringe a categorias específicas de ferramentas (repetido ou CSV)	?category=querying&category=schema
projectId	Limita todas as operações a um único projeto	?projectId=proj-123

Exemplo de somente leitura + escopo de projeto:

{
  "mcpServers": {
    "Neon": {
      "url": "https://mcp.neon.tech/mcp?readonly=true&projectId=my-project-id"
    }
  }
}

Exemplo com filtro de categoria (apenas ferramentas de consulta e esquema):

{
  "mcpServers": {
    "Neon": {
      "url": "https://mcp.neon.tech/mcp?category=querying&category=schema"
    }
  }
}

Você pode visualizar quais ferramentas estão visíveis para qualquer configuração usando o endpoint /api/list-tools (sem necessidade de autenticação):

curl "https://mcp.neon.tech/api/list-tools?readonly=true&category=querying"

Ferramentas disponíveis no modo somente leitura

• list_projects, list_shared_projects, describe_project, list_organizations
• describe_branch, list_branch_computes, compare_database_schema
• run_sql, run_sql_transaction, get_database_tables, describe_table_schema
• list_slow_queries, explain_sql_statement, inspect_database
• get_connection_string
• get_neon_auth_config
• query_logs, list_log_fields, list_log_field_values
• search, fetch, list_docs_resources, get_doc_resource

Ferramentas que exigem acesso de escrita:

• create_project, delete_project
• create_branch, delete_branch, reset_from_parent
• provision_neon_auth, configure_neon_auth, provision_neon_data_api
• prepare_database_migration, complete_database_migration
• prepare_query_tuning, complete_query_tuning

Transporte Server-Sent Events (SSE) (obsoleto)

O MCP suporta dois transportes de servidor remoto: o obsoleto Server-Sent Events (SSE) e o mais novo e recomendado Streamable HTTP. Se o seu cliente LLM ainda não suporta Streamable HTTP, você pode alternar o endpoint de https://mcp.neon.tech/mcp para https://mcp.neon.tech/sse para usar SSE.

Execute o seguinte comando para adicionar o Neon MCP Server para todos os agentes e editores detectados no seu workspace usando o transporte SSE:

npx add-mcp https://mcp.neon.tech/sse --type sse

Arquitetura do servidor remoto

O servidor remoto é executado como um aplicativo Next.js App Router na Vercel em mcp.neon.tech.

[!NOTE] O caminho raiz / redireciona para a documentação do Neon MCP Server. Não há página de destino.

Principais áreas de implementação:

• app/api/[transport]/route.ts: endpoint de transporte MCP para Streamable HTTP (/mcp) e SSE (/sse)
• app/api/authorize/, app/callback/, app/api/token/, app/api/revoke/: endpoints do fluxo OAuth
• app/.well-known/: endpoints de metadados de descoberta OAuth
• mcp/: servidor MCP, ferramentas, handlers, análises e integração com Sentry
• lib/: helpers compatíveis com Next.js (OAuth, configuração, tratamento de erros)
• mcp/utils/read-only.ts: modo somente leitura e tratamento de escopos

Guias

• Guia do Neon MCP Server
• Conecte clientes MCP à Neon
• Cursor com Neon MCP Server
• Claude Code com Neon MCP Server
• Claude Desktop com Neon MCP Server
• Cline com Neon MCP Server
• Windsurf com Neon MCP Server
• Zed com Neon MCP Server

Recursos

Ferramentas suportadas

O Neon MCP Server fornece as seguintes ações, que são expostas como "ferramentas" para clientes MCP. Você pode usar essas ferramentas para interagir com seus projetos e bancos de dados da Neon usando comandos em linguagem natural.

Metadados de escopo de ferramentas

Cada definição de ferramenta inclui uma categoria scope usada para filtragem de ferramentas baseada em concessão e UX de consentimento. As categorias atuais são:

• projects
• branches
• schema
• querying
• neon_auth
• data_api
• observability
• docs
• null (ferramentas sem categoria de escopo)

Notas:

• compare_database_schema é categorizado sob schema.
• provision_neon_data_api é categorizado sob data_api (separado de neon_auth).
• A aplicação de somente leitura ainda depende de readOnlySafe e da lógica de somente leitura no servidor; scope é metadado de categoria, não um interruptor independente de leitura/gravação.
• No modo com escopo de projeto (?projectId=...), search e fetch não estão disponíveis.

Gerenciamento de Projetos:

• list_projects: Lista os primeiros 10 projetos Neon na sua conta, fornecendo um resumo de cada projeto. Se você não conseguir encontrar um projeto específico, aumente o limite passando um valor maior para o parâmetro limit.
• list_shared_projects: Lista projetos Neon compartilhados com o usuário atual. Suporta um parâmetro de busca e limitação do número de projetos retornados (padrão: 10).
• describe_project: Busca informações detalhadas sobre um projeto Neon específico, incluindo seu ID, nome e branches e bancos de dados associados.
• create_project: Cria um novo projeto Neon na sua conta Neon. Um projeto atua como um contêiner para branches, bancos de dados, roles e computes.
• delete_project: Exclui um projeto Neon existente e todos os seus recursos associados.
• list_organizations: Lista todas as organizações às quais o usuário atual tem acesso. Opcionalmente, filtre por nome ou ID da organização usando o parâmetro de busca.

Gerenciamento de Branches:

• create_branch: Cria uma nova branch dentro de um projeto Neon especificado. Aproveita o recurso de branching do Neon para desenvolvimento, testes ou migrações.
• delete_branch: Exclui uma branch existente de um projeto Neon.
• describe_branch: Recupera detalhes sobre uma branch específica, como nome, ID e branch pai.
• list_branch_computes: Lista endpoints de compute para um projeto ou branch específica, incluindo ID do compute, tipo, tamanho, último horário ativo e informações de autoscaling.
• compare_database_schema: Mostra o diff de schema entre a branch filha e sua branch pai.
• reset_from_parent: Redefine a branch atual para o estado da branch pai, descartando alterações locais. Preserva automaticamente um backup se a branch tiver branches filhas, ou opcionalmente preserva sob solicitação com um nome personalizado.

Execução de Consultas SQL:

• get_connection_string: Retorna sua string de conexão com o banco de dados.
• run_sql: Executa uma única consulta SQL em um banco de dados Neon especificado. Suporta operações de leitura e gravação.
• run_sql_transaction: Executa uma série de consultas SQL em uma única transação em um banco de dados Neon.
• get_database_tables: Lista todas as tabelas em um banco de dados Neon especificado.
• describe_table_schema: Recupera a definição de schema de uma tabela específica, detalhando colunas, tipos de dados e restrições.

Migrações de Banco de Dados (Alterações de Schema):

• prepare_database_migration: Inicia um processo de migração de banco de dados. Criticamente, cria uma branch temporária para aplicar e testar a migração com segurança antes de afetar a branch principal.
• complete_database_migration: Finaliza e aplica uma migração de banco de dados preparada à branch principal. Esta ação mescla alterações da branch de migração temporária e limpa os recursos temporários.

Consultas e Otimização SQL:

• inspect_database: Executa um dos 14 diagnósticos Postgres somente leitura predefinidos em uma branch — tamanhos de relações e índices, uso de index e sequential-scan, consultas e locks ativos, consultas mais pesadas e mais frequentes, taxa de acerto de cache e tamanho do working-set, estimativas de autovacuum e bloat, e estado de replicação. Mesmas verificações do comando CLI neon inspect db. Quatro deles precisam da extensão pg_stat_statements ou neon.
• list_slow_queries: Identifica gargalos de desempenho encontrando as consultas mais lentas em um banco de dados. Requer a extensão pg_stat_statements.
• explain_sql_statement: Fornece planos de execução detalhados para consultas SQL, ajudando a identificar gargalos de desempenho.
• prepare_query_tuning: Analisa o desempenho de consultas e sugere otimizações, como criação de índices. Cria uma branch temporária para testar essas otimizações com segurança.
• complete_query_tuning: Finaliza o ajuste de consultas aplicando otimizações à branch principal ou descartando-as. Limpa a branch temporária de ajuste.

Neon Auth:

• provision_neon_auth: Provisiona o Neon Auth para um projeto Neon. Permite que desenvolvedores configurem facilmente a infraestrutura de autenticação criando uma integração com um provedor de Auth.
• configure_neon_auth: Configura uma integração Neon Auth existente para uma branch — gerenciando origens confiáveis, acesso via localhost, métodos de autenticação, provedores OAuth e o provedor de e-mail transacional.
• get_neon_auth_config: Lê a configuração completa do Neon Auth para uma branch, incluindo metadados de integração e configurações ajustáveis (segredos são ocultados).

Neon Data API:

• provision_neon_data_api: Provisiona a Neon Data API para acesso a banco de dados baseado em HTTP com autenticação JWT opcional via Neon Auth ou provedores JWKS externos.

Busca e Descoberta:

• search: Busca em organizações, projetos e branches que correspondem a uma consulta. Retorna IDs, títulos e links diretos para o Neon Console.
• fetch: Busca informações detalhadas sobre uma organização, projeto ou branch específica usando um ID (normalmente da ferramenta de busca).

Observabilidade: essas ferramentas exigem o Neon Platform Beta e atualmente estão disponíveis apenas para projetos na região aws-us-east-2. Uma branch sem acesso a logs retorna HTTP 404 com o motivo telemetry_not_enabled.

• query_logs: Consulta logs OpenTelemetry emitidos por funções serverless do Neon e outros serviços. Use filtros estruturados para origem, nome do serviço, severidade e janela de tempo, ou logql bruto para seletores de stream e filtros de linha que as entradas estruturadas não conseguem expressar.
• list_log_fields: Lista os campos de log para os quais você pode enumerar valores em uma branch, como service_name, severity_text e scope_name. Use antes de list_log_field_values.
• list_log_field_values: Lista os valores distintos de um campo de log dentro de uma branch e janela de tempo, para descobrir valores concretos para filtros estruturados ou logql bruto.

Documentação e Recursos:

• list_docs_resources: Lista todas as páginas de documentação do Neon disponíveis buscando o índice de https://neon.com/docs/llms.txt. Retorna URLs e títulos de páginas que podem ser buscados individualmente usando a ferramenta get_doc_resource.
• get_doc_resource: Busca uma página específica da documentação do Neon como conteúdo markdown. Use a ferramenta list_docs_resources primeiro para descobrir os slugs de página disponíveis e, em seguida, passe o slug para esta ferramenta.

Migrações

Migrações são uma forma de gerenciar alterações no schema do seu banco de dados ao longo do tempo. Com o servidor MCP do Neon, LLMs têm autonomia para fazer migrações com segurança usando comandos separados "Start" (prepare_database_migration) e "Commit" (complete_database_migration).

O comando "Start" aceita uma migração e a executa em uma nova branch temporária. Ao retornar, este comando indica ao LLM que ele deve testar a migração nesta branch. O LLM pode então executar o comando "Commit" para aplicar a migração à branch original.

Desenvolvimento

Este projeto usa pnpm como gerenciador de pacotes, fixado via Corepack.

Estrutura do Projeto

O código do servidor MCP fica na raiz do repositório, um aplicativo Next.js implantado na Vercel em mcp.neon.tech.

corepack enable
pnpm install

Desenvolvimento Local

# Start the Next.js dev server (for the remote MCP server)
pnpm dev

Linting e Verificação de Tipos

pnpm lint
pnpm typecheck

Variáveis de Ambiente

Necessárias para o runtime do servidor remoto:

Variável	Descrição
SERVER_HOST	URL do servidor (padrão: VERCEL_URL)
UPSTREAM_OAUTH_HOST	URL do provedor OAuth do Neon
CLIENT_ID	ID do cliente OAuth
CLIENT_SECRET	Segredo do cliente OAuth
COOKIE_SECRET	Segredo para cookies assinados
KV_URL	URL do Vercel KV (Upstash Redis)
OAUTH_DATABASE_URL	URL Postgres para armazenamento de tokens

Opcionais:

Variável	Descrição
LOG_LEVEL	Nível de log do Winston: error, warn, info (padrão), debug, verbose, silly

Pirâmide de Testes

Todos os testes são executados a partir da raiz do repositório.

# Unit tests
pnpm test:unit

# Integration tests
pnpm test:integration

# MCP protocol end-to-end tests (real MCP client/server tool calls)
pnpm test:e2e:mcp

# Website end-to-end tests (Playwright; provisions/validates ephemeral DB first)
pnpm test:e2e:web

# Full end-to-end suite
pnpm test:e2e

# Full test pyramid (unit + integration + e2e; used in CI)
pnpm test

Estratégia de testes:

• Prefira E2E para transporte/protocolo e comportamento visível ao usuário.
• Use testes de integração para contratos de ferramentas determinísticos e comportamento de fluxo de trabalho.
• Use testes unitários para lógica pura e casos extremos.
• Evite depender da disponibilidade de terceiros em testes de merge-gating; simule dependências externas nos níveis de integração/unitários.

Implantação

A Vercel implanta o servidor remoto automaticamente a partir da configuração de branch do repositório. Ambientes de preview estão disponíveis para pull requests.