Neon

Neon MCP 服务

Neon MCP 服务是一个开源工具，可让你通过自然语言与 Neon 上的 Lakebase Postgres 数据库交互。

模型上下文协议（MCP）是一种标准化协议，旨在管理大模型（LLM）与外部系统之间的上下文。此代码库为 Neon 提供远程 MCP 服务。

Neon 的 MCP 服务充当自然语言请求与 Neon API 之间的桥梁。它基于 MCP 构建，可将你的请求转换为必要的 API 调用，让你轻松管理创建项目和分支、运行查询以及执行数据库迁移等任务。

Neon MCP 服务的一些主要功能包括：

• **自然语言交互：**使用直观的对话式命令管理 Neon 数据库。
• **简化数据库管理：**无需编写 SQL 或直接使用 Neon API，即可执行复杂操作。
• **面向非开发者：**让不同技术背景的用户也能与 Neon 数据库交互。
• **支持数据库迁移：**利用 Neon 的分支功能，通过自然语言发起数据库架构更改。

例如，在 Claude Code 或任何 MCP 客户端中，你可以使用自然语言完成各种 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?

警告

Neon MCP 服务安全注意事项
Neon MCP 服务可通过自然语言请求提供强大的数据库管理功能。**执行前，务必检查并授权大模型请求的操作。**确保只有经过授权的用户和应用程序能够访问 Neon MCP 服务。

Neon MCP 服务仅用于本地开发和 IDE 集成。**我们不建议在生产环境中使用 Neon MCP 服务。**它可以执行可能导致意外或未经授权更改的强大操作。

如需了解更多信息，请参阅 MCP 安全指南 →。

设置 Neon MCP 服务

设置 Neon MCP 服务有几种方式：

1. 使用 API 密钥快速设置（Cursor、VS Code 和 Claude Code）： 运行 neon@latest init，即可通过一条命令自动配置 Neon 的 MCP 服务、Agent 技能和 VS Code 扩展。
2. 远程 MCP 服务（基于 OAuth 的身份验证）： 使用 OAuth 进行身份验证，连接到 Neon 托管的 MCP 服务。这种方式更方便，因为无需管理 API 密钥。此外，发布最新功能和改进后，你会自动获得这些更新。
3. 远程 MCP 服务（基于 API 密钥的身份验证）： 使用 API 密钥进行身份验证，连接到 Neon 托管的 MCP 服务。如果你想将远程 Agent 连接到 Neon，但无法使用 OAuth，这种方式很实用。此外，发布最新功能和改进后，你会自动获得这些更新。

前提条件

• 一个 MCP 客户端应用。
• 一个 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+（通过 Corepack 提供 pnpm — 运行 corepack enable 即可启用）。

选项 1：使用 API 密钥快速设置

不想手动创建 API 密钥？

运行 neon@latest init，即可通过一条命令自动配置 Neon 的 MCP 服务：

npx neon@latest init

此方法适用于 Cursor、VS Code（GitHub Copilot）和 Claude Code。它会通过 OAuth 进行身份验证，为你创建 Neon API 密钥，并自动配置编辑器。

选项 2：远程托管 MCP 服务（基于 OAuth 的身份验证）

使用 OAuth 进行身份验证，连接到 Neon 托管的 MCP 服务。这是最简单的设置方式，无需在本地安装此服务，也无需在客户端中配置 Neon API 密钥。

运行以下命令，为工作区中检测到的所有 Agent 和编辑器添加 Neon MCP 服务：

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 服务添加到全局 MCP 服务列表，而非仅限于当前项目。

或者，将以下 “Neon” 条目添加到客户端的 MCP 服务配置文件中（例如 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： 将以下内容添加到 Kiro MCP 配置文件（全局配置使用 ~/.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 顶部的一键安装按钮。更多信息请参阅 Kiro MCP 文档。

• 重启或刷新 MCP 客户端。
• 浏览器中会打开 OAuth 窗口。按照提示授权 MCP 客户端访问你的 Neon 账户。

使用基于 OAuth 的身份验证时，MCP 服务默认会对你的个人 Neon 账户下的项目进行操作。如需访问或管理属于某个组织的项目，必须在发送给 MCP 客户端的提示词中明确提供 org_id 或 project_id。

选项 3. 远程托管 MCP 服务（基于 API 密钥的身份验证）

如果客户端支持，远程 MCP 服务也支持使用 Authorization 标头中的 API 密钥进行身份验证。

在 Neon 控制台中创建 Neon API 密钥。接下来，运行以下命令，为工作区中检测到的所有 Agent 和编辑器添加 Neon MCP 服务：

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 服务配置文件中（例如，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 客户端可以请求这些范围，也可以在 OAuth 权限界面中进行选择。如果客户端仍发送 *，则会将其视为写入权限。

只读模式会限制可用工具，禁用创建项目、分支或运行迁移等写入操作。只读工具包括列出项目、描述架构、查询数据和查看性能指标。

你可以通过以下两种方式设置只读模式：

1. 默认 MCP URL（可编辑授权）： 使用 https://mcp.neon.tech/mcp 连接，并在授权页面取消勾选 允许写入。你也可以在此处选择一个项目、用于 SQL 的 Postgres 角色，以及部分工具类别。
2. 带参数的 MCP URL（固定授权）： 在 MCP 服务 URL 中添加 readonly、projectId、category 和／或 roleName。授权页面会确认该授权，不提供编辑选项。要更改授权，请修改 URL 并重新授权。

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

查询参数的行为方式如下：

• API 密钥流程： readonly=true 是启用只读模式的方式（此流程中没有 OAuth 范围交换）。URL 更改会在下一个请求中生效。
• OAuth 流程： MCP URL 中的 projectId、category、readonly 和 roleName 是在授权时确认的固定授权。readonly=true 无法在该页面上扩展为写入权限。颁发令牌后，更改 URL 不会扩展该令牌的权限；请重新授权。

对于 OAuth 注册，x-read-only 是可编辑授权页面上「允许写入」选项的初始默认值。它不会锁定确认操作，也不会覆盖包含 readonly=false 的带参数 URL。对于 API 密钥请求，每个请求仍会遵循 x-read-only；但其优先级低于 readonly 查询参数。

注意： 只读模式会限制可用的 工具。run_sql 仍然可用，并会在 READ ONLY 事务中运行每个查询。run_sql_transaction 不可用；请使用 run_sql 运行每条语句。这些调用会分别运行，不共享事务。如需事务语义，请使用允许写入的连接。

用于访问控制的 URL 查询参数

授权上下文（范围类别、项目范围、只读模式、固定的 Postgres 角色）通过 MCP 服务 URL 上的 URL 查询参数配置。API 密钥请求会在每个请求中应用这些参数。OAuth 令牌会保存授权时确认或编辑的授权内容。

参数	说明	示例
readonly	启用只读模式（true／false）	?readonly=true
category	限制为特定工具类别（可重复使用或使用 CSV）	?category=querying&category=schema
projectId	将所有操作限制在单个项目内	?projectId=proj-123
roleName	使用此 Postgres 角色运行所有 SQL，而不是使用所有者角色	?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 角色的示例（只读、单个项目、使用 app_reader 运行 SQL）：

{
  "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 授予的权限决定了 Agent 可以读取或更改哪些内容。如果不设置，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 中创建的角色均可使用。要让固定角色发挥作用，应只授予它所需的权限，不要授予更多权限：对于只读 Agent，请在它们应能查看的表上授予 SELECT，并且不要将其添加到 neon_superuser。
• OAuth： MCP URL 中的 roleName 会固定授权角色。授权页面会显示该角色，签发的令牌在刷新后仍会保留该角色。之后更改 URL 不会改变令牌；请重新授权。使用默认 URL（可编辑授权）时，请在可选的 Postgres role 字段中输入角色；留空则继续使用数据库所有者。在启用此选项之前签发的令牌没有固定角色，行为与以前相同。
• API 密钥： 每次请求都会从 URL 中读取角色。任何能够编辑连接 URL 且持有 API 密钥的人都可以更改或移除此角色，因此请将 URL 保存在 Agent 无法控制的配置中。
• 固定角色仅适用于 SQL 连接。管理 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。

生成的管理 API 工具中，使用 GET 且不返回机密的工具，以及 query_logs（POST，只读）。使用 /api/list-tools?readonly=true 预览确切的工具集合。

需要写入权限的工具：

• 生成的管理 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

### 服务器发送事件（SSE）传输（已弃用）

MCP 支持两种远程服务传输方式：已弃用的服务器发送事件（SSE）和较新的推荐方式 Streamable HTTP。如果你的 LLM 客户端尚不支持 Streamable HTTP，可以将端点从 https://mcp.neon.tech/mcp 切换为 https://mcp.neon.tech/sse，改用 SSE。

运行以下命令，使用 SSE 传输方式为工作区中检测到的所有 Agent 和编辑器添加 Neon MCP 服务：

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

远程服务架构

远程服务作为 Next.js App Router 应用运行在 Vercel 上，地址为 mcp.neon.tech。

说明

根路径 / 会重定向到 Neon MCP Server 文档。此处没有落地页。

核心实现区域：

• app/api/[transport]/route.ts：Streamable HTTP（/mcp）和 SSE（/sse）的 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 服务指南
• 将 MCP 客户端连接到 Neon
• 使用 Neon MCP 服务的 Cursor
• 使用 Neon MCP 服务的 Claude Code
• 使用 Neon MCP 服务的 Claude Desktop
• 使用 Neon MCP 服务的 Cline
• 使用 Neon MCP 服务的 Windsurf
• 使用 Neon MCP 服务的 Zed

功能

支持的工具

Neon MCP 服务提供以下操作，并将其作为“工具”开放给 MCP 客户端。你可以使用这些工具，通过自然语言命令与 Neon 项目和数据库交互。

工具范围元数据

每个工具定义都包含一个 scope 类别，用于基于授权的工具筛选和授权确认 UX。当前类别包括：

• projects
• branches
• endpoints
• snapshots
• schema
• querying
• neon_auth
• data_api
• observability
• docs
• functions
• storage
• realtime
• null（无范围类别的工具：search、fetch、send_feedback）

说明：

• 管理 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、create_project、list_organizations、list_regions、search、fetch，等等）会被隐藏。delete_project 也会被隐藏。

项目管理：

• list_projects：列出 Neon 项目。limit 用于限制返回的项目数量。
• describe_project：按 ID 获取 Neon 项目（{ "project_id": "…" }）。
• create_project：创建 Neon 项目，并等待默认计算资源就绪。不会返回连接字符串。参数为 { "name": "…", "org_id": "…", "region_id": "…" }。创建成功后调用 get_connection_string。
• delete_project：删除现有 Neon 项目。参数为 { "project_id": "…" }。
• list_organizations：列出当前用户有权访问的所有组织。可选使用搜索参数按组织名称或 ID 筛选。

分支管理：

• list_branches：列出项目中的分支。用于将分支名称解析为 br-… ID。
• list_credentials、create_credential、revoke_credential、rotate_credential：用于对象存储和 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：获取分支上的数据库、架构、表、视图和函数的树状结构。
• 生成的分支工具需要传入分支 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：针对指定的 Neon 数据库执行一条 SQL 查询。支持读写操作。可选的 role_name 用于以该 Postgres 角色而非数据库所有者身份登录，compute_id 用于选择计算资源；凭据保留在服务端。如果连接中包含 ?roleName=，则必须省略 role_name，或使其与该值一致。
• run_sql_transaction：在单个事务中针对 Neon 数据库执行一系列 SQL 查询。接受与 run_sql 相同的可选参数 role_name 和 compute_id。
• get_database_tables：列出指定 Neon 数据库中的所有表。
• describe_table_schema：获取指定表的架构定义，包括列、数据类型和约束。

数据库迁移（架构更改）：

• prepare_database_migration：启动数据库迁移流程。重要的是，它会创建一个临时分支，以便在影响主分支之前安全地应用和测试迁移。
• complete_database_migration：完成并将已准备好的数据库迁移应用到主分支。此操作会合并临时迁移分支中的更改，并清理临时资源。

SQL 查询与优化：

• inspect_database：对某个分支运行 15 项预定义的 Postgres 只读诊断之一，涵盖关系和索引大小、索引和顺序扫描使用情况、活动查询和锁、最耗时和最频繁的查询、缓存命中率和工作集大小、autovacuum 和膨胀估算，以及复制状态。执行的检查与 neon inspect db CLI 命令相同。省略 database_name 可检查分支上的所有数据库；传入名称则检查单个数据库。其中 4 项需要 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：宿主工具；机密信息会经过脱敏处理。请使用生成的 Auth 写入工具更改设置。
• list_auth_oauth_providers、add_auth_oauth_provider、update_auth_oauth_provider、delete_auth_oauth_provider
• 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：搜索与查询匹配的组织、项目和分支。返回 ID、标题以及指向 Neon Console 的直接链接。
• fetch：使用 ID（通常来自搜索工具）获取特定组织、项目或分支的详细信息。

反馈（始终可用，包括无需登录的 ?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；此服务将其视为只读操作。
• list_log_fields：列出可在分支上枚举值的日志字段。
• list_log_field_values：列出分支在指定时间范围内某个日志字段的不同值。

文档与资源（?category=docs）：

• search_docs：使用与 neon.com 搜索框相同的搜索功能搜索 neon.com（文档、API 参考、PostgreSQL 教程、指南、常见问题、更新日志和博客）。接受 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：以 Markdown 格式获取一个 neon.com 页面。接受来自 search_docs 搜索结果的 slug（例如 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"，五字段 UTC cron）。

存储（?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

实时功能（?category=realtime）：

• get_realtime、enable_realtime、disable_realtime：获取分支实时功能状态、启用（可选 allowed_origins）和禁用。启用和禁用操作会等待变更生效。
• get_realtime_secret：应用后端用于签发实时功能令牌的共享密钥。只读模式下不可用。
• rotate_realtime_secret：替换共享密钥并等待变更生效。此操作不具幂等性。之后调用 get_realtime_secret 获取新值。

迁移

迁移是一种随时间管理数据库架构变更的方式。借助 Neon MCP 服务，大模型可以通过分开的“开始”（prepare_database_migration）和“提交”（complete_database_migration）命令安全地执行迁移。

“开始”命令接受一项迁移，并在新的临时分支中运行。命令返回后，会提示大模型在该分支上测试迁移。随后，大模型可以运行“提交”命令，将迁移应用到原始分支。

开发

本项目使用 pnpm 作为包管理器，并通过 Corepack 固定版本。

项目结构

MCP 服务代码位于仓库根目录。这是一个部署到 Vercel（地址为 mcp.neon.tech）的 Next.js 应用。

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	Neon OAuth 提供商 URL
CLIENT_ID	OAuth 客户端 ID
CLIENT_SECRET	OAuth 客户端密钥
KV_URL	Vercel KV（Upstash Redis）URL
OAUTH_DATABASE_URL	用于存储令牌的 Postgres URL

可选：

变量	描述
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）： 使用经过身份验证的账户连接时，服务会发送一个包含 Neon 账户 ID、姓名和电子邮件地址的 identify 事件。服务还会跟踪会话开始（server_init）、每次工具调用（tool_call）和意外的服务错误（server_error）。工具调用事件包含工具名称、身份验证方式和客户端，但不包含工具参数或查询结果。不使用账户的纯文档工具调用会以匿名方式跟踪。事件会发送到 Neon 自有的分析端点 track.neon.tech。
• 错误报告（Sentry）： 意外的服务错误会连同堆栈跟踪和请求上下文一起上报。

此类数据收集受 Neon 隐私政策约束。若要在自行运行服务时停用分析功能，请设置 NEON_MCP_DISABLE_ANALYTICS=1。此标记不会停用 Sentry。