Neon

официальный

Взаимодействие с бессерверной платформой Postgres Neon

Что можно делать с Neon MCP?

Создание проектов и веток — Попросите ассистента создать новый проект Postgres или ветку, например feature-x, для изменений схемы.
Выполнение SQL-запросов — Выполняйте отдельные запросы или транзакции из нескольких операторов в базе данных Neon и получайте строки в ответ.
Просмотр схем — Просматривайте список таблиц в базе данных и описание столбцов, типов данных и ограничений таблицы.
Безопасная миграция — Подготовьте миграцию во временной ветке, а затем завершите её, чтобы применить изменения к основной ветке.
Оптимизация медленных запросов — Находите медленные запросы, просматривайте планы выполнения и проверяйте предложенные оптимизации во временной ветке.
Сводка по проектам — Просматривайте список проектов Neon и описания веток, чтобы узнать, какие базы данных и таблицы содержит каждая из них.

Размещённый MCP-сервер

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

Устанавливается в Claude Code, Codex, Cursor и другие

Документация

Neon MCP Server

Neon MCP Server — это инструмент с открытым исходным кодом, который позволяет взаимодействовать с базами данных Lakebase Postgres на Neon на естественном языке.

Model Context Protocol (MCP) — это стандартизированный протокол, предназначенный для управления контекстом между большими языковыми моделями (LLM) и внешними системами. Этот репозиторий предоставляет удалённый MCP Server для Neon.

MCP Server Neon служит связующим звеном между запросами на естественном языке и Neon API. Созданный на основе MCP, он преобразует ваши запросы в необходимые вызовы API, позволяя без труда выполнять такие задачи, как создание проектов и веток, выполнение запросов и миграция баз данных.

Ключевые возможности MCP Server Neon:

Взаимодействие на естественном языке: управляйте базами данных Neon с помощью интуитивно понятных команд в разговорной форме.
Упрощённое управление базами данных: выполняйте сложные действия без написания SQL и прямого обращения к Neon API.
Доступность для пользователей без опыта разработки: пользователи с разным уровнем технической подготовки могут взаимодействовать с базами данных Neon.
Поддержка миграции баз данных: используйте возможности ветвления Neon для изменения схемы базы данных, инициируемого на естественном языке.

Например, в Claude Code или любом MCP Client можно использовать естественный язык для выполнения задач в Neon, например:

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]
Важные сведения о безопасности Neon MCP Server
Neon MCP Server предоставляет широкие возможности управления базами данных через запросы на естественном языке. Перед выполнением всегда проверяйте и подтверждайте действия, запрошенные LLM. Убедитесь, что доступ к Neon MCP Server есть только у авторизованных пользователей и приложений.

Neon MCP Server предназначен только для локальной разработки и интеграции со средами разработки. Мы не рекомендуем использовать Neon MCP Server в производственной среде. Он может выполнять мощные операции, способные привести к случайным или несанкционированным изменениям.

Дополнительные сведения см. в рекомендациях по безопасности MCP →.

Настройка Neon MCP Server

Настроить Neon MCP Server можно несколькими способами:

Быстрая настройка с помощью API-ключа (Cursor, VS Code и Claude Code): выполните neon@latest init, чтобы одной командой автоматически настроить MCP Server Neon, навыки агента и расширение VS Code.
Удалённый MCP Server (аутентификация на основе OAuth): подключитесь к управляемому MCP Server Neon с помощью OAuth. Этот способ удобнее, поскольку не требует управления API-ключами. Кроме того, вы будете автоматически получать новые функции и улучшения сразу после их выпуска.
Удалённый MCP Server (аутентификация на основе API-ключа): подключитесь к управляемому MCP Server Neon с помощью API-ключа. Этот способ подходит, если нужно подключить к Neon удалённого агента, для которого OAuth недоступен. Кроме того, вы будете автоматически получать новые функции и улучшения сразу после их выпуска.

Предварительные требования

Приложение MCP Client.
Учётная запись Neon.
Node.js (>= v18.0.0): загрузите с сайта nodejs.org.
Если включена функция IP Allow, добавьте 34.192.103.46 и 23.22.233.166 в список разрешённых адресов (mcp.neon.tech статических IP-адресов).

Для разработки потребуется Node.js 22+ (pnpm предоставляется через Corepack — выполните corepack enable, чтобы активировать его).

Вариант 1. Быстрая настройка с помощью API-ключа

Не хотите создавать API-ключ вручную?

Выполните neon@latest init, чтобы одной командой автоматически настроить MCP Server Neon:

npx neon@latest init

Этот способ работает с Cursor, VS Code (GitHub Copilot) и Claude Code. Аутентификация будет выполнена через OAuth, для вас будет создан API-ключ Neon, а редактор настроится автоматически.

Вариант 2. Размещённый удалённый MCP Server (аутентификация на основе OAuth)

Подключитесь к управляемому MCP Server Neon с помощью OAuth. Это самый простой способ настройки: не требуется локально устанавливать этот сервер или настраивать API-ключ Neon в клиенте.

Выполните следующую команду, чтобы добавить Neon MCP Server во все обнаруженные агенты и редакторы в рабочей области:

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

Этот URL предоставляет доступ к проектам, веткам, вычислительным конечным точкам, выполнению запросов и схемам. Предварительно просмотреть его можно с помощью /api/list-tools?category=projects&category=branches&category=endpoints&category=querying&category=schema. URL без фильтров предоставляет доступ ко всем категориям:

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

Добавьте флаг -g, чтобы добавить Neon MCP Server в глобальный список MCP Server, а не только для проекта.

Также можно добавить следующую запись «Neon» в файл конфигурации MCP Server клиента (например, 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: добавьте следующую запись в файл конфигурации MCP для Kiro (~/.kiro/settings/mcp.json для глобальной конфигурации или .kiro/settings/mcp.json для конфигурации проекта):

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

Или воспользуйтесь кнопкой установки в один клик в верхней части этого README. Дополнительные сведения см. в документации по MCP для Kiro.

Перезапустите или обновите MCP Client.
В браузере откроется окно OAuth. Следуйте инструкциям, чтобы разрешить MCP Client доступ к вашей учётной записи Neon.

При аутентификации на основе OAuth MCP Server по умолчанию работает с проектами в вашей личной учётной записи Neon. Чтобы получить доступ к проектам организации или управлять ими, необходимо явно указать в запросе к MCP Client либо org_id, либо project_id.

Вариант 3. Размещённый удалённый MCP Server (аутентификация на основе API-ключа)

Удалённый MCP Server также поддерживает аутентификацию с помощью API-ключа в заголовке Authorization, если клиент поддерживает такую возможность.

Создайте API-ключ Neon в Neon Console. Затем выполните следующую команду, чтобы добавить Neon MCP Server во все обнаруженные агенты и редакторы в рабочей области:

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

Также можно добавить следующую запись «Neon» в файл конфигурации MCP Server клиента (например, 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>"
      }
    }
  }
}

Укажите API-ключ организации, чтобы ограничить доступ только проектами этой организации.

Области доступа и режим только для чтения

Neon MCP объявляет области OAuth read и write. MCP Client может запросить их, либо их можно выбрать в интерфейсе разрешений OAuth. Если клиент по-прежнему отправляет *, он считается разрешением на запись.

Режим только для чтения ограничивает доступные инструменты, отключая операции записи, например создание проектов и веток или выполнение миграций. К инструментам только для чтения относятся просмотр списка проектов, описание схем, выполнение запросов к данным и просмотр показателей производительности.

Включить режим только для чтения можно двумя способами:

URL MCP по умолчанию (редактируемое подтверждение): подключитесь с помощью https://mcp.neon.tech/mcp и снимите флажок Разрешить запись на странице авторизации. Там же можно выбрать один проект, роль Postgres для SQL и подмножество категорий инструментов.
Параметризованный URL MCP (фиксированное подтверждение): добавьте readonly, projectId, category и/или roleName в URL MCP Server. На странице авторизации будет показано подтверждение этих разрешений, а возможность их редактирования будет недоступна. Чтобы изменить разрешения, измените URL и пройдите авторизацию повторно.

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

Поведение параметра запроса:

Поток с API-ключом: readonly=true — это способ включить режим только для чтения (в этом потоке обмена областями OAuth нет). Изменения URL применяются при следующем запросе.
Поток OAuth: параметры projectId, category, readonly и roleName в URL MCP задают фиксированный набор разрешений, подтверждаемый при авторизации. На этой странице нельзя расширить readonly=true до разрешения на запись. После выдачи токена изменение URL не расширит его разрешения — пройдите авторизацию повторно.

При регистрации OAuth x-read-only задаёт начальное значение по умолчанию для разрешения на запись при редактируемом подтверждении. Оно не блокирует изменение подтверждения и не ограничивает параметризованный URL, содержащий readonly=false. Запросы с API-ключом по-прежнему учитывают x-read-only для каждого запроса; этот параметр имеет приоритет над параметром запроса readonly.

Примечание: режим только для чтения ограничивает доступные инструменты. run_sql остаётся доступным и выполняет каждый запрос в транзакции READ ONLY. run_sql_transaction недоступен; выполняйте каждую инструкцию с помощью run_sql. Эти вызовы выполняются отдельно и не используют общую транзакцию. Чтобы обеспечить семантику транзакций, используйте подключение с разрешённой записью.

Параметры URL для управления доступом

Контекст разрешений (категории областей доступа, ограничение по проекту, режим только для чтения, закреплённая роль Postgres) настраивается с помощью параметров запроса в URL MCP Server. Для запросов с API-ключом эти параметры применяются при каждом запросе. В токенах OAuth сохраняются разрешения, подтверждённые или изменённые при авторизации.

Параметр	Описание	Пример
`readonly`	Включить режим только для чтения (`true`/`false`)	`?readonly=true`
`category`	Ограничить доступ определёнными категориями инструментов (повторяющиеся значения или CSV)	`?category=querying&category=schema`
`projectId`	Ограничить все операции одним проектом	`?projectId=proj-123`
`roleName`	Выполнять весь SQL от имени этой роли Postgres, а не владельца	`?roleName=app_reader`

Пример: режим только для чтения и ограничение одним проектом:

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

Пример фильтрации по категориям (только инструменты для запросов и схем):

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

Пример закреплённой роли Postgres (режим только для чтения, один проект, выполнение SQL от имени app_reader):

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

roleName закрепляет роль входа Postgres для всего подключения. Весь SQL, выполняемый сервером от вашего имени (run_sql, run_sql_transaction, explain_sql_statement, get_database_tables, describe_table_schema, describe_branch, list_slow_queries, inspect_database, а также SQL внутри миграций и настройки запросов), выполняется от имени этой роли. Поэтому доступ агента на чтение и изменение данных определяется разрешениями Postgres. Если этот параметр не задан, SQL выполняется от имени владельца базы данных. В режиме только для чтения запросы по-прежнему выполняются в транзакции READ ONLY; закреплённая роль добавляет ограничение, которое Postgres применяет непосредственно к учётной записи, поэтому даже если SQL выйдет за пределы транзакции, у него останутся только разрешения этой роли.

Сервер разрешает учетные данные роли внутри системы и никогда их не возвращает. get_connection_string недоступен для закрепленного подключения.
Аргумент инструмента role_name, отличающийся от закрепленной роли, отклоняется. Если его не указать, используется закрепленная роль, а не владелец.
Если роль не существует или не может войти в систему (например, ALTER ROLE … NOLOGIN), вызов завершается ошибкой до выполнения SQL. Повторной попытки с другой ролью не происходит.
Значение должно точно соответствовать имени роли Postgres: буквы, цифры, _ или $; начинаться с буквы или _; длина — не более 63 символов. Любое другое значение (пустое, повторяющееся, заключенное в кавычки, содержащее дефис) отклоняется с ошибкой 400, а не игнорируется.
Роль должна иметь возможность входа в систему (LOGIN) и существовать в каждой запрашиваемой ветке. Подойдут роли, созданные в SQL (CREATE ROLE app_reader LOGIN PASSWORD '…'), а также роли, созданные в Neon Console или через API. Закрепление полезно, когда у роли есть только необходимые ей привилегии: для агентов с доступом только на чтение предоставьте SELECT к таблицам, которые им следует видеть, и не добавляйте эту роль в neon_superuser. create_postgres_role с access: "read_only" создает такую роль из подключения без roleName; роли, созданные без access, входят в neon_superuser.
OAuth: roleName в URL MCP задает фиксированное разрешение. На странице авторизации отображается роль, и выданный токен сохраняет ее при обновлении. Последующее изменение URL не меняет токен; авторизуйтесь повторно. При использовании URL по умолчанию (с редактируемым согласием) укажите роль в необязательном поле Postgres role; оставьте его пустым, чтобы сохранить владельца базы данных. В токенах, выданных до появления этой возможности, закрепленной роли нет, и они работают как прежде.
Ключ API: роль считывается из URL при каждом запросе. Любой, кто может изменить URL подключения и располагает ключом API, может изменить или удалить роль, поэтому храните URL в конфигурации, которую агент не контролирует.
Закрепление применяется только к SQL-подключениям. Инструменты Management API по-прежнему используют собственные права доступа ключа API или токена OAuth; например, compare_database_schema вычисляется Neon API и не ограничивается привилегиями роли. Чтобы ограничить и эти инструменты, используйте roleName вместе с readonly=true и category.

Предварительно просмотреть инструменты, доступные при любой конфигурации, можно с помощью конечной точки /api/list-tools (авторизация не требуется):

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

Инструменты, доступные в режиме только для чтения

Пользовательские инструменты: 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.

Сгенерированные инструменты Management API, использующие GET и не возвращающие секреты, а также query_logs (POST, только чтение). Предварительно просмотреть точный набор можно с помощью /api/list-tools?readonly=true.

Инструменты, требующие доступа на запись:

Операции записи сгенерированного Management API (create_project, create_branch, delete_project, …)
get_connection_string (строка подключения содержит пароль привилегированной роли, поэтому в режиме только для чтения она не предоставляется; скопируйте ее из Neon Console)
run_sql_transaction (его инструкции выполняются в одном сеансе, поэтому инструкция COMMIT или SET TRANSACTION READ WRITE завершила бы транзакцию только для чтения)
prepare_database_migration, complete_database_migration
prepare_query_tuning, complete_query_tuning

Совместимость транспортов

https://mcp.neon.tech/mcp использует не сохраняющий состояние Streamable HTTP. Он поддерживает протокол MCP 2026-07-28 и не сохраняющий состояние резервный режим для клиентов эпохи 2025 года. Устаревшие конечные точки HTTP+SSE /sse и /message возвращают 410 Gone.

Подключайте клиенты Streamable HTTP к https://mcp.neon.tech/mcp. Для клиентов, поддерживающих только локальные серверы stdio, добавьте это в конфигурацию клиента, чтобы mcp-remote обеспечивал взаимодействие с Streamable HTTP:

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

Запрос с некорректным заголовком Origin получает ответ 403 Forbidden. Принимается любое сериализованное значение origin, включая веб-страницы, расширения браузера, встроенные веб-представления настольных приложений и null, поэтому клиенты на основе браузера могут подключаться. Запросы без Origin не затрагиваются.

Архитектура удаленного сервера

Удаленный сервер работает как приложение Next.js App Router на Vercel по адресу mcp.neon.tech.

[!NOTE] Корневой путь / перенаправляет на документацию Neon MCP Server. Стартовой страницы нет.

Основные компоненты реализации:

app/api/[transport]/route.ts: конечная точка Streamable HTTP без сохранения состояния (/mcp)
app/api/authorize/, app/callback/, app/api/token/, app/api/revoke/: конечные точки потока OAuth
app/.well-known/: конечные точки метаданных обнаружения OAuth
mcp/: MCP-сервер, инструменты, обработчики, аналитика и интеграция с Sentry
lib/: вспомогательные средства, совместимые с Next.js (OAuth, конфигурация, обработка ошибок)
mcp/utils/read-only.ts: режим только для чтения и обработка областей доступа

Руководства

Возможности

Поддерживаемые инструменты

Neon MCP Server предоставляет следующие действия, доступные клиентам MCP в виде «инструментов». С помощью этих инструментов можно взаимодействовать с проектами и базами данных Neon, используя команды на естественном языке.

Метаданные областей действия инструментов

Определение каждого инструмента включает категорию scope, используемую для фильтрации инструментов на основе разрешений и интерфейса согласия. Текущие категории:

projects
branches
endpoints
snapshots
schema
querying
neon_auth
data_api
observability
docs
functions
storage
realtime
null (инструменты без категории области действия: search, fetch, send_feedback)

Примечания:

Инструменты Management API формируются из @neon/tools. Селекторы — это пути SDK (projects.list); опубликованные имена MCP начинаются с глагола (list_projects, delete_project, query_logs). Исторические имена сохраняются там, где они уже использовались (describe_project, create_branch, reset_from_parent, compare_database_schema, provision_neon_auth, provision_neon_data_api, list_branch_computes).
?category=branches включает инструменты для веток, ролей и баз данных (list_postgres_roles, create_postgres_database, …). Токен, уже выданный для branches, получает доступ к этим операциям записи. Получение списка вычислительных ресурсов — ?category=endpoints. Восстановление снимка — ?category=snapshots.
Операции записи для участников проекта и разрешений не публикуются. list_project_members и list_project_permissions предназначены для чтения.
Инструменты схемы (?category=schema) — это get_database_tables и describe_table_schema, а также сгенерированный compare_database_schema.
Принудительное ограничение доступа только для чтения по-прежнему опирается на readOnlySafe и логику только для чтения на стороне сервера; scope — это метаданные категории, а не самостоятельный переключатель чтения/записи.
В режиме с областью действия проекта (?projectId=...) скрываются инструменты без пути проекта (list_projects, count_projects, create_project, get_project_consumption, get_branch_consumption, list_organizations, list_regions, search, fetch, …). delete_project также скрывается.

Управление проектами:

list_projects: выводит список проектов Neon. limit ограничивает количество возвращаемых элементов.
count_projects: возвращает количество активных проектов в организации. Параметр org_id необязателен и разрешается так же, как в list_projects.
describe_project: получает проект Neon по идентификатору ({ "project_id": "…" }).
get_project_consumption, get_branch_consumption: метрики потребления по проекту или ветке с группировкой по расчетному периоду. Принимают org_id, metrics, from, to и granularity; для их использования требуется план Launch, Scale, Agent, Business или Enterprise. Для get_branch_consumption также требуется project_ids; он отклоняет метрики extra_branches_month и snapshot_storage_bytes_month и недоступен в плане Business. Конечная точка для устаревших планов /consumption_history/projects не публикуется.
create_project: создает проект Neon и ожидает запуска вычислительного ресурса по умолчанию. Строку подключения не возвращает. Аргументы: { "name": "…", "org_id": "…", "region_id": "…" }. После успешного выполнения вызовите get_connection_string.
delete_project: удаляет существующий проект Neon. Аргументы: { "project_id": "…" }.
list_organizations: выводит список всех организаций, к которым у текущего пользователя есть доступ. При необходимости можно отфильтровать список по названию или идентификатору организации с помощью параметра поиска.

Управление ветками:

list_branches: выводит список веток проекта. Используйте этот инструмент, чтобы сопоставить имя ветки с идентификатором br-….
list_credentials, create_credential, revoke_credential, rotate_credential: учетные данные для Object Storage и AI Gateway, привязанные к ветке. reveal — не инструмент; при ротации секреты заменяются на месте, и операция не является идемпотентной.
create_branch: создает ветку с вычислительным ресурсом для чтения и записи и ожидает ее готовности. Строку подключения не возвращает. Аргументы: { "project_id": "…", "name": "feature-x" }. Передайте no_compute: true, чтобы пропустить конечную точку. После успешного выполнения вызовите get_connection_string.
reset_from_parent: сбрасывает ветку до текущего HEAD родительской ветки ({ "project_id": "…", "branch_id": "br-…" }). Отменяет все записи, сделанные после отделения ветки. Если у ветки есть дочерние ветки, требуется preserve_under_name; эти дочерние ветки перемещаются в новую ветку. Используется только HEAD родительской ветки; для восстановления на определенный момент времени предназначен restore_snapshot.
delete_branch: удаляет ветку ({ "project_id": "…", "branch_id": "br-…" }).
describe_branch: получает дерево баз данных, схем, таблиц, представлений и функций в ветке.
Сгенерированные инструменты для веток принимают branch_id как идентификатор ветки (br-...), а не ее имя.
restore_snapshot: восстанавливает снимок. Передайте target_branch_id, чтобы восстановить его в существующую ветку; не указывайте этот параметр, чтобы создать новую.

Конечные точки вычислительных ресурсов (?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

Снимки (?category=snapshots):

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

Схема (?category=schema):

get_database_tables, describe_table_schema
compare_database_schema: сравнивает SQL-схему одной базы данных со схемой другой ветки. Требуется database_name. Если не указать base_branch_id, сравнение выполняется с родительской веткой. Необязательные параметры lsn, timestamp, base_lsn, base_timestamp доступны только для восстановления на определенный момент времени.

Выполнение SQL-запросов:

get_connection_string: Возвращает строку подключения к вашей базе данных.
run_sql: Выполняет один SQL-запрос к указанной базе данных Neon. Поддерживаются операции чтения и записи. Необязательный параметр role_name выполняет вход от имени этой роли Postgres вместо владельца базы данных, а compute_id выбирает вычислительный ресурс; учетные данные остаются на сервере. При подключении с ?roleName= параметр role_name нужно опустить или указать его значение. Возвращает массив строк, содержащий не более max_rows строк (по умолчанию 100, максимум 10 000); если часть строк была отсечена, во втором блоке содержимого возвращается { totalRowCount, truncated, note }. При ошибке запроса возвращаются SQLSTATE Postgres, позиция ошибки, а также любые сведения, подсказки или контекст.
run_sql_transaction: Выполняет серию SQL-запросов в рамках одной транзакции к базе данных Neon. Принимает те же необязательные параметры role_name, compute_id и max_rows, что и run_sql. Параметр max_rows применяется к каждому оператору; если какой-либо оператор был отсечен, во втором блоке содержится сводка по каждому оператору.
get_database_tables: Перечисляет все таблицы в указанной базе данных Neon.
describe_table_schema: Получает определение схемы конкретной таблицы с описанием столбцов, типов данных и ограничений.

Миграции базы данных (изменения схемы):

prepare_database_migration: Запускает процесс миграции базы данных. Важно: для безопасного применения и тестирования миграции перед внесением изменений в основную ветку создается временная ветка.
complete_database_migration: Завершает подготовленную миграцию базы данных и применяет ее к основной ветке. Это действие объединяет изменения из временной ветки миграции и удаляет временные ресурсы.

Выполнение SQL-запросов и оптимизация:

inspect_database: Запускает одну из 15 предопределенных диагностик Postgres только для чтения в ветке: размеры отношений и индексов, использование индексов и последовательного сканирования, активные запросы и блокировки, самые ресурсоемкие и частые запросы, коэффициент попаданий в кэш и размер рабочего набора, оценки autovacuum и раздувания, а также состояние репликации. Те же проверки, что и в команде CLI neon inspect db. Не указывайте database_name, чтобы проверить все базы данных в ветке; укажите имя, чтобы проверить одну базу. Для четырех проверок требуется расширение pg_stat_statements или neon.
list_slow_queries: Выявляет узкие места производительности, находя самые медленные запросы в базе данных. Требуется расширение pg_stat_statements.
explain_sql_statement: Предоставляет подробные планы выполнения SQL-запросов, помогающие выявить узкие места производительности.
prepare_query_tuning: Анализирует производительность запросов и предлагает оптимизации, например создание индексов. Создает временную ветку для безопасного тестирования этих оптимизаций.
complete_query_tuning: Завершает настройку запросов, применяя оптимизации к основной ветке или отменяя их. Удаляет временную ветку настройки.

Neon Auth (?category=neon_auth):

provision_neon_auth, get_auth, disable_auth, update_auth_config
get_neon_auth_config: Секреты скрыты. Читает доверенные источники, доступ с localhost, настройки электронной почты и пароля, провайдеров OAuth, провайдера электронной почты, плагины организации, magic link и номера телефона, вебхук и экспорт журналов.
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: Изменяют эти настройки. update_auth_webhooks заменяет всю конфигурацию вебхука. update_auth_logs_export включает или отключает экспорт событий Neon Auth в журналы Neon Platform; проект без экспорта журналов принимает только 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: Настраивают Neon Auth как сервер авторизации OAuth 2.1 (в том числе для MCP-серверов). Не связаны с указанными выше провайдерами входа через социальные сети.
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: Управляют OAuth-клиентами этого сервера. create_auth_oauth_client и rotate_auth_oauth_client_secret возвращают client_secret один раз.
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: Управляют Data API для базы данных ветки.

Поиск и обнаружение:

search: Выполняет поиск по организациям, проектам и веткам, соответствующим запросу. Возвращает идентификаторы, названия и прямые ссылки на Neon Console.
fetch: Получает подробную информацию о конкретной организации, проекте или ветке по идентификатору (обычно полученному с помощью инструмента поиска).

Обратная связь (всегда доступна, в том числе через конечную точку ?category=docs без входа):

send_feedback: Отправляет анонимный отзыв команде Neon. Отправляется только текст отзыва, без сведений об учетной записи, проекте или подключении. Максимальная длина сообщения — 10 000 символов.

Наблюдаемость (?category=observability): для этих инструментов требуется Neon Platform Beta; сейчас они доступны только для проектов в регионе aws-us-east-2. Для ветки без доступа к журналам возвращается HTTP 404 с причиной telemetry_not_enabled.

query_logs: Выполняет запросы к журналам OpenTelemetry для ветки. В Management API используется POST; этот сервер обрабатывает запрос как доступный только для чтения.
query_loki_logs: Выполняет запрос диапазона LogQL к API чтения ветки, совместимому с Loki, и возвращает ответ Loki: строки, сгруппированные по меткам потоков, с временными метками в наносекундах.
list_log_fields: Перечисляет поля журналов, для которых можно получить список значений в ветке.
list_log_field_values: Перечисляет уникальные значения поля журнала в ветке и временном интервале.

Документация и ресурсы (?category=docs):

search_docs: Выполняет поиск на neon.com (документация, справочник API, руководство по PostgreSQL, инструкции, часто задаваемые вопросы, журнал изменений и блог) так же, как поле поиска на neon.com. Принимает query, необязательный параметр categories (docs, api, postgresql, guides, faqs, blog, changelog) и необязательный параметр limit (1–40, по умолчанию 10). Возвращает ранжированные страницы с title, url, slug, category, breadcrumb, heading и excerpt; передайте slug в get_doc, чтобы прочитать страницу.
get_doc: Получает одну страницу neon.com в формате Markdown. Принимает slug из результата search_docs (например, docs/guides/prisma или postgresql/tutorial/inner-join).

Функции (?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: Триггеры запланированных функций (type: "schedule", cron с пятью полями в UTC).

Хранилище (?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

Realtime (?category=realtime):

get_realtime, enable_realtime, disable_realtime: Состояние Realtime ветки, включение (необязательный параметр allowed_origins) и отключение. При включении и отключении выполняется ожидание применения изменений.
get_realtime_secret: Общий секрет, с помощью которого сервер приложения выпускает токены Realtime. Недоступен в режиме только для чтения.
rotate_realtime_secret: Заменяет общий секрет и ожидает применения изменений. Не является идемпотентным. После этого вызовите get_realtime_secret, чтобы получить новое значение.

Миграции

Миграции позволяют управлять изменениями схемы базы данных с течением времени. С помощью сервера Neon MCP LLM могут безопасно выполнять миграции, используя отдельные команды «Start» (prepare_database_migration) и «Commit» (complete_database_migration).

Команда «Start» принимает миграцию и выполняет ее в новой временной ветке. После завершения команда подсказывает LLM протестировать миграцию в этой ветке. Затем LLM может выполнить команду «Commit», чтобы применить миграцию к исходной ветке.

Разработка

В этом проекте в качестве менеджера пакетов используется pnpm, закрепленный через Corepack.

Структура проекта

Код MCP-сервера находится в корне репозитория. Это приложение Next.js, развернутое на Vercel по адресу mcp.neon.tech.

corepack enable
pnpm install

Инструкции по добавлению инструментов см. в CONTRIBUTING.md. Аргументы инструментов — snake_case.

Локальная разработка

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

Проверка стиля и типов

pnpm lint
pnpm typecheck

Переменные окружения

Обязательны для удаленной среды выполнения сервера:

Переменная	Описание
`SERVER_HOST`	URL сервера (по умолчанию `VERCEL_URL`)
`UPSTREAM_OAUTH_HOST`	URL провайдера Neon OAuth
`CLIENT_ID`	Идентификатор клиента OAuth
`CLIENT_SECRET`	Секрет клиента OAuth
`KV_URL`	URL Upstash Redis (переходная блокировка)
`OAUTH_DATABASE_URL`	URL Postgres для хранения токенов

Необязательные:

Переменная	Описание
`LOG_LEVEL`	Уровень журналирования Winston: `error`, `warn`, `info` (по умолчанию), `debug`, `verbose`, `silly`
`NEON_MCP_DISABLE_ANALYTICS`	Установите значение `1`, чтобы отключить аналитику продукта

Пирамида тестирования

Все тесты запускаются из корня репозитория.

# 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

Стратегия тестирования:

Для проверки транспорта, протокола и поведения, видимого пользователю, отдавайте предпочтение E2E.
Используйте интеграционные тесты для проверки детерминированных контрактов инструментов и поведения рабочих процессов.
Используйте модульные тесты для проверки чистой логики и граничных случаев.
Не полагайтесь на доступность сторонних сервисов в тестах, блокирующих слияние; имитируйте внешние зависимости на уровнях интеграционных и модульных тестов.

Развертывание

Vercel автоматически развертывает удаленный сервер в соответствии с настройками ветки репозитория. Для запросов на слияние доступны предварительные среды.

Телеметрия

Сервер Neon MCP собирает продуктовую аналитику и отчеты об ошибках, чтобы помочь нам понять, как используется сервер, и повысить его надежность:

Продуктовая аналитика (Segment): при подключении с аутентифицированной учетной записью сервер отправляет событие identify с идентификатором учетной записи Neon, именем и адресом электронной почты. Также отслеживаются начало сеанса (server_init), каждый вызов инструмента (tool_call) и непредвиденные ошибки сервера (server_error). Событие вызова инструмента содержит название инструмента, метод аутентификации и клиент, но не аргументы инструмента и не результаты запросов. Вызовы инструментов, предназначенных только для документации, без учетной записи отслеживаются анонимно. Для страницы, отображаемой после авторизации, фиксируется факт показа (auth_complete_viewed, вместе с результатом и клиентом), а также использование ее кнопок и ссылок (auth_complete_action); браузер отправляет только случайный идентификатор просмотра страницы, но никогда не отправляет код авторизации или сведения о вашей личности. События отправляются на track.neon.tech, собственную конечную точку аналитики Neon.
Отчеты об ошибках, трассировки и журналы (Sentry): непредвиденные ошибки сервера отправляются вместе с трассировками стека, методом и путем запроса. Заголовки запросов, тела, файлы cookie и строки запроса не отправляются. Для каждого запроса и вызова инструмента создается трассировка с названием инструмента, названием клиента, идентификатором учетной записи и сведениями о том, завершился ли вызов ошибкой, а также с идентификатором сеанса, который сервер назначает клиентам эпохи 2025 года, и идентификатором беседы, который клиент передает в _meta.threadId. Трассировки не содержат аргументов инструментов или результатов. Журналы сервера также отправляются в Sentry. На эту коллекцию распространяется действие Политики конфиденциальности Neon. Чтобы отключить аналитику при самостоятельном запуске сервера, задайте NEON_MCP_DISABLE_ANALYTICS=1. Этот флаг не отключает Sentry.