Neon

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

Neon MCP Server

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

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

O MCP server do Neon funciona como uma ponte entre solicitações em linguagem natural e a API do Neon. Desenvolvido com base no MCP, ele traduz suas solicitações nas chamadas de API necessárias, permitindo gerenciar tarefas como criar projetos e branches, executar consultas e realizar migrações de banco de dados com facilidade.

Alguns dos principais recursos do MCP server do Neon incluem:

• Interação em linguagem natural: gerencie bancos de dados Neon usando comandos intuitivos e conversacionais.
• Gerenciamento simplificado de bancos de dados: realize ações complexas sem escrever SQL ou usar diretamente a API do Neon.
• Acessibilidade para pessoas que não são desenvolvedoras: permita que usuários com diferentes níveis de conhecimento técnico interajam com bancos de dados Neon.
• Suporte a migrações de banco de dados: aproveite os recursos de branching do Neon para alterações no esquema do banco de dados iniciadas em linguagem natural.

Por exemplo, no Claude Code ou em qualquer cliente MCP, você pode usar linguagem natural para realizar tarefas no 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 recursos avançados 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. Certifique-se de que somente usuários e aplicativos autorizados tenham acesso ao Neon MCP Server.

O Neon MCP Server destina-se apenas ao desenvolvimento local e a integrações com IDEs. Não recomendamos usar o Neon MCP Server em ambientes de produção. Ele pode executar operações avançadas que podem causar alterações acidentais ou não autorizadas.

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

Configuração do Neon MCP Server

Há 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 do Neon, as agent skills e a extensão do VS Code com um único comando.
2. MCP Server remoto (autenticação baseada em OAuth): conecte-se ao MCP server gerenciado do Neon usando OAuth para autenticação. Esse método é mais conveniente, pois elimina a necessidade de gerenciar chaves de API. Além disso, você receberá automaticamente os recursos e aprimoramentos mais recentes assim que forem lançados.
3. MCP Server remoto (autenticação baseada em chave de API): conecte-se ao MCP server gerenciado do Neon usando uma chave de API para autenticação. Esse método é útil se você quiser conectar um agente remoto ao Neon quando o OAuth não estiver disponível. Além disso, você receberá automaticamente os recursos e aprimoramentos 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 IP Allow estiver ativado, 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+ (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 do Neon com um único comando:

npx neon@latest init

Isso funciona com Cursor, VS Code (GitHub Copilot) e Claude Code. A autenticação será feita via OAuth, uma chave de API do Neon será criada para você e seu editor será configurado automaticamente.

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

Conecte-se ao MCP server gerenciado do Neon usando OAuth para autenticação. Essa é a configuração mais simples, não requer instalação local deste server e não exige que uma chave de API do Neon esteja configurada no cliente.

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

npx add-mcp "https://mcp.neon.tech/mcp?category=projects&category=branches&category=endpoints&category=querying&category=schema"

Esse URL disponibiliza projetos, branches, endpoints de computação, consultas e esquema. Visualize-o com /api/list-tools?category=projects&category=branches&category=endpoints&category=querying&category=schema. O URL sem filtros disponibiliza todas as categorias:

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

Adicione a flag -g para adicionar o Neon MCP Server à lista global de MCP servers, em vez de adicioná-lo ao escopo do projeto.

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

{
  "mcpServers": {
    "Neon": {
      "type": "http",
      "url": "https://mcp.neon.tech/mcp?category=projects&category=branches&category=endpoints&category=querying&category=schema"
    }
  }
}

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

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

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

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

Com a autenticação baseada em OAuth, o MCP server, por padrão, opera em projetos da sua conta pessoal do Neon. Para acessar ou gerenciar projetos pertencentes a uma organização, você deve fornecer explicitamente org_id ou project_id no prompt enviado ao cliente MCP.

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

O MCP Server remoto também oferece suporte à autenticação usando uma chave de API no cabeçalho Authorization, caso seu cliente ofereça suporte a isso.

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

npx add-mcp "https://mcp.neon.tech/mcp?category=projects&category=branches&category=endpoints&category=querying&category=schema" --header "Authorization: Bearer <$NEON_API_KEY>"

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

{
  "mcpServers": {
    "Neon": {
      "type": "http",
      "url": "https://mcp.neon.tech/mcp?category=projects&category=branches&category=endpoints&category=querying&category=schema",
      "headers": {
        "Authorization": "Bearer <$NEON_API_KEY>"
      }
    }
  }
}

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

Escopos e modo somente leitura

O Neon MCP anuncia os escopos OAuth read e write. Seu cliente MCP pode solicitá-los, ou você pode fazer a seleção na interface de permissões do OAuth. * é tratado como gravação se um cliente ainda o enviar.

O modo somente leitura restringe as ferramentas disponíveis, desativando operações de gravação, como criar projetos e 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. URL MCP padrão (consentimento editável): conecte-se usando https://mcp.neon.tech/mcp e desmarque Permitir gravações na página de autorização. Você também pode escolher um projeto, uma função Postgres para SQL e um subconjunto de categorias de ferramentas nessa página.
2. URL MCP parametrizado (consentimento fixo): inclua readonly, projectId, category e/ou roleName no URL do MCP server. A página de autorização confirma essa concessão e não oferece opções de edição. Altere o URL e autorize novamente para mudar a concessão.

{
  "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 ativar o modo somente leitura (não há troca de escopo OAuth nesse fluxo). As alterações no URL são aplicadas na próxima solicitação.
• Fluxo OAuth: projectId, category, readonly e roleName no URL do MCP definem uma concessão fixa, confirmada durante a autorização. readonly=true não pode ser ampliado para permitir gravações nessa página. Depois que um token é emitido, alterar o URL não amplia as permissões desse token; autorize novamente.

Para o registro OAuth, x-read-only é um valor inicial padrão para Permitir gravações no consentimento editável. Ele não bloqueia a confirmação nem reduz as permissões de um URL parametrizado que inclua readonly=false. As solicitações com chave de API ainda respeitam x-read-only em cada solicitação, abaixo do parâmetro de consulta readonly.

Observação: o modo somente leitura restringe quais ferramentas estão disponíveis. run_sql continua disponível e executa cada consulta em uma transação READ ONLY. run_sql_transaction não está disponível; execute cada instrução com run_sql. Essas chamadas são executadas separadamente e não compartilham uma transação. Para obter semântica transacional, use uma conexão com gravações permitidas.

Parâmetros de consulta do URL para controle de acesso

O contexto de concessão (categorias de escopo, escopo do projeto, modo somente leitura, função Postgres fixada) é configurado por meio de parâmetros de consulta no URL do MCP server. As solicitações com chave de API aplicam esses parâmetros em cada solicitação. Os tokens OAuth armazenam a concessão confirmada ou editada durante a autorização.

Parâmetro	Descrição	Exemplo
readonly	Ativa o modo somente leitura (true/false)	?readonly=true
category	Restringe a categorias específicas de ferramentas (repetidas ou CSV)	?category=querying&category=schema
projectId	Restringe todas as operações a um único projeto	?projectId=proj-123
roleName	Executa todo o SQL como esta função Postgres, em vez de como o proprietário	?roleName=app_reader

Exemplo de modo somente leitura com escopo de projeto:

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

Exemplo com filtro de categorias (somente ferramentas de consulta e esquema):

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

Exemplo de função Postgres fixada (somente leitura, um projeto, SQL como app_reader):

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

roleName fixa a função de login do Postgres para toda a conexão. Todo o SQL que o server executa para você (run_sql, run_sql_transaction, explain_sql_statement, get_database_tables, describe_table_schema, describe_branch, list_slow_queries, inspect_database e o SQL dentro de migrações e ajuste de consultas) faz login como essa função, portanto as permissões do Postgres determinam o que o agente pode ler ou alterar. Sem esse parâmetro, o SQL é executado como o proprietário do banco de dados. O modo somente leitura ainda envolve as consultas em uma transação READ ONLY; a função fixada acrescenta uma restrição aplicada pelo próprio Postgres ao login, de modo que o SQL que sair da transação ainda terá apenas os privilégios dessa função.

• O servidor resolve internamente as credenciais da função e nunca as retorna. get_connection_string não está disponível em uma conexão fixada.
• Um argumento de ferramenta role_name diferente da função fixada é rejeitado. Se omitido, usa a função fixada, nunca o proprietário.
• Se a função não existir ou não puder fazer login (por exemplo, ALTER ROLE … NOLOGIN), a chamada falha antes de qualquer execução de SQL. Ela não tenta novamente com outra função.
• O valor deve ser um nome exato de função do Postgres: letras, dígitos, _ ou $, começando com uma letra ou _, com no máximo 63 caracteres. Qualquer outra coisa (vazio, repetido, entre aspas, com hífen) é rejeitada com 400, não ignorada.
• A função deve poder fazer login (LOGIN) e existir em cada branch consultado. Funções criadas em SQL (CREATE ROLE app_reader LOGIN PASSWORD '…') funcionam, assim como as criadas no Neon Console ou na API. Uma função com os privilégios necessários, e nada além deles, é o que torna a fixação útil: para agentes somente leitura, conceda SELECT nas tabelas que eles devem ver e não adicione isso a neon_superuser. create_postgres_role com access: "read_only" cria essa função a partir de uma conexão sem roleName; as funções que ele cria sem access são adicionadas a neon_superuser.
• OAuth: roleName na URL do MCP fixa uma concessão. A página de autorização mostra a função, e o token emitido a mantém durante a renovação. Alterar a URL posteriormente não altera o token; autorize novamente. Com a URL padrão (consentimento editável), informe a função no campo opcional Postgres role; deixe-o vazio para manter o proprietário do banco de dados. Os tokens emitidos antes dessa opção não têm uma função fixada e continuam funcionando como antes.
• Chave de API: a função é lida da URL em cada solicitação. Qualquer pessoa que possa editar a URL de conexão e tenha a chave de API pode alterá-la ou removê-la; portanto, mantenha a URL em uma configuração que o agente não controle.
• A fixação se aplica somente às conexões SQL. As ferramentas da API de gerenciamento continuam agindo com o acesso próprio da chave de API ou do token OAuth; compare_database_schema, por exemplo, é calculado pela API Neon e não é limitado pelas concessões da função. Combine roleName com readonly=true e category para limitar também essas ferramentas.

Você pode visualizar quais ferramentas ficam disponíveis para qualquer configuração usando o endpoint /api/list-tools (não requer autenticação):

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

Ferramentas disponíveis no modo somente leitura

Ferramentas personalizadas: list_organizations, describe_branch, run_sql, get_database_tables, describe_table_schema, list_slow_queries, explain_sql_statement, inspect_database, get_neon_auth_config, search, fetch, search_docs, get_doc, send_feedback, list_incidents.

Ferramentas geradas da API de gerenciamento que são GET e não retornam segredos, além de query_logs (POST, somente leitura). Visualize o conjunto exato com /api/list-tools?readonly=true.

Ferramentas que exigem acesso de gravação:

• Gravações geradas da API de gerenciamento (create_project, create_branch, delete_project, …)
• get_connection_string (a string de conexão contém a senha de uma função privilegiada, por isso é omitida no modo somente leitura; copie-a do Neon Console em vez disso)
• run_sql_transaction (suas instruções são executadas em uma única sessão, portanto uma instrução COMMIT ou SET TRANSACTION READ WRITE encerraria a transação somente leitura)
• prepare_database_migration, complete_database_migration
• prepare_query_tuning, complete_query_tuning

Compatibilidade de transporte

https://mcp.neon.tech/mcp usa HTTP Streamable sem estado. Ele oferece suporte ao protocolo MCP 2026-07-28 e a uma alternativa sem estado para clientes da era de 2025. Os endpoints HTTP+SSE /sse e /message, obsoletos, retornam 410 Gone.

Conecte clientes HTTP Streamable a https://mcp.neon.tech/mcp. Para clientes que oferecem suporte apenas a servidores stdio locais, adicione isto à configuração do cliente para que mcp-remote faça a ponte para HTTP Streamable:

{
  "mcpServers": {
    "Neon": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.neon.tech/mcp"]
    }
  }
}

Uma solicitação com um cabeçalho Origin malformado recebe 403 Forbidden. Qualquer origem serializada é aceita, incluindo páginas da Web, extensões de navegador, webviews de desktop e null, para que clientes baseados em navegador possam se conectar. Solicitações sem um Origin não são afetadas.

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

Áreas principais da implementação:

• app/api/[transport]/route.ts: endpoint HTTP Streamable sem estado (/mcp)
• 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/: auxiliares 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
• Conectar clientes MCP ao 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 compatíveis

O Neon MCP Server oferece as seguintes ações, expostas como “ferramentas” para clientes MCP. Você pode usar essas ferramentas para interagir com seus projetos e bancos de dados Neon usando comandos em linguagem natural.

Metadados de escopo das ferramentas

Cada definição de ferramenta inclui uma categoria scope usada para filtragem de ferramentas baseada em concessões e para a experiência de consentimento. As categorias atuais são:

• projects
• branches
• endpoints
• snapshots
• schema
• querying
• neon_auth
• data_api
• observability
• docs
• functions
• storage
• realtime
• null (ferramentas sem categoria de escopo: search, fetch, send_feedback)

Observações:

• As ferramentas da API de gerenciamento vêm de @neon/tools. Os seletores são caminhos do SDK (projects.list); os nomes MCP publicados seguem a ordem verbo-primeiro (list_projects, delete_project, query_logs). Os nomes históricos permanecem onde já existiam (describe_project, create_branch, reset_from_parent, compare_database_schema, provision_neon_auth, provision_neon_data_api, list_branch_computes).
• ?category=branches inclui ferramentas de branch, função e banco de dados (list_postgres_roles, create_postgres_database, …). Um token já emitido para branches passa a ter acesso a essas gravações. A listagem de computação é ?category=endpoints. A restauração de snapshot é ?category=snapshots.
• As gravações de membros e permissões do projeto não são publicadas. list_project_members e list_project_permissions são operações de leitura.
• As ferramentas de esquema (?category=schema) são get_database_tables e describe_table_schema, além de compare_database_schema gerada.
• A aplicação do modo somente leitura ainda depende de readOnlySafe e da lógica de somente leitura no servidor; scope são metadados de categoria, não um controle independente de leitura/gravação.
• No modo com escopo de projeto (?projectId=...), as ferramentas sem um caminho de projeto (list_projects, count_projects, create_project, get_project_consumption, get_branch_consumption, list_organizations, list_regions, search, fetch, …) ficam ocultas. delete_project também fica oculta.

Gerenciamento de projetos:

• list_projects: Lista os projetos Neon. limit limita o número de itens retornados.
• count_projects: Retorna o número de projetos ativos em uma organização. org_id é opcional e é resolvido da mesma forma que em list_projects.
• describe_project: Busca um projeto Neon pelo ID ({ "project_id": "…" }).
• get_project_consumption, get_branch_consumption: Métricas de consumo por projeto ou branch, agrupadas por período de cobrança. Aceitam org_id, metrics, from, to e granularity, e exigem um plano Launch, Scale, Agent, Business ou Enterprise. get_branch_consumption também exige project_ids, rejeita as métricas extra_branches_month e snapshot_storage_bytes_month, e não está disponível no plano Business. O endpoint do plano legado /consumption_history/projects não é publicado.
• create_project: Cria um projeto Neon e aguarda a computação padrão. Não retorna uma string de conexão. Os argumentos são { "name": "…", "org_id": "…", "region_id": "…" }. Chame get_connection_string após a conclusão bem-sucedida.
• delete_project: Exclui um projeto Neon existente. Os argumentos são { "project_id": "…" }.
• 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 pesquisa.

Gerenciamento de branches:

• list_branches: Lista as branches de um projeto. Use-a para resolver o nome de uma branch para um ID br-….
• list_credentials, create_credential, revoke_credential, rotate_credential: Credenciais com escopo de branch para Object Storage e AI Gateway. reveal não é uma ferramenta; a rotação substitui os segredos no lugar e não é idempotente.
• create_branch: Cria uma branch com uma computação de leitura e gravação e aguarda até que esteja pronta. Não retorna uma string de conexão. Os argumentos são { "project_id": "…", "name": "feature-x" }. Passe no_compute: true para ignorar o endpoint. Chame get_connection_string após a conclusão bem-sucedida.
• reset_from_parent: Redefine uma branch para o HEAD atual da branch pai ({ "project_id": "…", "branch_id": "br-…" }). Descarta as gravações feitas desde que a branch divergiu. preserve_under_name é obrigatório quando a branch tem branches filhas; essas branches filhas passam para a nova branch. Somente o HEAD da branch pai; a restauração para um ponto no tempo é restore_snapshot.
• delete_branch: Exclui uma branch ({ "project_id": "…", "branch_id": "br-…" }).
• describe_branch: Recupera uma árvore de bancos de dados, esquemas, tabelas, views e funções em uma branch.
• As ferramentas de branch geradas recebem branch_id como ID de branch (br-...), não como nome.
• restore_snapshot: Restaura um snapshot. Passe target_branch_id para restaurar em uma branch existente; omita-o para criar uma nova.

Endpoints de computação (?category=endpoints):

• list_postgres_endpoints, list_branch_computes, get_postgres_endpoint, create_postgres_endpoint, update_postgres_endpoint, delete_postgres_endpoint, start_postgres_endpoint, suspend_postgres_endpoint, restart_postgres_endpoint

Snapshots (?category=snapshots):

• list_snapshots, get_snapshot_schedule, set_snapshot_schedule, create_snapshot, update_snapshot, delete_snapshot, restore_snapshot

Esquema (?category=schema):

• get_database_tables, describe_table_schema
• compare_database_schema: Diferença de esquema SQL de um banco de dados em relação a outro branch. database_name é obrigatório. Se base_branch_id for omitido, a comparação será feita com a branch pai. Os parâmetros opcionais lsn, timestamp, base_lsn, base_timestamp são válidos apenas para pontos no tempo.

Execução de consultas SQL:

• get_connection_string: Retorna a string de conexão do seu banco de dados.
• run_sql: Executa uma única consulta SQL em um banco de dados Neon especificado. Oferece suporte a operações de leitura e gravação. O parâmetro opcional role_name faz login como essa função do Postgres em vez de como o proprietário do banco de dados, e compute_id seleciona o compute; as credenciais permanecem no servidor. Em uma conexão com ?roleName=, role_name deve ser omitido ou corresponder a ele. Retorna a matriz de linhas com no máximo max_rows linhas (100 por padrão, até 10.000); quando as linhas são truncadas, um segundo bloco de conteúdo contém { totalRowCount, truncated, note }. Uma consulta com falha retorna o SQLSTATE do Postgres, a posição do erro e quaisquer detalhes, dicas ou contexto.
• run_sql_transaction: Executa uma série de consultas SQL em uma única transação em um banco de dados Neon. Aceita os mesmos parâmetros opcionais role_name, compute_id e max_rows que run_sql. max_rows se aplica a cada instrução; quando alguma instrução é truncada, o segundo bloco contém um resumo por instrução.
• get_database_tables: Lista todas as tabelas de um banco de dados Neon especificado.
• describe_table_schema: Recupera a definição do esquema de uma tabela específica, detalhando colunas, tipos de dados e restrições.

Migrações de banco de dados (alterações de esquema):

• prepare_database_migration: Inicia um processo de migração de banco de dados. É importante destacar que ele cria uma ramificação temporária para aplicar e testar a migração com segurança antes de afetar a ramificação principal.
• complete_database_migration: Finaliza e aplica uma migração de banco de dados preparada à ramificação principal. Essa ação mescla as alterações da ramificação temporária de migração e limpa os recursos temporários.

Consultas e otimização SQL:

• inspect_database: Executa um dos 15 diagnósticos predefinidos e somente leitura do Postgres em uma ramificação — tamanhos de relações e índices, uso de índices e varreduras sequenciais, consultas e bloqueios ativos, consultas mais pesadas e frequentes, taxa de acerto do cache e tamanho do conjunto de trabalho, estimativas de autovacuum e bloat, e estado da replicação. São as mesmas verificações do comando CLI neon inspect db. Omita database_name para abranger todos os bancos de dados da ramificação; informe um nome para inspecionar um deles. Quatro diagnósticos 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 para ajudar a identificar gargalos de desempenho.
• prepare_query_tuning: Analisa o desempenho das consultas e sugere otimizações, como a criação de índices. Cria uma ramificação temporária para testar essas otimizações com segurança.
• complete_query_tuning: Finaliza o ajuste de consultas aplicando as otimizações à ramificação principal ou descartando-as. Limpa a ramificação temporária de ajuste.

Neon Auth (?category=neon_auth):

• provision_neon_auth, get_auth, disable_auth, update_auth_config
• get_neon_auth_config: Segredos redigidos. Lê origens confiáveis, acesso a localhost, e-mail e senha, provedores OAuth, o provedor de e-mail, a organização, os plugins de link mágico e número de telefone, o webhook e a exportação de logs.
• update_auth_allow_localhost, update_auth_email_and_password, update_auth_email_provider, send_auth_test_email, update_auth_plugins_organization, update_auth_plugins_magic_link, update_auth_plugins_phone_number, update_auth_webhooks, update_auth_logs_export: Altera essas configurações. update_auth_webhooks substitui toda a configuração do webhook. update_auth_logs_export ativa ou desativa a exportação de eventos do Neon Auth para os logs do Neon Platform; um projeto sem exportação de logs aceita apenas enabled: false.
• list_auth_oauth_providers, add_auth_oauth_provider, update_auth_oauth_provider, delete_auth_oauth_provider
• get_auth_oauth_server, update_auth_oauth_server: Configura o Neon Auth como servidor de autorização OAuth 2.1 (inclusive para servidores MCP). É separado dos provedores de login social acima.
• list_auth_oauth_clients, get_auth_oauth_client, create_auth_oauth_client, update_auth_oauth_client, delete_auth_oauth_client, rotate_auth_oauth_client_secret: Gerencia os clientes OAuth desse servidor. create_auth_oauth_client e rotate_auth_oauth_client_secret retornam o client_secret uma única vez.
• list_auth_trusted_domains, add_auth_trusted_domain, delete_auth_trusted_domain
• create_auth_user, delete_auth_user, update_auth_user_role

Neon Data API (?category=data_api):

• provision_neon_data_api, get_data_api, update_data_api, delete_data_api: Gerencia a Data API de um banco de dados da ramificação.

Pesquisa e descoberta:

• search: Pesquisa organizações, projetos e ramificações que correspondam 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 ramificação específica usando um ID (normalmente obtido pela ferramenta de pesquisa).

Feedback (sempre disponível, inclusive no endpoint ?category=docs sem login):

• send_feedback: Envia feedback anônimo à equipe Neon. Somente o texto do feedback é enviado, sem dados da conta, do projeto ou da conexão. As mensagens têm limite de 10.000 caracteres.

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

• query_logs: Consulta logs do OpenTelemetry de uma ramificação. Usa POST na Management API; este servidor a trata como somente leitura.
• query_loki_logs: Executa uma consulta de intervalo LogQL na API de leitura compatível com Loki da ramificação e retorna a resposta do Loki: linhas agrupadas por rótulos de fluxo, com registros de data e hora em nanossegundos.
• list_log_fields: Lista os campos de log cujos valores podem ser enumerados em uma ramificação.
• list_log_field_values: Lista os valores distintos de um campo de log em uma ramificação e intervalo de tempo.

Documentação e recursos (?category=docs):

• search_docs: Pesquisa em neon.com (documentação, referência da API, tutorial de PostgreSQL, guias, perguntas frequentes, changelog e blog) usando a mesma pesquisa da caixa de pesquisa de neon.com. Aceita query, categories opcional (docs, api, postgresql, guides, faqs, blog, changelog) e limit opcional (1-40, padrão 10). Retorna páginas classificadas com title, url, slug, category, breadcrumb, heading e excerpt; passe slug para get_doc para ler a página.
• get_doc: Busca uma página de neon.com em formato Markdown. Aceita slug de um resultado de search_docs (por exemplo, docs/guides/prisma ou postgresql/tutorial/inner-join).

Funções (?category=functions):

• list_functions, get_function, update_function, delete_function, deploy_function
• list_functions_custom_domains, register_functions_custom_domain, delete_functions_custom_domain
• list_triggers, get_trigger, create_trigger, update_trigger, delete_trigger: Gatilhos de função agendados (type: "schedule", cron UTC de cinco campos).

Armazenamento (?category=storage):

• list_storage_buckets, create_storage_bucket, delete_storage_bucket
• list_storage_objects, delete_storage_object, delete_storage_objects_by_prefix
• presign_storage_object, get_storage

Tempo real (?category=realtime):

• get_realtime, enable_realtime, disable_realtime: Estado do Realtime da ramificação, ativação (com allowed_origins opcional) e desativação. A ativação e a desativação aguardam até que a alteração seja aplicada.
• get_realtime_secret: O segredo compartilhado com o qual o backend do aplicativo emite tokens do Realtime. Não disponível no modo somente leitura.
• rotate_realtime_secret: Substitui o segredo compartilhado e aguarda até que a alteração seja aplicada. Não é idempotente. Depois, chame get_realtime_secret para obter o novo valor.

Migrações

As migrações são uma forma de gerenciar alterações no esquema do banco de dados ao longo do tempo. Com o servidor MCP Neon, os LLMs podem executar migrações com segurança usando comandos separados de "Iniciar" (prepare_database_migration) e "Confirmar" (complete_database_migration).

O comando "Iniciar" aceita uma migração e a executa em uma nova ramificação temporária. Ao retornar, esse comando indica ao LLM que ele deve testar a migração nessa ramificação. Em seguida, o LLM pode executar o comando "Confirmar" para aplicar a migração à ramificação 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, em um aplicativo Next.js implantado no Vercel em mcp.neon.tech.

corepack enable
pnpm install

Consulte CONTRIBUTING.md para saber como adicionar ferramentas. Os argumentos das ferramentas são snake_case.

Desenvolvimento local

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

Lint e verificação de tipos

pnpm lint
pnpm typecheck

Variáveis de ambiente

Obrigatórias para a execução do servidor remoto:

Variável	Descrição
SERVER_HOST	URL do servidor (o 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
KV_URL	URL do Upstash Redis (bloqueio transitório)
OAUTH_DATABASE_URL	URL do 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
NEON_MCP_DISABLE_ANALYTICS	Defina como 1 para desativar a análise de produto

Pirâmide de testes

Todos os testes são executados na 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 testes E2E para transporte/protocolo e comportamento visível ao usuário.
• Use testes de integração para contratos determinísticos de ferramentas e comportamento de fluxos de trabalho.
• Use testes unitários para lógica pura e casos extremos.
• Evite depender da disponibilidade de terceiros em testes que bloqueiam mesclagens; simule dependências externas nas camadas de integração/unitárias.

Implantação

O Vercel implanta automaticamente o servidor remoto com base na configuração da ramificação do repositório. Ambientes de pré-visualização estão disponíveis para pull requests.

Telemetria

O servidor MCP Neon coleta análises de produto e relatórios de erros para nos ajudar a entender o uso e melhorar a confiabilidade:

• Análise de produto (Segment): quando você se conecta com uma conta autenticada, o servidor envia um evento identify com o ID, o nome e o endereço de e-mail da sua conta Neon. Também registra o início da sessão (server_init), cada chamada de ferramenta (tool_call) e erros inesperados do servidor (server_error). Um evento de chamada de ferramenta inclui o nome da ferramenta, o método de autenticação e o cliente, mas não os argumentos da ferramenta nem os resultados das consultas. As chamadas de ferramentas exclusivas de documentação, sem uma conta, são registradas anonimamente. A página exibida após a autorização informa que foi mostrada (auth_complete_viewed, com o resultado e o cliente) e quais botões e links foram usados (auth_complete_action); o navegador envia apenas um ID aleatório de visualização da página, nunca o código de autorização nem sua identidade. Os eventos são enviados para track.neon.tech, o endpoint de análise próprio da Neon.
• Relatórios de erros, rastreamentos e logs (Sentry): erros inesperados do servidor são relatados com rastreamentos de pilha e o método e o caminho da solicitação. Cabeçalhos, corpos, cookies e strings de consulta das solicitações não são enviados. Cada solicitação e chamada de ferramenta é rastreada com o nome da ferramenta, o nome do cliente, o ID da conta e a indicação de falha da chamada, além do ID de sessão atribuído pelo servidor a clientes da geração de 2025 e do ID de conversa enviado pelo cliente em _meta.threadId. Os rastreamentos não incluem argumentos nem resultados das ferramentas. Os logs do servidor também são enviados ao Sentry. Esta coleção é abrangida pela Política de Privacidade da Neon. Para desativar a análise de dados ao executar o servidor por conta própria, defina NEON_MCP_DISABLE_ANALYTICS=1. Essa opção não desativa o Sentry.