Neon

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

Máy chủ MCP Neon

Máy chủ MCP Neon là một công cụ mã nguồn mở cho phép bạn tương tác với cơ sở dữ liệu Lakebase Postgres trên Neon bằng ngôn ngữ tự nhiên.

Giao thức Ngữ cảnh Mô hình (MCP) là một giao thức chuẩn hóa được thiết kế để quản lý ngữ cảnh giữa các mô hình ngôn ngữ lớn (LLM) và các hệ thống bên ngoài. Kho lưu trữ này cung cấp một Máy chủ MCP từ xa cho Neon.

Máy chủ MCP của Neon hoạt động như một cầu nối giữa các yêu cầu ngôn ngữ tự nhiên và API Neon. Được xây dựng trên MCP, nó dịch các yêu cầu của bạn thành các lệnh gọi API cần thiết, cho phép bạn quản lý các tác vụ như tạo dự án và nhánh, chạy truy vấn và thực hiện di chuyển cơ sở dữ liệu một cách liền mạch.

Một số tính năng chính của máy chủ MCP Neon bao gồm:

• Tương tác bằng ngôn ngữ tự nhiên: Quản lý cơ sở dữ liệu Neon bằng các lệnh hội thoại trực quan.
• Đơn giản hóa quản lý cơ sở dữ liệu: Thực hiện các hành động phức tạp mà không cần viết SQL hoặc sử dụng trực tiếp API Neon.
• Khả năng tiếp cận cho người không phải nhà phát triển: Trao quyền cho người dùng có nền tảng kỹ thuật đa dạng để tương tác với cơ sở dữ liệu Neon.
• Hỗ trợ di chuyển cơ sở dữ liệu: Tận dụng khả năng phân nhánh của Neon cho các thay đổi lược đồ cơ sở dữ liệu được khởi tạo qua ngôn ngữ tự nhiên.

Ví dụ: trong Claude Code hoặc bất kỳ Máy khách MCP nào, bạn có thể sử dụng ngôn ngữ tự nhiên để hoàn thành các việc với Neon, chẳng hạn như:

• 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]
Cân nhắc bảo mật Máy chủ MCP Neon
Máy chủ MCP Neon cung cấp khả năng quản lý cơ sở dữ liệu mạnh mẽ thông qua các yêu cầu ngôn ngữ tự nhiên. Luôn xem xét và ủy quyền các hành động được LLM yêu cầu trước khi thực thi. Đảm bảo rằng chỉ những người dùng và ứng dụng được ủy quyền mới có quyền truy cập vào Máy chủ MCP Neon.

Máy chủ MCP Neon chỉ dành cho phát triển cục bộ và tích hợp IDE. Chúng tôi không khuyến nghị sử dụng Máy chủ MCP Neon trong môi trường sản xuất. Nó có thể thực thi các thao tác mạnh mẽ có thể dẫn đến các thay đổi vô tình hoặc trái phép.

Để biết thêm thông tin, hãy xem hướng dẫn bảo mật MCP →.

Thiết lập Máy chủ MCP Neon

Có một số tùy chọn để thiết lập Máy chủ MCP Neon:

1. Thiết lập nhanh với Khóa API (Cursor, VS Code và Claude Code): Chạy neon@latest init để tự động cấu hình Máy chủ MCP của Neon, kỹ năng đại lý và tiện ích mở rộng VS Code chỉ bằng một lệnh.
2. Máy chủ MCP từ xa (Xác thực dựa trên OAuth): Kết nối với máy chủ MCP được quản lý của Neon bằng OAuth để xác thực. Phương pháp này thuận tiện hơn vì loại bỏ nhu cầu quản lý khóa API. Ngoài ra, bạn sẽ tự động nhận được các tính năng và cải tiến mới nhất ngay khi chúng được phát hành.
3. Máy chủ MCP từ xa (Xác thực dựa trên Khóa API): Kết nối với máy chủ MCP được quản lý của Neon bằng khóa API để xác thực. Phương pháp này hữu ích nếu bạn muốn kết nối một đại lý từ xa với Neon khi OAuth không khả dụng. Ngoài ra, bạn sẽ tự động nhận được các tính năng và cải tiến mới nhất ngay khi chúng được phát hành.

Điều kiện tiên quyết

• Một ứng dụng Máy khách MCP.
• Một tài khoản Neon.
• Node.js (>= v18.0.0): Tải xuống từ nodejs.org.
• Nếu IP Allow được bật, hãy thêm 34.192.103.46 và 23.22.233.166 vào danh sách cho phép của bạn (mcp.neon.tech IP tĩnh).

Đối với phát triển, bạn sẽ cần Node.js 22+ (pnpm được cung cấp qua Corepack — chạy corepack enable để kích hoạt nó).

Tùy chọn 1. Thiết lập nhanh với Khóa API

Không muốn tạo khóa API theo cách thủ công?

Chạy neon@latest init để tự động cấu hình Máy chủ MCP của Neon chỉ bằng một lệnh:

npx neon@latest init

Điều này hoạt động với Cursor, VS Code (GitHub Copilot) và Claude Code. Nó sẽ xác thực qua OAuth, tạo khóa API Neon cho bạn và cấu hình trình soạn thảo của bạn tự động.

Tùy chọn 2. Máy chủ MCP từ xa được lưu trữ (Xác thực dựa trên OAuth)

Kết nối với máy chủ MCP được quản lý của Neon bằng OAuth để xác thực. Đây là thiết lập dễ nhất, không yêu cầu cài đặt cục bộ máy chủ này và không cần khóa API Neon được cấu hình trong máy khách.

Chạy lệnh sau để thêm Máy chủ MCP Neon cho tất cả các đại lý và trình soạn thảo được phát hiện trong không gian làm việc của bạn:

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

URL đó xuất bản các dự án, nhánh, điểm cuối tính toán, truy vấn và lược đồ. Xem trước nó bằng /api/list-tools?category=projects&category=branches&category=endpoints&category=querying&category=schema. URL không lọc xuất bản mọi danh mục:

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

Thêm cờ -g để thêm Máy chủ MCP Neon vào danh sách máy chủ MCP toàn cục thay vì phạm vi dự án.

Ngoài ra, bạn có thể thêm mục "Neon" sau vào tệp cấu hình máy chủ MCP của máy khách (ví dụ: 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: Thêm nội dung sau vào tệp cấu hình MCP Kiro của bạn (~/.kiro/settings/mcp.json cho toàn cục hoặc .kiro/settings/mcp.json cho phạm vi dự án):

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

Hoặc sử dụng nút cài đặt một cú nhấp chuột ở đầu README này. Để biết thêm thông tin, hãy xem tài liệu MCP Kiro.

• Khởi động lại hoặc làm mới máy khách MCP của bạn.
• Một cửa sổ OAuth sẽ mở trong trình duyệt của bạn. Làm theo lời nhắc để ủy quyền cho máy khách MCP của bạn truy cập vào tài khoản Neon của bạn.

Với xác thực dựa trên OAuth, máy chủ MCP theo mặc định sẽ hoạt động trên các dự án thuộc tài khoản Neon cá nhân của bạn. Để truy cập hoặc quản lý các dự án thuộc về một tổ chức, bạn phải cung cấp rõ ràng org_id hoặc project_id trong lời nhắc của bạn cho máy khách MCP.

Tùy chọn 3. Máy chủ MCP từ xa được lưu trữ (Xác thực dựa trên Khóa API)

Máy chủ MCP từ xa cũng hỗ trợ xác thực bằng khóa API trong tiêu đề Authorization nếu máy khách của bạn hỗ trợ điều đó.

Tạo khóa API Neon trong Bảng điều khiển Neon. Tiếp theo, chạy lệnh sau để thêm Máy chủ MCP Neon cho tất cả các đại lý và trình soạn thảo được phát hiện trong không gian làm việc của bạn:

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

Ngoài ra, bạn có thể thêm mục "Neon" sau vào tệp cấu hình máy chủ MCP của máy khách (ví dụ: 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>"
      }
    }
  }
}

Cung cấp khóa API của tổ chức để giới hạn quyền truy cập chỉ vào các dự án thuộc tổ chức đó.

Phạm vi và Chế độ chỉ đọc

Neon MCP quảng cáo các phạm vi OAuth read và write. Máy khách MCP của bạn có thể yêu cầu các phạm vi này hoặc bạn có thể thực hiện lựa chọn trong giao diện quyền OAuth. * được coi là ghi nếu máy khách vẫn gửi nó.

Chế độ chỉ đọc giới hạn các công cụ khả dụng, vô hiệu hóa các thao tác ghi như tạo dự án, nhánh hoặc chạy di chuyển. Các công cụ chỉ đọc bao gồm liệt kê dự án, mô tả lược đồ, truy vấn dữ liệu và xem số liệu hiệu suất.

Bạn có thể đặt chế độ chỉ đọc theo hai cách:

1. URL MCP mặc định (đồng ý có thể chỉnh sửa): Kết nối với https://mcp.neon.tech/mcp và bỏ chọn Cho phép ghi trên trang ủy quyền. Bạn cũng có thể chọn một dự án và một tập hợp con các danh mục công cụ ở đó.
2. URL MCP có tham số (đồng ý cố định): Đặt readonly, projectId và/hoặc category trên URL máy chủ MCP. Trang ủy quyền xác nhận cấp quyền đó và không cung cấp trình chỉnh sửa. Thay đổi URL và ủy quyền lại để thay đổi cấp quyền.

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

Cách tham số truy vấn hoạt động:

• Luồng khóa API: readonly=true là cách để bật chế độ chỉ đọc (không có trao đổi phạm vi OAuth trong luồng này). Các thay đổi URL được áp dụng trên yêu cầu tiếp theo.
• Luồng OAuth: projectId, category và readonly trên URL MCP là một cấp quyền cố định được xác nhận tại thời điểm ủy quyền. readonly=true không thể được mở rộng thành ghi trên trang đó. Sau khi mã thông báo được cấp, việc thay đổi URL không mở rộng mã thông báo đó; hãy ủy quyền lại.

Đối với đăng ký OAuth, x-read-only là mặc định Cho phép ghi ban đầu trên đồng ý có thể chỉnh sửa. Nó không khóa xác nhận và không giảm URL có tham số bao gồm readonly=false. Các yêu cầu khóa API vẫn tôn trọng x-read-only cho mỗi yêu cầu, dưới tham số truy vấn readonly.

Lưu ý: Chế độ chỉ đọc giới hạn công cụ nào khả dụng. Hơn nữa, công cụ run_sql vẫn khả dụng chỉ cho các truy vấn chỉ đọc.

Tham số truy vấn URL để kiểm soát truy cập

Ngữ cảnh cấp quyền (danh mục phạm vi, phạm vi dự án, chế độ chỉ đọc) được cấu hình qua các tham số truy vấn URL trên URL máy chủ MCP. Các yêu cầu khóa API áp dụng các tham số đó trên mỗi yêu cầu. Mã thông báo OAuth lưu trữ cấp quyền được xác nhận hoặc chỉnh sửa tại thời điểm ủy quyền.

Tham số	Mô tả	Ví dụ
readonly	Bật chế độ chỉ đọc (true/false)	?readonly=true
category	Giới hạn các danh mục công cụ cụ thể (lặp lại hoặc CSV)	?category=querying&category=schema
projectId	Phạm vi tất cả các thao tác cho một dự án duy nhất	?projectId=proj-123

Ví dụ chỉ đọc + phạm vi dự án:

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

Ví dụ lọc danh mục (chỉ công cụ truy vấn và lược đồ):

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

Bạn có thể xem trước các công cụ hiển thị cho bất kỳ cấu hình nào bằng điểm cuối /api/list-tools (không yêu cầu xác thực):

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

Các công cụ khả dụng trong chế độ chỉ đọc

Công cụ máy chủ: list_organizations, describe_branch, run_sql, run_sql_transaction, get_database_tables, describe_table_schema, list_slow_queries, explain_sql_statement, inspect_database, get_neon_auth_config, search, fetch, list_docs_resources, get_doc_resource.

Các công cụ API Quản lý được tạo là GET và không trả về bí mật, cộng với query_logs (POST, chỉ đọc). Xem trước tập hợp chính xác bằng /api/list-tools?readonly=true.

Các công cụ yêu cầu quyền ghi:

• Các thao tác ghi API Quản lý được tạo (create_project, create_branch, delete_project, …)
• get_connection_string (chuỗi kết nối mang mật khẩu vai trò đặc quyền, vì vậy nó bị giữ lại trong chế độ chỉ đọc; thay vào đó hãy sao chép nó từ Bảng điều khiển Neon)
• prepare_database_migration, complete_database_migration
• prepare_query_tuning, complete_query_tuning

Truyền tải Server-Sent Events (SSE) (Không dùng nữa)

MCP hỗ trợ hai truyền tải máy chủ từ xa: Server-Sent Events (SSE) không dùng nữa và Streamable HTTP mới hơn, được khuyến nghị. Nếu máy khách LLM của bạn chưa hỗ trợ Streamable HTTP, bạn có thể chuyển điểm cuối từ https://mcp.neon.tech/mcp sang https://mcp.neon.tech/sse để sử dụng SSE.

Chạy lệnh sau để thêm Máy chủ MCP Neon cho tất cả các đại lý và trình soạn thảo được phát hiện trong không gian làm việc của bạn bằng truyền tải SSE:

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

Kiến trúc máy chủ từ xa

Máy chủ từ xa chạy như một ứng dụng Next.js App Router trên Vercel tại mcp.neon.tech.

[!NOTE] Đường dẫn gốc / chuyển hướng đến tài liệu Máy chủ MCP Neon. Không có trang đích.

Các khu vực triển khai cốt lõi:

• app/api/[transport]/route.ts: Điểm cuối truyền tải MCP cho Streamable HTTP (/mcp) và SSE (/sse)
• app/api/authorize/, app/callback/, app/api/token/, app/api/revoke/: Các điểm cuối luồng OAuth
• app/.well-known/: Các điểm cuối siêu dữ liệu khám phá OAuth
• mcp/: Máy chủ MCP, công cụ, trình xử lý, phân tích và tích hợp Sentry
• lib/: Các trình trợ giúp tương thích Next.js (OAuth, cấu hình, xử lý lỗi)
• mcp/utils/read-only.ts: Xử lý chế độ chỉ đọc và phạm vi

Hướng dẫn

• Hướng dẫn MCP Server Neon
• Kết nối MCP Clients với Neon
• Cursor với MCP Server Neon
• Claude Code với MCP Server Neon
• Claude Desktop với MCP Server Neon
• Cline với MCP Server Neon
• Windsurf với MCP Server Neon
• Zed với MCP Server Neon

Tính năng

Các công cụ được hỗ trợ

MCP Server Neon cung cấp các hành động sau, được hiển thị dưới dạng "công cụ" cho MCP Clients. Bạn có thể sử dụng các công cụ này để tương tác với các dự án và cơ sở dữ liệu Neon của mình bằng các lệnh ngôn ngữ tự nhiên.

Siêu dữ liệu phạm vi công cụ

Mỗi định nghĩa công cụ bao gồm một danh mục scope được sử dụng để lọc công cụ dựa trên quyền và trải nghiệm người dùng đồng ý. Các danh mục hiện tại là:

• projects
• branches
• endpoints
• snapshots
• schema
• querying
• neon_auth
• data_api
• observability
• docs
• functions
• storage
• null (các công cụ không có danh mục phạm vi)

Ghi chú:

• Các công cụ Management API đến từ @neon/tools. Bộ chọn là các đường dẫn SDK (projects.list); tên MCP đã xuất bản bắt đầu bằng động từ (list_projects, delete_project, query_logs). Các tên lịch sử vẫn giữ nguyên ở nơi chúng đã tồn tại (describe_project, create_branch, reset_from_parent, compare_database_schema, provision_neon_auth, provision_neon_data_api, list_branch_computes).
• ?category=branches bao gồm các công cụ branch, role và database (list_postgres_roles, create_postgres_database, …). Một token đã được cấp cho branches sẽ có thêm các quyền ghi đó. Liệt kê compute là ?category=endpoints. Khôi phục snapshot là ?category=snapshots.
• Các thao tác ghi thành viên dự án và quyền không được xuất bản. list_project_members và list_project_permissions là các thao tác đọc.
• Các công cụ schema (?category=schema) là các công cụ máy chủ get_database_tables và describe_table_schema, cùng với compare_database_schema được tạo.
• Việc thực thi chỉ đọc vẫn dựa trên readOnlySafe và logic chỉ đọc phía máy chủ; scope là siêu dữ liệu danh mục, không phải là công tắc đọc/ghi độc lập.
• Trong chế độ phạm vi dự án (?projectId=...), các công cụ không có đường dẫn dự án (list_projects, create_project, list_organizations, list_regions, search, fetch, …) sẽ bị ẩn. delete_project cũng bị ẩn.

Quản lý dự án:

• list_projects: Liệt kê các dự án Neon. limit giới hạn số lượng mục trả về.
• describe_project: Lấy thông tin một dự án Neon theo id ({ "project_id": "…" }).
• create_project: Tạo một dự án Neon và chờ compute mặc định. Không trả về chuỗi kết nối. Các đối số là { "name": "…", "org_id": "…", "region_id": "…" }. Gọi get_connection_string sau khi thành công.
• delete_project: Xóa một dự án Neon hiện có. Các đối số là { "project_id": "…" }.
• list_organizations: Liệt kê tất cả các tổ chức mà người dùng hiện tại có quyền truy cập. Tùy chọn lọc theo tên hoặc ID tổ chức bằng tham số tìm kiếm.

Quản lý branch:

• list_branches: Liệt kê các branch trong một dự án. Sử dụng để phân giải tên branch thành id br-….
• list_credentials, create_credential, revoke_credential, rotate_credential: Thông tin xác thực theo phạm vi branch cho Object Storage và AI Gateway. reveal không phải là một công cụ; việc xoay vòng thay thế bí mật tại chỗ và không phải là thao tác lũy đẳng.
• create_branch: Tạo một branch với compute đọc-ghi và chờ cho đến khi sẵn sàng. Không trả về chuỗi kết nối. Các đối số là { "project_id": "…", "name": "feature-x" }. Truyền no_compute: true để bỏ qua endpoint. Gọi get_connection_string sau khi thành công.
• reset_from_parent: Đặt lại một branch về HEAD hiện tại của branch cha ({ "project_id": "…", "branch_id": "br-…" }). Loại bỏ các thay đổi ghi kể từ khi branch phân nhánh. preserve_under_name là bắt buộc khi branch có branch con; các branch con đó sẽ chuyển sang branch mới. Chỉ HEAD của branch cha; khôi phục tại một thời điểm là restore_snapshot.
• delete_branch: Xóa một branch ({ "project_id": "…", "branch_id": "br-…" }).
• describe_branch: Truy xuất cây cơ sở dữ liệu, schema, bảng, view và hàm trên một branch.
• Các công cụ branch được tạo nhận branch_id làm id branch (br-...), không phải tên.
• restore_snapshot: Khôi phục một snapshot. Truyền target_branch_id để khôi phục lên một branch hiện có; bỏ qua để tạo branch mới.

Compute endpoints (?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

Snapshots (?category=snapshots):

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

Schema (?category=schema):

• get_database_tables, describe_table_schema
• compare_database_schema: So sánh schema SQL của một cơ sở dữ liệu với một branch khác. database_name là bắt buộc. Bỏ qua base_branch_id sẽ so sánh với branch cha. Các tham số tùy chọn lsn, timestamp, base_lsn, base_timestamp chỉ dành cho điểm thời gian.

Thực thi truy vấn SQL:

• get_connection_string: Trả về chuỗi kết nối cơ sở dữ liệu của bạn.
• run_sql: Thực thi một truy vấn SQL duy nhất trên một cơ sở dữ liệu Neon được chỉ định. Hỗ trợ cả thao tác đọc và ghi.
• run_sql_transaction: Thực thi một loạt truy vấn SQL trong một giao dịch duy nhất trên một cơ sở dữ liệu Neon.
• get_database_tables: Liệt kê tất cả các bảng trong một cơ sở dữ liệu Neon được chỉ định.
• describe_table_schema: Truy xuất định nghĩa schema của một bảng cụ thể, chi tiết các cột, kiểu dữ liệu và ràng buộc.

Di chuyển cơ sở dữ liệu (Thay đổi schema):

• prepare_database_migration: Bắt đầu quá trình di chuyển cơ sở dữ liệu. Quan trọng là, nó tạo một branch tạm thời để áp dụng và kiểm tra việc di chuyển một cách an toàn trước khi ảnh hưởng đến branch chính.
• complete_database_migration: Hoàn tất và áp dụng một bản di chuyển cơ sở dữ liệu đã chuẩn bị vào branch chính. Hành động này hợp nhất các thay đổi từ branch di chuyển tạm thời và dọn dẹp các tài nguyên tạm thời.

Truy vấn và tối ưu hóa SQL:

• inspect_database: Chạy một trong 15 chẩn đoán Postgres chỉ đọc được xác định trước trên một branch — kích thước quan hệ và chỉ mục, mức sử dụng chỉ mục và quét tuần tự, truy vấn và khóa đang hoạt động, các truy vấn nặng nhất và thường xuyên nhất, tỷ lệ truy cập bộ nhớ cache và kích thước tập làm việc, ước tính autovacuum và bloat, và trạng thái sao chép. Các kiểm tra tương tự như lệnh CLI neon inspect db. Bỏ qua database_name để bao phủ mọi cơ sở dữ liệu trên branch; truyền tên để kiểm tra một cơ sở dữ liệu. Bốn trong số chúng cần phần mở rộng pg_stat_statements hoặc neon.
• list_slow_queries: Xác định các điểm nghẽn hiệu suất bằng cách tìm các truy vấn chậm nhất trong một cơ sở dữ liệu. Yêu cầu phần mở rộng pg_stat_statements.
• explain_sql_statement: Cung cấp các kế hoạch thực thi chi tiết cho các truy vấn SQL để giúp xác định các điểm nghẽn hiệu suất.
• prepare_query_tuning: Phân tích hiệu suất truy vấn và đề xuất các tối ưu hóa, như tạo chỉ mục. Tạo một branch tạm thời để kiểm tra các tối ưu hóa này một cách an toàn.
• complete_query_tuning: Hoàn tất việc điều chỉnh truy vấn bằng cách áp dụng các tối ưu hóa vào branch chính hoặc loại bỏ chúng. Dọn dẹp branch điều chỉnh tạm thời.

Neon Auth (?category=neon_auth):

• provision_neon_auth, get_auth, disable_auth, update_auth_config
• get_neon_auth_config: công cụ máy chủ; bí mật được biên tập lại. Sử dụng các công cụ ghi Auth được tạo để thay đổi cài đặt.
• 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: Quản lý Data API cho một cơ sở dữ liệu branch.

Tìm kiếm và khám phá:

• search: Tìm kiếm trên các tổ chức, dự án và branch khớp với một truy vấn. Trả về ID, tiêu đề và liên kết trực tiếp đến Neon Console.
• fetch: Lấy thông tin chi tiết về một tổ chức, dự án hoặc branch cụ thể bằng ID (thường từ công cụ tìm kiếm).

Quan sát (?category=observability): các công cụ này yêu cầu Neon Platform Beta và hiện chỉ khả dụng cho các dự án trong khu vực aws-us-east-2. Một branch không có quyền truy cập nhật ký trả về HTTP 404 với lý do telemetry_not_enabled.

• query_logs: Truy vấn nhật ký OpenTelemetry cho một branch. POST trong Management API; được máy chủ này coi là chỉ đọc.
• list_log_fields: Liệt kê các trường nhật ký mà bạn có thể liệt kê các giá trị trên một branch.
• list_log_field_values: Liệt kê các giá trị riêng biệt của một trường nhật ký trong một branch và cửa sổ thời gian.

Tài liệu và tài nguyên (?category=docs):

• list_docs_resources: Liệt kê tất cả các trang tài liệu Neon có sẵn bằng cách lấy chỉ mục từ https://neon.com/docs/llms.txt. Trả về URL và tiêu đề trang có thể được lấy riêng lẻ bằng công cụ get_doc_resource.
• get_doc_resource: Lấy một trang tài liệu Neon cụ thể dưới dạng nội dung markdown. Sử dụng công cụ list_docs_resources trước để khám phá các slug trang có sẵn, sau đó truyền slug cho công cụ này.

Hàm (?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: Trình kích hoạt hàm theo lịch trình (type: "schedule", cron UTC năm trường).

Lưu trữ (?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

Di chuyển

Di chuyển là một cách để quản lý các thay đổi đối với schema cơ sở dữ liệu của bạn theo thời gian. Với máy chủ MCP Neon, các LLM được trao quyền để thực hiện di chuyển một cách an toàn với các lệnh "Bắt đầu" (prepare_database_migration) và "Cam kết" (complete_database_migration) riêng biệt.

Lệnh "Bắt đầu" chấp nhận một bản di chuyển và chạy nó trong một branch tạm thời mới. Khi trả về, lệnh này gợi ý cho LLM rằng nó nên kiểm tra bản di chuyển trên branch này. LLM sau đó có thể chạy lệnh "Cam kết" để áp dụng bản di chuyển vào branch ban đầu.

Phát triển

Dự án này sử dụng pnpm làm trình quản lý gói, được ghim qua Corepack.

Cấu trúc dự án

Mã máy chủ MCP nằm ở thư mục gốc của kho lưu trữ, một ứng dụng Next.js được triển khai lên Vercel tại mcp.neon.tech.

corepack enable
pnpm install

Xem CONTRIBUTING.md để biết cách thêm công cụ. Các đối số công cụ là snake_case.

Phát triển cục bộ

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

Kiểm tra lint và kiểu

pnpm lint
pnpm typecheck

Biến môi trường

Bắt buộc cho thời gian chạy máy chủ từ xa:

Biến	Mô tả
SERVER_HOST	URL máy chủ (mặc định là VERCEL_URL)
UPSTREAM_OAUTH_HOST	URL nhà cung cấp OAuth Neon
CLIENT_ID	ID máy khách OAuth
CLIENT_SECRET	Bí mật máy khách OAuth
KV_URL	URL Vercel KV (Upstash Redis)
OAUTH_DATABASE_URL	URL Postgres để lưu trữ token

Tùy chọn:

Biến số	Mô tả
LOG_LEVEL	Mức log của Winston: error, warn, info (mặc định), debug, verbose, silly
NEON_MCP_DISABLE_ANALYTICS	Đặt thành 1 để tắt phân tích sản phẩm

Kim tự tháp kiểm thử

Tất cả các bài kiểm thử chạy từ thư mục gốc của kho lưu trữ.

# 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

Chiến lược kiểm thử:

• Ưu tiên E2E cho giao thức truyền tải và hành vi người dùng có thể thấy.
• Sử dụng bài kiểm thử tích hợp cho các hợp đồng công cụ xác định và hành vi quy trình làm việc.
• Sử dụng bài kiểm thử đơn vị cho logic thuần túy và các trường hợp biên.
• Tránh phụ thuộc vào thời gian hoạt động của bên thứ ba trong các bài kiểm thử gating hợp nhất; giả lập các phụ thuộc bên ngoài trong các tầng tích hợp/đơn vị.

Triển khai

Vercel tự động triển khai máy chủ từ xa từ cấu hình nhánh của kho lưu trữ. Môi trường xem trước có sẵn cho các yêu cầu kéo.

Đo lường từ xa

Máy chủ MCP Neon thu thập phân tích sản phẩm và báo cáo lỗi để giúp chúng tôi hiểu cách sử dụng và cải thiện độ tin cậy:

• Phân tích sản phẩm (Segment): khi bạn kết nối với tài khoản đã xác thực, máy chủ gửi một sự kiện identify với ID tài khoản Neon, tên và email của bạn. Nó cũng theo dõi bắt đầu phiên (server_init), mỗi lần gọi công cụ (tool_call) và lỗi máy chủ bất ngờ (server_error). Một sự kiện gọi công cụ bao gồm tên công cụ, phương thức xác thực và máy khách, không bao gồm đối số công cụ hoặc kết quả truy vấn. Các lệnh gọi công cụ chỉ dành cho tài liệu mà không có tài khoản được theo dõi ẩn danh. Sự kiện được gửi đến track.neon.tech, điểm cuối phân tích riêng của Neon.
• Báo cáo lỗi (Sentry): lỗi máy chủ bất ngờ được báo cáo với dấu vết ngăn xếp và ngữ cảnh yêu cầu.

Việc thu thập này được bao phủ bởi Chính sách quyền riêng tư của Neon. Để tắt phân tích khi tự chạy máy chủ, đặt NEON_MCP_DISABLE_ANALYTICS=1. Cờ đó không tắt Sentry.