Neon

Serveur MCP Neon

Le serveur MCP Neon est un outil open-source qui vous permet d'interagir avec vos bases de données Postgres Lakebase 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 agit comme un pont entre les requêtes en langage naturel et l'API Neon. Construit sur MCP, il traduit vos requêtes en appels API nécessaires, vous permettant de gérer des tâches telles que la création de projets et de branches, l'exécution de requêtes, et la réalisation de migrations de bases de données en toute simplicité.

Parmi les principales fonctionnalités du serveur MCP Neon, on trouve :

• Interaction en langage naturel : Gérez les bases de données Neon à l'aide de commandes conversationnelles intuitives.
• Gestion simplifiée des bases de données : Effectuez des actions complexes sans écrire de SQL ni utiliser directement l'API Neon.
• Accessibilité pour les non-développeurs : Permettez aux utilisateurs ayant des parcours 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 les modifications de schéma de base de données initiées en langage naturel.

Par exemple, dans Claude Code, ou tout autre client MCP, vous pouvez utiliser le langage naturel pour accomplir des tâches 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é du serveur MCP Neon
Le serveur MCP Neon offre des capacités puissantes de gestion de 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 au serveur MCP Neon.

Le serveur MCP Neon est destiné au développement local et aux intégrations IDE uniquement. Nous déconseillons l'utilisation du serveur MCP Neon 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 plus d'informations, consultez Recommandations de sécurité MCP →.

Configuration du serveur MCP Neon

Plusieurs options s'offrent à vous pour configurer le serveur MCP Neon :

1. Configuration rapide avec clé API (Cursor, VS Code et Claude Code) : Exécutez neon@latest init pour configurer automatiquement le serveur MCP de Neon, les compétences d'agent et l'extension VS Code en une seule commande.
2. Serveur MCP distant (authentification par OAuth) : Connectez-vous au serveur MCP géré de Neon en utilisant OAuth pour l'authentification. Cette méthode est plus pratique car elle élimine le besoin de gérer des clés API. De plus, vous recevrez 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é de Neon en utilisant une clé API pour l'authentification. Cette méthode est utile si vous souhaitez connecter un agent distant à Neon lorsque OAuth n'est pas disponible. De plus, vous recevrez 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 clé API

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

Exécutez neon@latest init pour configurer automatiquement le serveur MCP de Neon en une seule commande :

npx neon@latest init

Cela fonctionne avec Cursor, VS Code (GitHub Copilot) et Claude Code. L'authentification s'effectuera via OAuth, une clé API Neon sera créée pour vous, et votre éditeur sera configuré automatiquement.

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

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

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

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

Ajoutez l'indicateur -g pour ajouter le serveur MCP Neon à la liste globale des serveurs MCP au lieu d'une portée limitée au projet.

Vous pouvez également ajouter l'entrée « Neon » suivante au fichier de configuration du serveur MCP de votre client (par exemple, mcp.json, mcp_config.json) :

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

Kiro : Ajoutez ce qui suit à votre fichier de configuration MCP Kiro (~/.kiro/settings/mcp.json pour un niveau global, ou .kiro/settings/mcp.json pour une portée limitée au projet) :

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

Ou utilisez le bouton d'installation en un clic en haut de ce README. Pour plus d'informations, consultez la documentation MCP de Kiro.

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

Avec l'authentification par OAuth, le serveur MCP opère 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 explicitement fournir soit org_id soit project_id dans votre invite 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 prend en charge.

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

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

Vous pouvez également ajouter l'entrée « Neon » suivante au fichier de configuration du serveur MCP de votre client (par exemple, mcp.json, mcp_config.json) :

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

Fournissez une clé API d'organisation pour limiter l'accès aux projets de l'organisation uniquement.

Portées et mode lecture seule

Neon MCP prend en charge les portées OAuth read, write et * (* signifie les deux). Votre client MCP peut demander ces portées directement, ou vous pouvez effectuer la sélection dans l'interface d'autorisation OAuth.

Le mode lecture seule restreint les outils disponibles, en désactivant les opérations d'écriture telles que la création de projets, de branches ou l'exécution de migrations. Les outils en lecture seule incluent la liste des projets, la description des schémas, l'interrogation des données et la consultation des métriques de performance.

Vous pouvez activer le mode lecture seule de deux manières :

1. Sélection de la portée OAuth (recommandé) : Dans OAuth, sélectionnez lecture seule en décochant Accès complet dans l'interface d'autorisation.
2. Paramètre de requête readonly : Ajoutez ?readonly=true à l'URL de votre serveur MCP :

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

Comportement du paramètre de requête :

• Flux de clé API : readonly=true est le moyen d'activer le mode lecture seule (aucun échange de portée OAuth dans ce flux).
• Flux OAuth : readonly=true remplace la portée OAuth. Sans lui, le mode lecture seule est déterminé par la portée sélectionnée dans l'interface de consentement OAuth.

L'en-tête HTTP hérité x-read-only est également pris en charge en secours (priorité inférieure au paramètre de requête).

Remarque : Le mode lecture seule restreint les outils disponibles. De plus, l'outil run_sql reste disponible uniquement pour les requêtes en lecture seule.

Paramètres de requête URL pour le contrôle d'accès

Le contexte d'autorisation (catégories de portée, portée du projet, mode lecture seule) est configuré via des paramètres de requête URL sur l'URL du serveur MCP. La configuration accompagne chaque requête et prend effet immédiatement — aucune ré-authentification n'est nécessaire.

Paramètre	Description	Exemple
readonly	Activez le mode lecture seule (true/false)	?readonly=true
category	Limitez à des catégories d'outils spécifiques (répétés ou CSV)	?category=querying&category=schema
projectId	Limitez toutes les opérations à un seul projet	?projectId=proj-123

Exemple de lecture seule + portée limitée à un projet :

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

Exemple de filtre par catégorie (uniquement les outils d'interrogation et de schéma) :

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

Vous pouvez prévisualiser les outils visibles pour toute 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

• 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

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

• 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

Transport Server-Sent Events (SSE) (obsolète)

MCP prend en charge deux transports de serveur distant : le Server-Sent Events (SSE) obsolète et le Streamable HTTP plus récent et recommandé. Si votre client LLM ne prend pas encore en charge Streamable HTTP, vous pouvez faire passer le point de terminaison de https://mcp.neon.tech/mcp à https://mcp.neon.tech/sse pour utiliser SSE à la place.

Exécutez la commande suivante pour ajouter le serveur MCP Neon pour tous les agents et éditeurs détectés dans votre espace de travail en utilisant le transport SSE :

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

Architecture du serveur distant

Le serveur distant s'exécute comme une application Next.js App Router sur Vercel à 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 domaines d'implémentation :

• app/api/[transport]/route.ts : point de terminaison de transport MCP pour Streamable HTTP (/mcp) et SSE (/sse)
• app/api/authorize/, app/callback/, app/api/token/, app/api/revoke/ : points de terminaison du flux OAuth
• app/.well-known/ : points de terminaison de métadonnées de découverte OAuth
• mcp/ : serveur MCP, outils, gestionnaires, analyses et intégration Sentry
• lib/ : utilitaires compatibles Next.js (OAuth, configuration, gestion des erreurs)
• mcp/utils/read-only.ts : gestion du mode lecture seule et 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 comme « 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 inclut une catégorie scope utilisée pour le filtrage des outils basé sur les autorisations et l'UX de consentement. Les catégories actuelles sont :

• projects
• branches
• schema
• querying
• neon_auth
• data_api
• observability
• docs
• null (outils sans catégorie de portée)

Remarques :

• compare_database_schema est catégorisé sous schema.
• provision_neon_data_api est catégorisé sous data_api (séparé de neon_auth).
• L'application de la lecture seule repose toujours sur readOnlySafe et la logique de lecture seule côté serveur ; scope est une métadonnée de catégorie, pas un interrupteur de lecture/écriture autonome.
• En mode limité au projet (?projectId=...), search et fetch ne sont pas disponibles.

Gestion de projet :

• list_projects : Liste les 10 premiers projets Neon de votre compte, en fournissant un résumé de chaque projet. Si vous ne trouvez pas un projet spécifique, augmentez la limite en passant une valeur plus élevée au paramètre limit.
• list_shared_projects : Liste les projets Neon partagés avec l'utilisateur actuel. Prend en charge un paramètre de recherche et la limitation du nombre de projets renvoyés (par défaut : 10).
• describe_project : Récupère des informations détaillées sur un projet Neon spécifique, notamment son ID, son nom, ainsi que les branches et bases de données associées.
• create_project : Crée un nouveau projet Neon dans votre compte Neon. Un projet sert de conteneur pour les branches, les bases de données, les rôles et les computes.
• delete_project : Supprime un projet Neon existant et toutes ses ressources associées.
• list_organizations : Liste toutes les organisations auxquelles l'utilisateur actuel a accès. Filtrez éventuellement par nom ou ID d'organisation à l'aide du paramètre de recherche.

Gestion des branches :

• create_branch : Crée une nouvelle branche dans un projet Neon spécifié. Utilise la fonctionnalité de branchement de Neon pour le développement, les tests ou les migrations.
• delete_branch : Supprime une branche existante d'un projet Neon.
• describe_branch : Récupère les détails d'une branche spécifique, tels que son nom, son ID et sa branche parente.
• list_branch_computes : Liste les points de terminaison de calcul pour un projet ou une branche spécifique, y compris l'ID de calcul, le type, la taille, la dernière activité et les informations d'autoscaling.
• compare_database_schema : Affiche la différence de schéma entre la branche enfant et sa parente.
• reset_from_parent : Réinitialise la branche actuelle à l'état de sa parente, en écartant les modifications locales. Sauvegarde automatiquement si la branche a des enfants, ou sur demande avec un nom personnalisé.

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.
• run_sql_transaction : Exécute une série de requêtes SQL dans une seule transaction sur une base de données Neon.
• get_database_tables : Liste toutes les tables d'une base de données Neon spécifiée.
• describe_table_schema : Récupère la définition de schéma d'une table spécifique, détaillant les colonnes, les types de données et les contraintes.

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

• prepare_database_migration : Lance un processus de migration de base de données. Critiquement, il crée une branche temporaire pour appliquer et tester la migration en toute sécurité avant d'affecter 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 nettoie les ressources temporaires.

Interrogation et optimisation SQL :

• inspect_database : Exécute l'un des 14 diagnostics Postgres en lecture seule prédéfinis sur une branche — tailles des relations et des index, utilisation des index et des scans séquentiels, requêtes actives et verrous, requêtes les plus lourdes et les plus fréquentes, taux de succès du cache et taille de l'ensemble de travail, estimations d'autovacuum et de gonflement, et état de réplication. Mêmes vérifications que la commande CLI neon inspect db. Quatre d'entre elles nécessitent l'extension pg_stat_statements ou neon.
• list_slow_queries : Identifie les goulots d'étranglement de performance en trouvant les requêtes les plus lentes dans 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'identifier les goulots d'étranglement de performance.
• 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 écartant. Nettoie la branche d'optimisation temporaire.

Neon Auth :

• provision_neon_auth : Provisionne Neon Auth pour un projet Neon. Il permet aux développeurs de configurer facilement l'infrastructure d'authentification en créant une intégration avec un fournisseur Auth.
• configure_neon_auth : Configure une intégration Neon Auth existante pour une branche — gestion des origines de confiance, accès localhost, méthodes d'authentification, fournisseurs OAuth et fournisseur d'e-mails transactionnels.
• get_neon_auth_config : Lit la configuration complète de Neon Auth pour une branche, y compris les métadonnées d'intégration et les paramètres configurables (les secrets sont masqués).

Neon Data API :

• provision_neon_data_api : Provisionne la Neon Data API pour un accès à la base de données via HTTP avec authentification JWT optionnelle via Neon Auth ou des fournisseurs JWKS externes.

Recherche et découverte :

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

Observabilité : ces outils nécessitent la bêta de la plateforme Neon et ne sont actuellement disponibles que pour les projets de la région aws-us-east-2. Une branche sans accès aux journaux renvoie HTTP 404 avec la raison telemetry_not_enabled.

• query_logs : Interroge les journaux OpenTelemetry émis par les fonctions serverless de Neon et d'autres services. Utilisez des filtres structurés pour la source, le nom du service, la gravité et la fenêtre temporelle, ou logql brute pour les sélecteurs de flux et les filtres de ligne que les entrées structurées ne peuvent pas exprimer.
• list_log_fields : Liste les champs de journaux pour lesquels vous pouvez énumérer les valeurs sur une branche, tels que service_name, severity_text et scope_name. À utiliser avant list_log_field_values.
• list_log_field_values : Liste les valeurs distinctes d'un champ de journal dans une branche et une fenêtre temporelle, afin de découvrir des valeurs concrètes pour les filtres structurés ou logql brute.

Documentation et ressources :

• list_docs_resources : Liste toutes les pages de documentation Neon disponibles en récupérant l'index depuis https://neon.com/docs/llms.txt. Renvoie les URL et les titres des pages qui peuvent être récupérées individuellement à l'aide de l'outil get_doc_resource.
• get_doc_resource : Récupère une page de documentation Neon spécifique sous forme de contenu markdown. Utilisez d'abord l'outil list_docs_resources pour découvrir les slugs de pages disponibles, puis transmettez le slug à cet outil.

Migrations

Les migrations sont un moyen de gérer les modifications apportées au schéma de votre base de données au fil du temps. Avec le serveur Neon MCP, les LLM sont habilités à effectuer des migrations en toute sécurité avec des 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. Au retour, cette commande indique au LLM qu'il doit 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, épinglé via Corepack.

Structure du projet

Le code du serveur MCP se trouve à la racine du dépôt, une application Next.js déployée sur Vercel à mcp.neon.tech.

corepack enable
pnpm install

Développement local

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

Linting et vérification des types

pnpm lint
pnpm typecheck

Variables d'environnement

Requis 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
COOKIE_SECRET	Secret pour les cookies signés
KV_URL	URL Vercel KV (Upstash Redis)
OAUTH_DATABASE_URL	URL Postgres pour le stockage des jetons

Facultatif :

Variable	Description
LOG_LEVEL	Niveau de journal Winston : error, warn, info (défaut), debug, verbose, silly

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 :

• Préférez E2E pour le transport/protocole et le comportement visible par l'utilisateur.
• Utilisez des tests d'intégration pour les contrats d'outils déterministes 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 tiers dans les tests de validation de fusion ; simulez les dépendances externes dans les niveaux d'intégration/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 tirage (pull requests).