Neon

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

Neon MCP Server

Neon MCP Server es una herramienta de código abierto que te permite interactuar con tus bases de datos Lakebase Postgres en Neon en lenguaje natural.

El Model Context Protocol (MCP) es un protocolo estandarizado diseñado para gestionar el contexto entre modelos de lenguaje grandes (LLM) y sistemas externos. Este repositorio proporciona un servidor MCP remoto para Neon.

El servidor MCP de Neon actúa como puente entre las solicitudes en lenguaje natural y la API de Neon. Basado en MCP, traduce tus solicitudes en las llamadas API necesarias, lo que te permite gestionar tareas como crear proyectos y ramas, ejecutar consultas y realizar migraciones de bases de datos sin complicaciones.

Algunas de las funciones clave del servidor MCP de Neon incluyen:

• Interacción en lenguaje natural: Gestiona bases de datos de Neon mediante comandos intuitivos y conversacionales.
• Gestión simplificada de bases de datos: Realiza acciones complejas sin escribir SQL ni usar directamente la API de Neon.
• Accesibilidad para quienes no son desarrolladores: Permite que usuarios con distintos niveles de conocimientos técnicos interactúen con bases de datos de Neon.
• Compatibilidad con migraciones de bases de datos: Aprovecha las capacidades de ramificación de Neon para realizar cambios en el esquema de la base de datos mediante solicitudes en lenguaje natural.

Por ejemplo, en Claude Code o cualquier cliente MCP, puedes usar lenguaje natural para realizar tareas con 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]
Consideraciones de seguridad de Neon MCP Server
Neon MCP Server otorga potentes capacidades de gestión de bases de datos mediante solicitudes en lenguaje natural. Revisa y autoriza siempre las acciones solicitadas por el LLM antes de ejecutarlas. Asegúrate de que solo los usuarios y las aplicaciones autorizados tengan acceso a Neon MCP Server.

Neon MCP Server está pensado únicamente para el desarrollo local y las integraciones con IDE. No recomendamos usar Neon MCP Server en entornos de producción. Puede ejecutar operaciones potentes que podrían provocar cambios accidentales o no autorizados.

Para obtener más información, consulta las recomendaciones de seguridad de MCP →.

Configuración de Neon MCP Server

Hay varias opciones para configurar Neon MCP Server:

1. Configuración rápida con clave de API (Cursor, VS Code y Claude Code): Ejecuta neon@latest init para configurar automáticamente Neon MCP Server, las habilidades de agente y la extensión de VS Code con un solo comando.
2. Servidor MCP remoto (autenticación basada en OAuth): Conéctate al servidor MCP gestionado de Neon mediante OAuth para la autenticación. Este método es más práctico porque elimina la necesidad de gestionar claves de API. Además, recibirás automáticamente las últimas funciones y mejoras en cuanto se publiquen.
3. Servidor MCP remoto (autenticación basada en clave de API): Conéctate al servidor MCP gestionado de Neon mediante una clave de API para la autenticación. Este método es útil si quieres conectar a Neon un agente remoto que no dispone de OAuth. Además, recibirás automáticamente las últimas funciones y mejoras en cuanto se publiquen.

Requisitos previos

• Una aplicación cliente MCP.
• Una cuenta de Neon.
• Node.js (>= v18.0.0): Descárgalo desde nodejs.org.
• Si IP Allow está habilitado, añade 34.192.103.46 y 23.22.233.166 a tu lista de permitidos (mcp.neon.tech IP estáticas).

Para el desarrollo, necesitarás Node.js 22+ (pnpm se proporciona mediante Corepack; ejecuta corepack enable para activarlo).

Opción 1. Configuración rápida con clave de API

¿No quieres crear manualmente una clave de API?

Ejecuta neon@latest init para configurar automáticamente Neon MCP Server con un solo comando:

npx neon@latest init

Funciona con Cursor, VS Code (GitHub Copilot) y Claude Code. Se autenticará mediante OAuth, creará una clave de API de Neon y configurará automáticamente tu editor.

Opción 2. Servidor MCP remoto alojado (autenticación basada en OAuth)

Conéctate al servidor MCP gestionado de Neon mediante OAuth para la autenticación. Esta es la configuración más sencilla: no requiere instalar este servidor localmente ni configurar una clave de API de Neon en el cliente.

Ejecuta el siguiente comando para añadir Neon MCP Server a todos los agentes y editores detectados en tu espacio de trabajo:

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

Esa URL publica proyectos, ramas, endpoints de cómputo, consultas y esquemas. Previsualízala con /api/list-tools?category=projects&category=branches&category=endpoints&category=querying&category=schema. La URL sin filtros publica todas las categorías:

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

Añade la opción -g para agregar Neon MCP Server a la lista global de servidores MCP en lugar de limitarlo al proyecto.

Como alternativa, puedes añadir la siguiente entrada «Neon» al archivo de configuración de servidores MCP de tu cliente (por ejemplo, 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: Añade lo siguiente al archivo de configuración MCP de Kiro (~/.kiro/settings/mcp.json para la configuración global o .kiro/settings/mcp.json para la configuración del proyecto):

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

O usa el botón de instalación con un clic que aparece en la parte superior de este README. Para obtener más información, consulta la documentación de Kiro MCP.

• Reinicia o actualiza tu cliente MCP.
• Se abrirá una ventana de OAuth en el navegador. Sigue las indicaciones para autorizar el acceso de tu cliente MCP a tu cuenta de Neon.

Con la autenticación basada en OAuth, el servidor MCP operará de forma predeterminada en los proyectos de tu cuenta personal de Neon. Para acceder a proyectos de una organización o gestionarlos, debes proporcionar explícitamente org_id o project_id en la solicitud a tu cliente MCP.

Opción 3. Servidor MCP remoto alojado (autenticación basada en clave de API)

El servidor MCP remoto también admite la autenticación mediante una clave de API en el encabezado Authorization, si tu cliente lo admite.

Crea una clave de API de Neon en la consola de Neon. A continuación, ejecuta el siguiente comando para añadir Neon MCP Server a todos los agentes y editores detectados en tu espacio de trabajo:

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, puedes añadir la siguiente entrada «Neon» al archivo de configuración de servidores MCP de tu cliente (por ejemplo, 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>"
      }
    }
  }
}

Proporciona una clave de API de una organización para limitar el acceso únicamente a los proyectos de esa organización.

Ámbitos y modo de solo lectura

Neon MCP anuncia los ámbitos de OAuth read y write. Tu cliente MCP puede solicitarlos, o puedes seleccionarlos en la interfaz de permisos de OAuth. * se trata como escritura si un cliente aún lo envía.

El modo de solo lectura restringe las herramientas disponibles y deshabilita las operaciones de escritura, como crear proyectos y ramas o ejecutar migraciones. Las herramientas de solo lectura incluyen enumerar proyectos, describir esquemas, consultar datos y ver métricas de rendimiento.

Puedes configurar el modo de solo lectura de dos maneras:

1. URL MCP predeterminada (consentimiento editable): Conéctate con https://mcp.neon.tech/mcp y desmarca Permitir escrituras en la página de autorización. Allí también puedes elegir un proyecto, un rol de Postgres para SQL y un subconjunto de categorías de herramientas.
2. URL MCP con parámetros (consentimiento fijo): Incluye readonly, projectId, category o roleName en la URL del servidor MCP. La página de autorización confirma ese permiso y no ofrece opciones de edición. Para cambiar el permiso, modifica la URL y vuelve a autorizar.

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

Comportamiento del parámetro de consulta:

• Flujo con clave de API: readonly=true es la forma de habilitar el modo de solo lectura (en este flujo no hay intercambio de ámbitos de OAuth). Los cambios en la URL se aplican en la siguiente solicitud.
• Flujo de OAuth: projectId, category, readonly y roleName en la URL MCP constituyen un permiso fijo que se confirma durante la autorización. readonly=true no se puede ampliar para permitir escrituras en esa página. Una vez emitido el token, cambiar la URL no amplía sus permisos; vuelve a autorizar.

Para el registro de OAuth, x-read-only es el valor inicial predeterminado de Permitir escrituras en el consentimiento editable. No bloquea la confirmación ni reduce los permisos de una URL con parámetros que incluya readonly=false. Las solicitudes con clave de API siguen respetando x-read-only en cada solicitud, por debajo del parámetro de consulta readonly.

Nota: El modo de solo lectura restringe las herramientas disponibles. run_sql sigue disponible y ejecuta cada consulta en una transacción READ ONLY. run_sql_transaction no está disponible; ejecuta cada instrucción con run_sql. Esas llamadas se ejecutan por separado y no comparten una transacción. Para obtener semántica transaccional, usa una conexión que permita escrituras.

Parámetros de consulta de URL para el control de acceso

El contexto de permisos (categorías de ámbito, limitación al proyecto, modo de solo lectura y rol de Postgres fijado) se configura mediante parámetros de consulta en la URL del servidor MCP. Las solicitudes con clave de API aplican esos parámetros en cada solicitud. Los tokens de OAuth almacenan los permisos confirmados o editados durante la autorización.

Parámetro	Descripción	Ejemplo
readonly	Habilita el modo de solo lectura (true/false)	?readonly=true
category	Limita el acceso a categorías específicas de herramientas (repetidas o CSV)	?category=querying&category=schema
projectId	Limita todas las operaciones a un solo proyecto	?projectId=proj-123
roleName	Ejecuta todo el SQL con este rol de Postgres en lugar del propietario	?roleName=app_reader

Ejemplo de solo lectura y limitado a un proyecto:

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

Ejemplo con filtro de categorías (solo herramientas de consulta y esquema):

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

Ejemplo con rol de Postgres fijado (solo lectura, un proyecto, SQL como app_reader):

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

roleName fija el rol de inicio de sesión de Postgres para toda la conexión. Todo el SQL que el servidor ejecuta por ti (run_sql, run_sql_transaction, explain_sql_statement, get_database_tables, describe_table_schema, describe_branch, list_slow_queries, inspect_database y el SQL de las migraciones y el ajuste de consultas) inicia sesión con ese rol, por lo que los permisos de Postgres determinan qué puede leer o modificar el agente. Sin este parámetro, el SQL se ejecuta como propietario de la base de datos. El modo de solo lectura sigue envolviendo las consultas en una transacción READ ONLY; el rol fijado añade una restricción que Postgres aplica al inicio de sesión, de modo que el SQL que salga de la transacción seguirá teniendo únicamente los privilegios de ese rol.

• El servidor resuelve internamente las credenciales del rol y nunca las devuelve. get_connection_string no está disponible en una conexión fijada.
• Se rechaza un argumento de herramienta role_name que difiera del rol fijado. Si se omite, se usa el rol fijado, nunca el propietario.
• Si el rol no existe o no puede iniciar sesión (por ejemplo, ALTER ROLE … NOLOGIN), la llamada falla antes de ejecutar cualquier SQL. No se vuelve a intentar con otro rol.
• El valor debe ser un nombre exacto de rol de Postgres: letras, dígitos, _ o $, y debe empezar por una letra o _; puede tener como máximo 63 caracteres. Cualquier otra cosa (vacío, repetido, entre comillas o con guiones) se rechaza con 400; no se ignora.
• El rol debe poder iniciar sesión (LOGIN) y debe existir en cada rama que consultes. Los roles creados en SQL (CREATE ROLE app_reader LOGIN PASSWORD '…') funcionan, al igual que los creados en Neon Console o mediante la API. Para que la fijación sea útil, el rol debe tener los privilegios que necesita y ninguno más: para agentes de solo lectura, concede SELECT en las tablas que deban ver y no lo añadas a neon_superuser. create_postgres_role con access: "read_only" crea un rol de este tipo desde una conexión sin roleName; los roles que crea sin access se incorporan a neon_superuser.
• OAuth: roleName en la URL de MCP establece una concesión fija. La página de autorización muestra el rol y el token emitido lo conserva al renovarse. Cambiar la URL más adelante no cambia el token; vuelve a autorizarte. Con la URL predeterminada (consentimiento editable), introduce el rol en el campo opcional Postgres role; déjalo vacío para conservar el propietario de la base de datos. Los tokens emitidos antes de esta opción no tienen un rol fijado y funcionan como antes.
• Clave de API: el rol se lee de la URL en cada solicitud. Cualquiera que pueda editar la URL de conexión y tenga la clave de API puede cambiarlo o quitarlo, así que mantén la URL en una configuración que el agente no controle.
• La fijación solo se aplica a las conexiones SQL. Las herramientas de la API de administración siguen actuando con el acceso propio de la clave de API o del token OAuth; compare_database_schema, por ejemplo, lo calcula la API de Neon y no está limitado por los permisos del rol. Combina roleName con readonly=true y category para limitar también esas herramientas.

Puedes obtener una vista previa de las herramientas visibles para cualquier configuración mediante el endpoint /api/list-tools (no requiere autenticación):

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

Herramientas disponibles en modo de solo lectura

Herramientas del host: 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.

Herramientas generadas de la API de administración que son GET y no devuelven secretos, además de query_logs (POST, de solo lectura). Obtén una vista previa del conjunto exacto con /api/list-tools?readonly=true.

Herramientas que requieren acceso de escritura:

• Escrituras generadas de la API de administración (create_project, create_branch, delete_project, …)
• get_connection_string (la cadena de conexión contiene la contraseña de un rol con privilegios, por lo que se oculta en el modo de solo lectura; cópiala desde Neon Console en su lugar)
• run_sql_transaction (sus instrucciones se ejecutan en una sola sesión, por lo que una instrucción COMMIT o SET TRANSACTION READ WRITE finalizaría la transacción de solo lectura)
• prepare_database_migration, complete_database_migration
• prepare_query_tuning, complete_query_tuning

Compatibilidad de transporte

https://mcp.neon.tech/mcp usa HTTP Streamable sin estado. Admite el protocolo MCP 2026-07-28 y una alternativa sin estado para clientes de la era de 2025. Los endpoints HTTP+SSE /sse y /message, obsoletos, devuelven 410 Gone.

Conecta los clientes HTTP Streamable a https://mcp.neon.tech/mcp. Para los clientes que solo admiten servidores locales stdio, añade esto a la configuración del cliente para que mcp-remote actúe como puente hacia HTTP Streamable:

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

Una solicitud con un encabezado Origin mal formado recibe 403 Forbidden. Se acepta cualquier origen serializado, incluidas páginas web, extensiones del navegador, vistas web de escritorio y null, por lo que los clientes basados en navegador pueden conectarse. Las solicitudes sin Origin no se ven afectadas.

Arquitectura del servidor remoto

El servidor remoto se ejecuta como una aplicación Next.js App Router en Vercel en mcp.neon.tech.

[!NOTE] La ruta raíz / redirige a la documentación de Neon MCP Server. No hay página de inicio.

Áreas principales de implementación:

• app/api/[transport]/route.ts: endpoint HTTP Streamable sin estado (/mcp)
• app/api/authorize/, app/callback/, app/api/token/, app/api/revoke/: endpoints del flujo OAuth
• app/.well-known/: endpoints de metadatos de descubrimiento de OAuth
• mcp/: servidor MCP, herramientas, controladores, analíticas e integración con Sentry
• lib/: funciones auxiliares compatibles con Next.js (OAuth, configuración, gestión de errores)
• mcp/utils/read-only.ts: modo de solo lectura y gestión de ámbitos

Guías

• Guía de Neon MCP Server
• Conectar clientes MCP a Neon
• Cursor con Neon MCP Server
• Claude Code con Neon MCP Server
• Claude Desktop con Neon MCP Server
• Cline con Neon MCP Server
• Windsurf con Neon MCP Server
• Zed con Neon MCP Server

Funciones

Herramientas admitidas

Neon MCP Server proporciona las siguientes acciones, que se exponen como «herramientas» para los clientes MCP. Puedes usar estas herramientas para interactuar con tus proyectos y bases de datos de Neon mediante comandos en lenguaje natural.

Metadatos del ámbito de las herramientas

Cada definición de herramienta incluye una categoría scope que se usa para filtrar herramientas según las concesiones y para la experiencia de consentimiento. Las categorías actuales son:

• projects
• branches
• endpoints
• snapshots
• schema
• querying
• neon_auth
• data_api
• observability
• docs
• functions
• storage
• realtime
• null (herramientas sin categoría de ámbito: search, fetch, send_feedback)

Notas:

• Las herramientas de la API de administración proceden de @neon/tools. Los selectores son rutas del SDK (projects.list); los nombres publicados en MCP empiezan por el verbo (list_projects, delete_project, query_logs). Los nombres históricos se mantienen donde ya existían (describe_project, create_branch, reset_from_parent, compare_database_schema, provision_neon_auth, provision_neon_data_api, list_branch_computes).
• ?category=branches incluye herramientas de ramas, roles y bases de datos (list_postgres_roles, create_postgres_database, …). Un token ya emitido para branches obtiene acceso a esas escrituras. La lista de cómputos es ?category=endpoints. La restauración de instantáneas es ?category=snapshots.
• Las escrituras de miembros y permisos del proyecto no se publican. list_project_members y list_project_permissions son operaciones de lectura.
• Las herramientas de esquema (?category=schema) son las herramientas del host get_database_tables y describe_table_schema, además de compare_database_schema, que se genera.
• La aplicación del modo de solo lectura sigue dependiendo de readOnlySafe y de la lógica de solo lectura del servidor; scope son metadatos de categoría, no un interruptor independiente de lectura/escritura.
• En el modo con ámbito de proyecto (?projectId=...), se ocultan las herramientas sin una ruta de proyecto (list_projects, count_projects, create_project, get_project_consumption, get_branch_consumption, list_organizations, list_regions, search, fetch, …). También se oculta delete_project.

Administración de proyectos:

• list_projects: Muestra los proyectos de Neon. limit limita la cantidad de elementos devueltos.
• count_projects: Devuelve el número de proyectos activos de una organización. org_id es opcional y se resuelve del mismo modo que en list_projects.
• describe_project: Obtiene un proyecto de Neon por su id ({ "project_id": "…" }).
• get_project_consumption, get_branch_consumption: Métricas de consumo por proyecto o rama, agrupadas por período de facturación. Aceptan org_id, metrics, from, to y granularity, y requieren un plan Launch, Scale, Agent, Business o Enterprise. get_branch_consumption también requiere project_ids, rechaza las métricas extra_branches_month y snapshot_storage_bytes_month, y no está disponible en el plan Business. El endpoint del plan heredado /consumption_history/projects no se publica.
• create_project: Crea un proyecto de Neon y espera a que esté listo el cómputo predeterminado. No devuelve una cadena de conexión. Los argumentos son { "name": "…", "org_id": "…", "region_id": "…" }. Cuando se complete correctamente, llama a get_connection_string.
• delete_project: Elimina un proyecto de Neon existente. Los argumentos son { "project_id": "…" }.
• list_organizations: Muestra todas las organizaciones a las que tiene acceso el usuario actual. Opcionalmente, filtra por nombre o ID de organización mediante el parámetro de búsqueda.

Administración de ramas:

• list_branches: Muestra las ramas de un proyecto. Úsalo para resolver el nombre de una rama y obtener su id br-….
• list_credentials, create_credential, revoke_credential, rotate_credential: Credenciales con ámbito de rama para Object Storage y AI Gateway. reveal no es una herramienta; la rotación reemplaza los secretos en el mismo lugar y no es idempotente.
• create_branch: Crea una rama con un cómputo de lectura y escritura y espera a que esté lista. No devuelve una cadena de conexión. Los argumentos son { "project_id": "…", "name": "feature-x" }. Pasa no_compute: true para omitir el endpoint. Cuando se complete correctamente, llama a get_connection_string.
• reset_from_parent: Restablece una rama al HEAD actual de su rama principal ({ "project_id": "…", "branch_id": "br-…" }). Descarta las escrituras realizadas desde que la rama se separó. preserve_under_name es obligatorio si la rama tiene ramas secundarias; estas se trasladan a la nueva rama. Solo se usa el HEAD de la rama principal; para restaurar a un momento específico, usa restore_snapshot.
• delete_branch: Elimina una rama ({ "project_id": "…", "branch_id": "br-…" }).
• describe_branch: Recupera un árbol de bases de datos, esquemas, tablas, vistas y funciones de una rama.
• Las herramientas generadas para ramas reciben branch_id como id de rama (br-...), no como nombre.
• restore_snapshot: Restaura una instantánea. Pasa target_branch_id para restaurarla en una rama existente; omítelo para crear una nueva.

Endpoints de cómputo (?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

Instantáneas (?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: Diferencia SQL del esquema de una base de datos con respecto a otra rama. database_name es obligatorio. Si se omite base_branch_id, se compara con la rama principal. Los parámetros opcionales lsn, timestamp, base_lsn, base_timestamp solo se aplican a un momento específico.

Ejecución de consultas SQL:

• get_connection_string: Devuelve la cadena de conexión de tu base de datos.
• run_sql: Ejecuta una sola consulta SQL en una base de datos de Neon especificada. Admite operaciones de lectura y escritura. El parámetro opcional role_name inicia sesión como ese rol de Postgres en lugar de como propietario de la base de datos, y compute_id selecciona el cómputo; las credenciales permanecen en el servidor. En una conexión con ?roleName=, se debe omitir role_name o hacer que coincida con ella.
• run_sql_transaction: Ejecuta una serie de consultas SQL dentro de una sola transacción en una base de datos de Neon. Acepta los mismos parámetros opcionales role_name y compute_id que run_sql.
• get_database_tables: Muestra todas las tablas de una base de datos de Neon especificada.
• describe_table_schema: Recupera la definición del esquema de una tabla específica, con detalles de las columnas, los tipos de datos y las restricciones.

Migraciones de bases de datos (cambios de esquema):

• prepare_database_migration: Inicia un proceso de migración de base de datos. Es importante destacar que crea una rama temporal para aplicar y probar la migración de forma segura antes de afectar a la rama principal.
• complete_database_migration: Finaliza y aplica una migración de base de datos preparada a la rama principal. Esta acción combina los cambios de la rama temporal de migración y limpia los recursos temporales.

Consultas y optimización de SQL:

• inspect_database: Ejecuta uno de los 15 diagnósticos predefinidos de solo lectura de Postgres en una rama: tamaños de relaciones e índices, uso de índices y escaneos secuenciales, consultas y bloqueos activos, las consultas más pesadas y frecuentes, tasa de aciertos de caché y tamaño del conjunto de trabajo, estimaciones de autovacuum y bloat, y estado de la replicación. Son las mismas comprobaciones que el comando de CLI neon inspect db. Omite database_name para abarcar todas las bases de datos de la rama; indica un nombre para inspeccionar una. Cuatro de ellas requieren la extensión pg_stat_statements o neon.
• list_slow_queries: Identifica los cuellos de botella de rendimiento al encontrar las consultas más lentas de una base de datos. Requiere la extensión pg_stat_statements.
• explain_sql_statement: Proporciona planes de ejecución detallados para consultas SQL con el fin de ayudar a identificar cuellos de botella de rendimiento.
• prepare_query_tuning: Analiza el rendimiento de las consultas y sugiere optimizaciones, como la creación de índices. Crea una rama temporal para probar estas optimizaciones de forma segura.
• complete_query_tuning: Finaliza el ajuste de consultas aplicando las optimizaciones a la rama principal o descartándolas. Limpia la rama temporal de ajuste.

Neon Auth (?category=neon_auth):

• provision_neon_auth, get_auth, disable_auth, update_auth_config
• get_neon_auth_config: herramienta del host; los secretos se ocultan. Lee los orígenes de confianza, el acceso a localhost, el correo electrónico y la contraseña, los proveedores de OAuth, el proveedor de correo electrónico, la organización, los complementos de enlace mágico y número de teléfono, y el webhook.
• 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: Cambian esos ajustes. update_auth_webhooks reemplaza toda la configuración del webhook.
• list_auth_oauth_providers, add_auth_oauth_provider, update_auth_oauth_provider, delete_auth_oauth_provider
• get_auth_oauth_server, update_auth_oauth_server: Configuran Neon Auth como servidor de autorización OAuth 2.1 (también para servidores MCP). Es independiente de los proveedores de inicio de sesión social anteriores.
• 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: Administran los clientes OAuth de ese servidor. create_auth_oauth_client y rotate_auth_oauth_client_secret devuelven el client_secret una 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: Administran la Data API de una base de datos de una rama.

Búsqueda y descubrimiento:

• search: Busca en organizaciones, proyectos y ramas que coincidan con una consulta. Devuelve los ID, los títulos y enlaces directos a Neon Console.
• fetch: Obtiene información detallada sobre una organización, proyecto o rama específicos mediante un ID (normalmente obtenido con la herramienta de búsqueda).

Comentarios (siempre disponible, incluido el endpoint ?category=docs sin inicio de sesión):

• send_feedback: Envía comentarios anónimos al equipo de Neon. Solo se envía el texto del comentario, sin datos de la cuenta, el proyecto ni la conexión. Los mensajes tienen un límite de 10.000 caracteres.

Observabilidad (?category=observability): estas herramientas requieren Neon Platform Beta y actualmente solo están disponibles para proyectos de la región aws-us-east-2. Una rama sin acceso a los registros devuelve HTTP 404 con el motivo telemetry_not_enabled.

• query_logs: Consulta los registros de OpenTelemetry de una rama. Usa POST en la Management API; este servidor la trata como de solo lectura.
• list_log_fields: Enumera los campos de registro cuyos valores se pueden enumerar en una rama.
• list_log_field_values: Enumera los valores distintos de un campo de registro dentro de una rama y un intervalo de tiempo.

Documentación y recursos (?category=docs):

• search_docs: Busca en neon.com (documentación, referencia de API, tutorial de PostgreSQL, guías, preguntas frecuentes, registro de cambios y blog) con la misma búsqueda que el cuadro de búsqueda de neon.com. Acepta query, categories opcional (docs, api, postgresql, guides, faqs, blog, changelog) y limit opcional (1-40, valor predeterminado: 10). Devuelve páginas ordenadas por relevancia con title, url, slug, category, breadcrumb, heading y excerpt; pasa slug a get_doc para leer la página.
• get_doc: Obtiene una página de neon.com en formato Markdown. Acepta slug de un resultado de search_docs (por ejemplo, docs/guides/prisma o postgresql/tutorial/inner-join).

Funciones (?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: Desencadenadores de funciones programadas (type: "schedule", cron UTC de cinco campos).

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

Tiempo real (?category=realtime):

• get_realtime, enable_realtime, disable_realtime: Estado de Realtime de la rama, habilitación (con allowed_origins opcional) y deshabilitación. La habilitación y la deshabilitación esperan hasta que se aplique el cambio.
• get_realtime_secret: El secreto compartido con el que el backend de la aplicación emite tokens de Realtime. No está disponible en modo de solo lectura.
• rotate_realtime_secret: Reemplaza el secreto compartido y espera hasta que se aplique el cambio. No es idempotente. Después, llama a get_realtime_secret para obtener el nuevo valor.

Migraciones

Las migraciones permiten administrar los cambios en el esquema de la base de datos a lo largo del tiempo. Con el servidor MCP de Neon, los LLM pueden realizar migraciones de forma segura mediante comandos separados de «Inicio» (prepare_database_migration) y «Confirmación» (complete_database_migration).

El comando «Inicio» acepta una migración y la ejecuta en una nueva rama temporal. Al finalizar, este comando indica al LLM que pruebe la migración en esa rama. A continuación, el LLM puede ejecutar el comando «Confirmación» para aplicar la migración a la rama original.

Desarrollo

Este proyecto usa pnpm como administrador de paquetes, fijado mediante Corepack.

Estructura del proyecto

El código del servidor MCP se encuentra en la raíz del repositorio. Es una aplicación Next.js implementada en Vercel en mcp.neon.tech.

corepack enable
pnpm install

Consulta CONTRIBUTING.md para saber cómo añadir herramientas. Los argumentos de las herramientas son snake_case.

Desarrollo local

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

Lint y comprobación de tipos

pnpm lint
pnpm typecheck

Variables de entorno

Obligatorias para el entorno de ejecución del servidor remoto:

Variable	Descripción
SERVER_HOST	URL del servidor (valor predeterminado: VERCEL_URL)
UPSTREAM_OAUTH_HOST	URL del proveedor de OAuth de Neon
CLIENT_ID	ID del cliente OAuth
CLIENT_SECRET	Secreto del cliente OAuth
KV_URL	URL de Upstash Redis (bloqueo transitorio)
OAUTH_DATABASE_URL	URL de Postgres para el almacenamiento de tokens

Opcionales:

Variable	Descripción
LOG_LEVEL	Nivel de registro de Winston: error, warn, info (predeterminado), debug, verbose, silly
NEON_MCP_DISABLE_ANALYTICS	Establécela en 1 para desactivar el análisis de producto

Pirámide de pruebas

Todas las pruebas se ejecutan desde la raíz del repositorio.

# 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

Estrategia de pruebas:

• Prioriza las pruebas E2E para el transporte, el protocolo y el comportamiento visible para el usuario.
• Usa pruebas de integración para los contratos deterministas de las herramientas y el comportamiento de los flujos de trabajo.
• Usa pruebas unitarias para la lógica pura y los casos límite.
• Evita depender de la disponibilidad de servicios de terceros en las pruebas que bloquean la integración de cambios; simula las dependencias externas en los niveles de integración y unitario.

Implementación

Vercel implementa automáticamente el servidor remoto a partir de la configuración de ramas del repositorio. Hay entornos de vista previa disponibles para las solicitudes de incorporación de cambios.

Telemetría

El servidor MCP de Neon recopila análisis de producto e informes de errores para ayudarnos a comprender el uso y mejorar la fiabilidad:

• Análisis de producto (Segment): cuando te conectas con una cuenta autenticada, el servidor envía un evento identify con el ID, el nombre y la dirección de correo electrónico de tu cuenta de Neon. También registra el inicio de sesión (server_init), cada llamada a una herramienta (tool_call) y los errores inesperados del servidor (server_error). Un evento de llamada a una herramienta incluye el nombre de la herramienta, el método de autenticación y el cliente, pero no los argumentos de la herramienta ni los resultados de las consultas. Las llamadas a herramientas de solo documentación sin una cuenta se registran de forma anónima. Los eventos se envían a track.neon.tech, el endpoint de análisis propio de Neon.
• Informes de errores (Sentry): los errores inesperados del servidor se notifican con trazas de pila y contexto de la solicitud.

Esta recopilación se rige por la Política de privacidad de Neon. Para desactivar el análisis al ejecutar el servidor por tu cuenta, establece NEON_MCP_DISABLE_ANALYTICS=1. Esta opción no desactiva Sentry.