Neon

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

Neon MCP Server

Neon MCP Server est un outil open source qui vous permet d’interagir avec vos bases de données Lakebase Postgres sur Neon en langage naturel.

Le Model Context Protocol (MCP) est un protocole standardisé conçu pour gérer le contexte entre les grands modèles de langage (LLM) et les systèmes externes. Ce dépôt fournit un serveur MCP distant pour Neon.

Le serveur MCP de Neon fait le lien entre les requêtes en langage naturel et l’API Neon. Basé sur MCP, il traduit vos requêtes en appels API nécessaires, ce qui vous permet de gérer facilement des tâches telles que la création de projets et de branches, l’exécution de requêtes et les migrations de bases de données.

Voici quelques-unes des principales fonctionnalités du serveur MCP de Neon :

• Interaction en langage naturel : gérez les bases de données Neon à l’aide de commandes intuitives et conversationnelles.
• Gestion simplifiée des bases de données : effectuez des opérations complexes sans écrire de SQL ni utiliser directement l’API Neon.
• Accessibilité pour les non-développeurs : permettez aux utilisateurs ayant des profils techniques variés d’interagir avec les bases de données Neon.
• Prise en charge des migrations de bases de données : exploitez les capacités de branchement de Neon pour modifier le schéma d’une base de données à l’aide de requêtes en langage naturel.

Par exemple, dans Claude Code ou tout client MCP, vous pouvez utiliser le langage naturel pour effectuer des opérations avec Neon, telles que :

• 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]
Considérations de sécurité concernant Neon MCP Server
Neon MCP Server offre de puissantes fonctionnalités de gestion des bases de données via des requêtes en langage naturel. Vérifiez et autorisez toujours les actions demandées par le LLM avant leur exécution. Assurez-vous que seuls les utilisateurs et applications autorisés ont accès à Neon MCP Server.

Neon MCP Server est destiné uniquement au développement local et aux intégrations dans les IDE. Nous déconseillons d’utiliser Neon MCP Server dans des environnements de production. Il peut exécuter des opérations puissantes susceptibles d’entraîner des modifications accidentelles ou non autorisées.

Pour en savoir plus, consultez les recommandations de sécurité MCP →.

Configuration de Neon MCP Server

Plusieurs options permettent de configurer Neon MCP Server :

1. Configuration rapide avec une clé API (Cursor, VS Code et Claude Code) : exécutez neon@latest init pour configurer automatiquement Neon MCP Server, les compétences d’agent et l’extension VS Code à l’aide d’une seule commande.
2. Serveur MCP distant (authentification OAuth) : connectez-vous au serveur MCP géré par Neon en utilisant OAuth pour l’authentification. Cette méthode est plus pratique, car elle évite d’avoir à gérer des clés API. Vous recevrez également automatiquement les dernières fonctionnalités et améliorations dès leur publication.
3. Serveur MCP distant (authentification par clé API) : connectez-vous au serveur MCP géré par Neon en utilisant une clé API pour l’authentification. Cette méthode est utile si vous souhaitez connecter à Neon un agent distant pour lequel OAuth n’est pas disponible. Vous recevrez également automatiquement les dernières fonctionnalités et améliorations dès leur publication.

Prérequis

• Une application cliente MCP.
• Un compte Neon.
• Node.js (>= v18.0.0) : téléchargez-le depuis nodejs.org.
• Si IP Allow est activé, ajoutez 34.192.103.46 et 23.22.233.166 à votre liste d’autorisation (mcp.neon.tech adresses IP statiques).

Pour le développement, vous aurez besoin de Node.js 22+ (pnpm est fourni via Corepack — exécutez corepack enable pour l’activer).

Option 1. Configuration rapide avec une clé API

Vous ne souhaitez pas créer manuellement une clé API ?

Exécutez neon@latest init pour configurer automatiquement Neon MCP Server à l’aide d’une seule commande :

npx neon@latest init

Cette méthode fonctionne avec Cursor, VS Code (GitHub Copilot) et Claude Code. Elle vous authentifiera via OAuth, créera une clé API Neon pour vous et configurera automatiquement votre éditeur.

Option 2. Serveur MCP distant hébergé (authentification OAuth)

Connectez-vous au serveur MCP géré par Neon en utilisant OAuth pour l’authentification. C’est la configuration la plus simple : aucune installation locale de ce serveur n’est nécessaire et aucune clé API Neon ne doit être configurée dans le client.

Exécutez la commande suivante pour ajouter Neon MCP Server à tous les agents et éditeurs détectés dans votre espace de travail :

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

Cette URL publie les projets, les branches, les points de terminaison de calcul, les requêtes et le schéma. Prévisualisez-la avec /api/list-tools?category=projects&category=branches&category=endpoints&category=querying&category=schema. L’URL sans filtre publie toutes les catégories :

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

Ajoutez l’indicateur -g pour ajouter Neon MCP Server à la liste globale des serveurs MCP plutôt qu’à celle du projet.

Vous pouvez également ajouter l’entrée « Neon » suivante au fichier de configuration des serveurs MCP de votre client (par exemple, 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 : ajoutez ce qui suit au fichier de configuration MCP de Kiro (~/.kiro/settings/mcp.json pour la configuration globale ou .kiro/settings/mcp.json pour celle du projet) :

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

Vous pouvez aussi utiliser le bouton d’installation en un clic en haut de ce README. Pour en savoir plus, consultez la documentation MCP de Kiro.

• Redémarrez ou actualisez votre client MCP.
• Une fenêtre OAuth s’ouvrira dans votre navigateur. Suivez les instructions pour autoriser votre client MCP à accéder à votre compte Neon.

Avec l’authentification OAuth, le serveur MCP fonctionne par défaut sur les projets de votre compte Neon personnel. Pour accéder aux projets appartenant à une organisation ou les gérer, vous devez indiquer explicitement soit org_id, soit project_id dans votre requête au client MCP.

Option 3. Serveur MCP distant hébergé (authentification par clé API)

Le serveur MCP distant prend également en charge l’authentification à l’aide d’une clé API dans l’en-tête Authorization, si votre client le permet.

Créez une clé API Neon dans la console Neon. Ensuite, exécutez la commande suivante pour ajouter Neon MCP Server à tous les agents et éditeurs détectés dans votre espace de travail :

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

Vous pouvez également ajouter l’entrée « Neon » suivante au fichier de configuration des serveurs MCP de votre client (par exemple, 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>"
      }
    }
  }
}

Fournissez une clé API d’organisation pour limiter l’accès aux seuls projets de cette organisation.

Portées et mode lecture seule

Neon MCP annonce les portées OAuth read et write. Votre client MCP peut les demander, ou vous pouvez les sélectionner dans l’interface des autorisations OAuth. * est considéré comme une autorisation d’écriture si un client l’envoie encore.

Le mode lecture seule limite les outils disponibles et désactive les opérations d’écriture, comme la création de projets ou de branches, ou l’exécution de migrations. Les outils en lecture seule comprennent la liste des projets, la description des schémas, l’interrogation des données et l’affichage des métriques de performance.

Vous pouvez activer le mode lecture seule de deux façons :

1. URL MCP par défaut (consentement modifiable) : connectez-vous avec https://mcp.neon.tech/mcp et décochez Autoriser les écritures sur la page d’autorisation. Vous pouvez également y choisir un projet, un rôle Postgres pour SQL et un sous-ensemble de catégories d’outils.
2. URL MCP paramétrée (consentement fixe) : ajoutez readonly, projectId, category et/ou roleName à l’URL du serveur MCP. La page d’autorisation confirme cette autorisation et ne propose pas de paramètres modifiables. Pour modifier l’autorisation, changez l’URL et autorisez à nouveau.

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

Comportement du paramètre de requête :

• Flux avec clé API : readonly=true permet d’activer le mode lecture seule (ce flux ne comporte pas d’échange de portée OAuth). Les modifications de l’URL s’appliquent à la requête suivante.
• Flux OAuth : projectId, category, readonly et roleName dans l’URL MCP définissent une autorisation fixe, confirmée lors de l’autorisation. readonly=true ne peut pas être étendu aux écritures sur cette page. Une fois le jeton émis, modifier l’URL n’élargit pas les autorisations de ce jeton ; autorisez à nouveau.

Pour l’enregistrement OAuth, x-read-only définit par défaut l’autorisation d’écriture sur la page de consentement modifiable. Cela ne verrouille pas la confirmation et ne réduit pas les autorisations d’une URL paramétrée qui inclut readonly=false. Les requêtes avec clé API respectent toujours x-read-only pour chaque requête, en complément du paramètre de requête readonly.

Remarque : le mode lecture seule limite les outils disponibles. run_sql reste disponible et exécute chaque requête dans une transaction READ ONLY. run_sql_transaction n’est pas disponible ; exécutez chaque instruction avec run_sql. Ces appels s’exécutent séparément et ne partagent pas de transaction. Pour bénéficier de la sémantique transactionnelle, utilisez une connexion autorisant les écritures.

Paramètres d’URL pour le contrôle d’accès

Le contexte d’autorisation (catégories de portée, restriction à un projet, mode lecture seule, rôle Postgres épinglé) est configuré à l’aide des paramètres de requête de l’URL du serveur MCP. Les requêtes avec clé API appliquent ces paramètres à chaque requête. Les jetons OAuth enregistrent l’autorisation confirmée ou modifiée lors de l’autorisation.

Paramètre	Description	Exemple
readonly	Activer le mode lecture seule (true/false)	?readonly=true
category	Limiter à des catégories d’outils spécifiques (répétées ou séparées par des virgules)	?category=querying&category=schema
projectId	Limiter toutes les opérations à un seul projet	?projectId=proj-123
roleName	Exécuter tout le SQL avec ce rôle Postgres plutôt qu’avec celui du propriétaire	?roleName=app_reader

Exemple en lecture seule et limité à un projet :

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

Exemple avec filtrage par catégorie (outils de requête et de schéma uniquement) :

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

Exemple avec rôle Postgres épinglé (lecture seule, un projet, SQL exécuté en tant que app_reader) :

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

roleName épingle le rôle de connexion Postgres pour toute la connexion. Toutes les requêtes SQL exécutées par le serveur pour vous (run_sql, run_sql_transaction, explain_sql_statement, get_database_tables, describe_table_schema, describe_branch, list_slow_queries, inspect_database, ainsi que le SQL des migrations et de l’optimisation des requêtes) se connectent avec ce rôle. Les privilèges Postgres déterminent donc ce que l’agent peut lire ou modifier. Sans ce paramètre, le SQL s’exécute en tant que propriétaire de la base de données. Le mode lecture seule continue d’encapsuler les requêtes dans une transaction READ ONLY ; le rôle épinglé ajoute une restriction appliquée par Postgres à la connexion elle-même, de sorte que le SQL qui sort de la transaction reste limité aux privilèges de ce rôle.

• Le serveur résout les identifiants du rôle en interne et ne les renvoie jamais. get_connection_string n’est pas disponible sur une connexion épinglée.
• Un argument d’outil role_name différent du rôle épinglé est rejeté. Si vous l’omettez, le rôle épinglé est utilisé, jamais le propriétaire.
• Si le rôle n’existe pas ou ne peut pas se connecter (par exemple ALTER ROLE … NOLOGIN), l’appel échoue avant l’exécution de toute requête SQL. Il ne réessaie pas avec un autre rôle.
• La valeur doit être un nom de rôle Postgres exact : lettres, chiffres, _ ou $, en commençant par une lettre ou _, et comportant au plus 63 caractères. Toute autre valeur (vide, répétée, entre guillemets, avec des traits d’union) est rejetée avec 400, et non ignorée.
• Le rôle doit pouvoir se connecter (LOGIN) et exister sur chaque branche interrogée. Les rôles créés en SQL (CREATE ROLE app_reader LOGIN PASSWORD '…') fonctionnent, tout comme ceux créés dans la Neon Console ou via l’API. Pour que l’épinglage soit utile, le rôle doit disposer des privilèges nécessaires, et d’aucun autre : pour les agents en lecture seule, accordez SELECT sur les tables qu’ils doivent consulter et ne l’ajoutez pas à neon_superuser. create_postgres_role avec access: "read_only" crée un tel rôle depuis une connexion sans roleName ; les rôles qu’il crée sans access rejoignent neon_superuser.
• OAuth : roleName dans l’URL MCP définit une autorisation fixe. La page d’autorisation affiche le rôle, et le jeton émis le conserve lors de son renouvellement. Modifier l’URL par la suite ne change pas le jeton ; autorisez-vous à nouveau. Avec l’URL par défaut (consentement modifiable), saisissez plutôt le rôle dans le champ facultatif Postgres role ; laissez-le vide pour conserver le propriétaire de la base de données. Les jetons émis avant l’ajout de cette option n’ont aucun rôle épinglé et fonctionnent comme auparavant.
• Clé API : le rôle est lu depuis l’URL à chaque requête. Toute personne pouvant modifier l’URL de connexion et disposant de la clé API peut le changer ou le supprimer ; conservez donc l’URL dans une configuration que l’agent ne contrôle pas.
• L’épinglage s’applique uniquement aux connexions SQL. Les outils de l’API de gestion agissent toujours avec les accès propres à la clé API ou au jeton OAuth ; compare_database_schema, par exemple, est calculé par l’API Neon et n’est pas limité par les privilèges du rôle. Combinez roleName avec readonly=true et category pour limiter également ces outils.

Vous pouvez prévisualiser les outils visibles pour n’importe quelle configuration à l’aide du point de terminaison /api/list-tools (aucune authentification requise) :

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

Outils disponibles en mode lecture seule

Outils personnalisés : 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.

Outils générés de l’API de gestion qui utilisent GET et ne renvoient pas de secrets, ainsi que query_logs (POST, en lecture seule). Prévisualisez l’ensemble exact avec /api/list-tools?readonly=true.

Outils nécessitant un accès en écriture :

• Écritures générées de l’API de gestion (create_project, create_branch, delete_project, …)
• get_connection_string (la chaîne de connexion contient le mot de passe d’un rôle privilégié ; elle est donc masquée en mode lecture seule. Copiez-la plutôt depuis la Neon Console)
• run_sql_transaction (ses instructions s’exécutent dans une seule session ; une instruction COMMIT ou SET TRANSACTION READ WRITE mettrait donc fin à la transaction en lecture seule)
• prepare_database_migration, complete_database_migration
• prepare_query_tuning, complete_query_tuning

Compatibilité des transports

https://mcp.neon.tech/mcp utilise Streamable HTTP sans état. Il prend en charge le protocole MCP 2026-07-28 et un mode de repli sans état pour les clients de l’ère 2025. Les points de terminaison HTTP+SSE /sse et /message, désormais obsolètes, renvoient 410 Gone.

Connectez les clients Streamable HTTP à https://mcp.neon.tech/mcp. Pour les clients qui ne prennent en charge que les serveurs locaux stdio, ajoutez ceci à la configuration du client afin que mcp-remote fasse le pont vers Streamable HTTP :

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

Une requête contenant un en-tête Origin mal formé reçoit 403 Forbidden. Toute origine sérialisée est acceptée, y compris les pages Web, les extensions de navigateur, les webviews de bureau et null, afin que les clients basés sur un navigateur puissent se connecter. Les requêtes sans Origin ne sont pas affectées.

Architecture du serveur distant

Le serveur distant s’exécute comme une application Next.js App Router sur Vercel à l’adresse mcp.neon.tech.

[!NOTE] Le chemin racine / redirige vers la documentation du serveur MCP Neon. Il n’y a pas de page d’accueil.

Principaux composants de l’implémentation :

• app/api/[transport]/route.ts : point de terminaison Streamable HTTP sans état (/mcp)
• app/api/authorize/, app/callback/, app/api/token/, app/api/revoke/ : points de terminaison du flux OAuth
• app/.well-known/ : points de terminaison des métadonnées de découverte OAuth
• mcp/ : serveur MCP, outils, gestionnaires, analyses et intégration Sentry
• lib/ : utilitaires compatibles avec Next.js (OAuth, configuration, gestion des erreurs)
• mcp/utils/read-only.ts : mode lecture seule et gestion des portées

Guides

• Guide du serveur MCP Neon
• Connecter des clients MCP à Neon
• Cursor avec le serveur MCP Neon
• Claude Code avec le serveur MCP Neon
• Claude Desktop avec le serveur MCP Neon
• Cline avec le serveur MCP Neon
• Windsurf avec le serveur MCP Neon
• Zed avec le serveur MCP Neon

Fonctionnalités

Outils pris en charge

Le serveur MCP Neon fournit les actions suivantes, exposées sous forme d’« outils » aux clients MCP. Vous pouvez utiliser ces outils pour interagir avec vos projets et bases de données Neon à l’aide de commandes en langage naturel.

Métadonnées de portée des outils

Chaque définition d’outil comprend une catégorie scope utilisée pour le filtrage des outils selon les autorisations et pour l’expérience de consentement. Les catégories actuelles sont :

• projects
• branches
• endpoints
• snapshots
• schema
• querying
• neon_auth
• data_api
• observability
• docs
• functions
• storage
• realtime
• null (outils sans catégorie de portée : search, fetch, send_feedback)

Remarques :

• Les outils de l’API de gestion proviennent de @neon/tools. Les sélecteurs sont des chemins SDK (projects.list) ; les noms MCP publiés commencent par un verbe (list_projects, delete_project, query_logs). Les noms historiques sont conservés lorsqu’ils existaient déjà (describe_project, create_branch, reset_from_parent, compare_database_schema, provision_neon_auth, provision_neon_data_api, list_branch_computes).
• ?category=branches comprend les outils de branche, de rôle et de base de données (list_postgres_roles, create_postgres_database, …). Un jeton déjà émis pour branches obtient ces droits d’écriture. La liste des ressources de calcul est ?category=endpoints. La restauration d’un instantané est ?category=snapshots.
• Les écritures concernant les membres et les autorisations des projets ne sont pas publiées. list_project_members et list_project_permissions sont des opérations de lecture.
• Les outils de schéma (?category=schema) sont get_database_tables et describe_table_schema, ainsi que compare_database_schema généré.
• L’application du mode lecture seule repose toujours sur readOnlySafe et sur la logique de lecture seule côté serveur ; scope correspond à des métadonnées de catégorie, et non à un commutateur autonome lecture/écriture.
• En mode limité au projet (?projectId=...), les outils sans chemin de projet (list_projects, count_projects, create_project, get_project_consumption, get_branch_consumption, list_organizations, list_regions, search, fetch, …) sont masqués. delete_project est également masqué.

Gestion des projets :

• list_projects : répertorie les projets Neon. limit limite le nombre d’éléments renvoyés.
• count_projects : renvoie le nombre de projets actifs dans une organisation. org_id est facultatif et est résolu de la même manière que pour list_projects.
• describe_project : récupère un projet Neon par son identifiant ({ "project_id": "…" }).
• get_project_consumption, get_branch_consumption : métriques de consommation par projet ou par branche, regroupées par période de facturation. Ces outils acceptent org_id, metrics, from, to et granularity, et nécessitent un forfait Launch, Scale, Agent, Business ou Enterprise. get_branch_consumption nécessite également project_ids, rejette les métriques extra_branches_month et snapshot_storage_bytes_month, et n’est pas disponible avec le forfait Business. Le point de terminaison de l’ancien forfait /consumption_history/projects n’est pas publié.
• create_project : crée un projet Neon et attend le calcul par défaut. Ne renvoie pas de chaîne de connexion. Les arguments sont { "name": "…", "org_id": "…", "region_id": "…" }. Appelez get_connection_string une fois l’opération réussie.
• delete_project : supprime un projet Neon existant. Les arguments sont { "project_id": "…" }.
• list_organizations : répertorie toutes les organisations auxquelles l’utilisateur actuel a accès. Vous pouvez filtrer par nom ou identifiant d’organisation à l’aide du paramètre de recherche.

Gestion des branches :

• list_branches : répertorie les branches d’un projet. Utilisez-le pour résoudre un nom de branche en identifiant br-….
• list_credentials, create_credential, revoke_credential, rotate_credential : identifiants limités à une branche pour Object Storage et l’AI Gateway. reveal n’est pas un outil ; la rotation remplace les secrets sur place et n’est pas idempotente.
• create_branch : crée une branche avec un calcul en lecture-écriture et attend qu’elle soit prête. Ne renvoie pas de chaîne de connexion. Les arguments sont { "project_id": "…", "name": "feature-x" }. Transmettez no_compute: true pour ignorer le point de terminaison. Appelez get_connection_string une fois l’opération réussie.
• reset_from_parent : réinitialise une branche à la valeur HEAD actuelle de son parent ({ "project_id": "…", "branch_id": "br-…" }). Les écritures effectuées depuis la divergence de la branche sont supprimées. preserve_under_name est obligatoire si la branche a des branches enfants ; celles-ci sont déplacées vers la nouvelle branche. Seule la valeur HEAD du parent est prise en charge ; pour une restauration à un instant précis, utilisez restore_snapshot.
• delete_branch : supprime une branche ({ "project_id": "…", "branch_id": "br-…" }).
• describe_branch : récupère l’arborescence des bases de données, schémas, tables, vues et fonctions d’une branche.
• Les outils de branche générés prennent branch_id comme identifiant de branche (br-...), et non comme nom.
• restore_snapshot : restaure un instantané. Transmettez target_branch_id pour le restaurer sur une branche existante ; omettez-le pour en créer une nouvelle.

Points de terminaison de calcul (?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

Instantanés (?category=snapshots) :

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

Schéma (?category=schema) :

• get_database_tables, describe_table_schema
• compare_database_schema : comparaison SQL des schémas d’une base de données avec ceux d’une autre branche. database_name est obligatoire. Si base_branch_id est omis, la comparaison se fait avec le parent. Les paramètres facultatifs lsn, timestamp, base_lsn, base_timestamp ne sont disponibles que pour les comparaisons à un instant précis.

Exécution de requêtes SQL :

• get_connection_string : Renvoie votre chaîne de connexion à la base de données.
• run_sql : Exécute une seule requête SQL sur une base de données Neon spécifiée. Prend en charge les opérations de lecture et d’écriture. L’option facultative role_name se connecte en tant que ce rôle Postgres plutôt qu’en tant que propriétaire de la base de données, et compute_id sélectionne le calcul ; les identifiants restent sur le serveur. Sur une connexion avec ?roleName=, role_name doit être omis ou correspondre à cette valeur. Renvoie le tableau de lignes avec au plus max_rows lignes (100 par défaut, jusqu’à 10 000) ; si des lignes ont été tronquées, un deuxième bloc de contenu contient { totalRowCount, truncated, note }. Une requête ayant échoué renvoie le code SQLSTATE Postgres, la position de l’erreur et tout détail, indice ou contexte.
• run_sql_transaction : Exécute une série de requêtes SQL au sein d’une seule transaction sur une base de données Neon. Accepte les mêmes options facultatives role_name, compute_id et max_rows que run_sql. max_rows s’applique à chaque instruction ; si une instruction a été tronquée, le deuxième bloc contient un résumé par instruction.
• get_database_tables : Répertorie toutes les tables d’une base de données Neon spécifiée.
• describe_table_schema : Récupère la définition du schéma d’une table spécifique, avec le détail des colonnes, des types de données et des contraintes.

Migrations de base de données (modifications du schéma) :

• prepare_database_migration : Lance un processus de migration de base de données. Point essentiel : il crée une branche temporaire pour appliquer et tester la migration en toute sécurité avant de modifier la branche principale.
• complete_database_migration : Finalise et applique une migration de base de données préparée à la branche principale. Cette action fusionne les modifications de la branche de migration temporaire et supprime les ressources temporaires.

Requêtes SQL et optimisation :

• inspect_database : Exécute l’un des 15 diagnostics Postgres prédéfinis en lecture seule sur une branche : tailles des relations et des index, utilisation des index et des analyses séquentielles, requêtes et verrous actifs, requêtes les plus lourdes et les plus fréquentes, taux de succès du cache et taille de l’ensemble de travail, estimations de l’autovacuum et du gonflement, ainsi que l’état de la réplication. Mêmes vérifications que la commande CLI neon inspect db. Omettez database_name pour couvrir toutes les bases de données de la branche ; indiquez un nom pour en examiner une seule. Quatre de ces diagnostics nécessitent l’extension pg_stat_statements ou neon.
• list_slow_queries : Identifie les goulots d’étranglement des performances en trouvant les requêtes les plus lentes d’une base de données. Nécessite l’extension pg_stat_statements.
• explain_sql_statement : Fournit des plans d’exécution détaillés pour les requêtes SQL afin d’aider à identifier les goulots d’étranglement des performances.
• prepare_query_tuning : Analyse les performances des requêtes et suggère des optimisations, comme la création d’index. Crée une branche temporaire pour tester ces optimisations en toute sécurité.
• complete_query_tuning : Finalise l’optimisation des requêtes en appliquant les optimisations à la branche principale ou en les abandonnant. Supprime la branche temporaire d’optimisation.

Neon Auth (?category=neon_auth) :

• provision_neon_auth, get_auth, disable_auth, update_auth_config
• get_neon_auth_config : Les secrets sont masqués. Lit les origines de confiance, l’accès à localhost, les options de messagerie et de mot de passe, les fournisseurs OAuth, le fournisseur de messagerie, les plugins d’organisation, de lien magique et de numéro de téléphone, le webhook et l’exportation des journaux.
• 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 : Modifient ces paramètres. update_auth_webhooks remplace toute la configuration du webhook. update_auth_logs_export active ou désactive l’exportation des événements Neon Auth vers les journaux Neon Platform ; un projet sans exportation des journaux n’accepte que 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 : Configurent Neon Auth comme serveur d’autorisation OAuth 2.1 (y compris pour les serveurs MCP). Cette configuration est distincte des fournisseurs de connexion sociale ci-dessus.
• 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 : Gèrent les clients OAuth de ce serveur. create_auth_oauth_client et rotate_auth_oauth_client_secret renvoient le client_secret une seule fois.
• 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 : Gèrent la Data API d’une base de données de branche.

Recherche et découverte :

• search : Recherche dans les organisations, les projets et les branches correspondant à une requête. Renvoie les identifiants, les titres et les liens directs vers la Neon Console.
• fetch : Récupère des informations détaillées sur une organisation, un projet ou une branche spécifique à l’aide d’un identifiant (généralement obtenu avec l’outil de recherche).

Commentaires (toujours disponible, y compris le point de terminaison ?category=docs sans connexion) :

• send_feedback : Envoie des commentaires anonymes à l’équipe Neon. Seul le texte du commentaire est envoyé, sans détails sur le compte, le projet ou la connexion. Les messages sont limités à 10 000 caractères.

Observabilité (?category=observability) : ces outils nécessitent Neon Platform Beta et sont actuellement disponibles uniquement pour les projets de la région aws-us-east-2. Une branche sans accès aux journaux renvoie HTTP 404 avec le motif telemetry_not_enabled.

• query_logs : Interroge les journaux OpenTelemetry d’une branche. Utilise POST dans l’API Management ; ce serveur le traite comme une opération en lecture seule.
• query_loki_logs : Exécute une requête de plage LogQL sur l’API de lecture compatible avec Loki de la branche et renvoie la réponse de Loki : des lignes regroupées par étiquettes de flux, avec des horodatages en nanosecondes.
• list_log_fields : Répertorie les champs de journal dont vous pouvez énumérer les valeurs sur une branche.
• list_log_field_values : Répertorie les valeurs distinctes d’un champ de journal dans une branche et une fenêtre temporelle.

Documentation et ressources (?category=docs) :

• search_docs : Effectue une recherche sur neon.com (documentation, référence de l’API, tutoriel PostgreSQL, guides, FAQ, journal des modifications et blog) avec la même recherche que le champ de recherche de neon.com. Accepte query, categories facultatif (docs, api, postgresql, guides, faqs, blog, changelog), et limit facultatif (1-40, 10 par défaut). Renvoie les pages classées par pertinence avec title, url, slug, category, breadcrumb, heading et excerpt ; transmettez slug à get_doc pour lire la page.
• get_doc : Récupère une page neon.com au format Markdown. Accepte slug provenant d’un résultat search_docs (par exemple docs/guides/prisma ou postgresql/tutorial/inner-join).

Fonctions (?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 : Déclencheurs de fonctions planifiées (type: "schedule", cron UTC à cinq champs).

Stockage (?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

Temps réel (?category=realtime) :

• get_realtime, enable_realtime, disable_realtime : État de Realtime de la branche, activation (avec allowed_origins facultatif) et désactivation. L’activation et la désactivation attendent que la modification soit appliquée.
• get_realtime_secret : Le secret partagé avec lequel le backend de l’application émet les jetons Realtime. Non disponible en mode lecture seule.
• rotate_realtime_secret : Remplace le secret partagé et attend que la modification soit appliquée. N’est pas idempotent. Appelez get_realtime_secret ensuite pour obtenir la nouvelle valeur.

Migrations

Les migrations permettent de gérer les modifications du schéma de votre base de données au fil du temps. Avec le serveur Neon MCP, les LLM peuvent effectuer des migrations en toute sécurité à l’aide de commandes distinctes « Start » (prepare_database_migration) et « Commit » (complete_database_migration).

La commande « Start » accepte une migration et l’exécute dans une nouvelle branche temporaire. À son retour, elle indique au LLM de tester la migration sur cette branche. Le LLM peut ensuite exécuter la commande « Commit » pour appliquer la migration à la branche d’origine.

Développement

Ce projet utilise pnpm comme gestionnaire de paquets, dont la version est fixée via Corepack.

Structure du projet

Le code du serveur MCP se trouve à la racine du dépôt. Il s’agit d’une application Next.js déployée sur Vercel à l’adresse mcp.neon.tech.

corepack enable
pnpm install

Consultez CONTRIBUTING.md pour savoir comment ajouter des outils. Les arguments des outils sont snake_case.

Développement local

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

Lint et vérification des types

pnpm lint
pnpm typecheck

Variables d’environnement

Requises pour l’exécution du serveur distant :

Variable	Description
SERVER_HOST	URL du serveur (par défaut, VERCEL_URL)
UPSTREAM_OAUTH_HOST	URL du fournisseur OAuth Neon
CLIENT_ID	ID client OAuth
CLIENT_SECRET	Secret client OAuth
KV_URL	URL Redis Upstash (verrou transitoire)
OAUTH_DATABASE_URL	URL Postgres pour le stockage des jetons

Facultatives :

Variable	Description
LOG_LEVEL	Niveau de journalisation Winston : error, warn, info (par défaut), debug, verbose, silly
NEON_MCP_DISABLE_ANALYTICS	Définissez sur 1 pour désactiver l’analytique produit

Pyramide de tests

Tous les tests s’exécutent depuis la racine du dépôt.

# 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

Stratégie de test :

• Privilégiez les tests E2E pour le transport, le protocole et les comportements visibles par l’utilisateur.
• Utilisez des tests d’intégration pour vérifier les contrats déterministes des outils et le comportement des workflows.
• Utilisez des tests unitaires pour la logique pure et les cas limites.
• Évitez de dépendre de la disponibilité de services tiers dans les tests bloquant les fusions ; simulez les dépendances externes dans les niveaux d’intégration et unitaires.

Déploiement

Vercel déploie automatiquement le serveur distant à partir de la configuration de branche du dépôt. Des environnements de prévisualisation sont disponibles pour les demandes de fusion.

Télémétrie

Le serveur Neon MCP collecte des données analytiques sur le produit et des rapports d’erreur afin de nous aider à comprendre son utilisation et à améliorer sa fiabilité :

• Analytique produit (Segment) : lorsque vous vous connectez avec un compte authentifié, le serveur envoie un événement identify contenant l’ID, le nom et l’adresse e-mail de votre compte Neon. Il suit également le début de session (server_init), chaque appel d’outil (tool_call) et les erreurs inattendues du serveur (server_error). Un événement d’appel d’outil inclut le nom de l’outil, la méthode d’authentification et le client, mais pas les arguments de l’outil ni les résultats des requêtes. Les appels aux outils de documentation sans compte sont suivis de manière anonyme. La page affichée après l’autorisation signale qu’elle a été présentée (auth_complete_viewed, avec le résultat et le client) et indique quels boutons et liens ont été utilisés (auth_complete_action) ; le navigateur n’envoie qu’un identifiant aléatoire de vue de page, jamais le code d’autorisation ni votre identité. Les événements sont envoyés à track.neon.tech, le point de terminaison analytique de Neon.
• Rapports d’erreur, traces et journaux (Sentry) : les erreurs inattendues du serveur sont signalées avec les traces de pile, ainsi que la méthode et le chemin de la requête. Les en-têtes, corps, cookies et chaînes de requête ne sont pas envoyés. Chaque requête et appel d’outil fait l’objet d’une trace comprenant le nom de l’outil, le nom du client, l’ID du compte et l’indication d’échec ou non de l’appel, ainsi que l’ID de session attribué par le serveur aux clients de l’ère 2025 et l’ID de conversation envoyé par un client dans _meta.threadId. Les traces ne contiennent aucun argument ni résultat d’outil. Les journaux du serveur sont également envoyés à Sentry. Cette collection est couverte par la Politique de confidentialité de Neon. Pour désactiver les analyses lorsque vous exécutez le serveur vous-même, définissez NEON_MCP_DISABLE_ANALYTICS=1. Ce paramètre ne désactive pas Sentry.