Neon

Server MCP Neon

Server MCP Neon adalah alat sumber terbuka yang memungkinkan Anda berinteraksi dengan basis data Neon Postgres dalam bahasa alami.

Model Context Protocol (MCP) adalah protokol terstandarisasi yang dirancang untuk mengelola konteks antara model bahasa besar (LLM) dan sistem eksternal. Repositori ini menyediakan Server MCP jarak jauh untuk Neon.

Server MCP Neon bertindak sebagai jembatan antara permintaan bahasa alami dan API Neon. Dibangun di atas MCP, server ini menerjemahkan permintaan Anda ke dalam panggilan API yang diperlukan, memungkinkan Anda mengelola tugas-tugas seperti membuat proyek dan cabang, menjalankan kueri, dan melakukan migrasi basis data dengan lancar.

Beberapa fitur utama dari server MCP Neon meliputi:

• Interaksi bahasa alami: Kelola basis data Neon menggunakan perintah percakapan yang intuitif.
• Manajemen basis data yang disederhanakan: Lakukan tindakan kompleks tanpa menulis SQL atau langsung menggunakan API Neon.
• Aksesibilitas untuk non-pengembang: Berdayakan pengguna dengan berbagai latar belakang teknis untuk berinteraksi dengan basis data Neon.
• Dukungan migrasi basis data: Manfaatkan kemampuan percabangan Neon untuk perubahan skema basis data yang dimulai melalui bahasa alami.

Misalnya, di Claude Code, atau klien MCP apa pun, Anda dapat menggunakan bahasa alami untuk mencapai berbagai hal dengan Neon, seperti:

• 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]
Pertimbangan Keamanan Server MCP Neon
Server MCP Neon memberikan kemampuan manajemen basis data yang kuat melalui permintaan bahasa alami. Selalu tinjau dan otorisasi tindakan yang diminta oleh LLM sebelum dieksekusi. Pastikan hanya pengguna dan aplikasi yang berwenang yang memiliki akses ke Server MCP Neon.

Server MCP Neon ditujukan hanya untuk pengembangan lokal dan integrasi IDE. Kami tidak merekomendasikan penggunaan Server MCP Neon di lingkungan produksi. Server ini dapat menjalankan operasi yang kuat yang dapat menyebabkan perubahan yang tidak disengaja atau tidak sah.

Untuk informasi lebih lanjut, lihat panduan keamanan MCP →.

Menyiapkan Server MCP Neon

Ada beberapa opsi untuk menyiapkan Server MCP Neon:

1. Penyiapan Cepat dengan Kunci API (Cursor, VS Code, dan Claude Code): Jalankan neon@latest init untuk mengonfigurasi Server MCP Neon, keterampilan agen, dan ekstensi VS Code secara otomatis dengan satu perintah.
2. Server MCP Jarak Jauh (Autentikasi Berbasis OAuth): Hubungkan ke server MCP terkelola Neon menggunakan OAuth untuk autentikasi. Metode ini lebih nyaman karena menghilangkan kebutuhan untuk mengelola kunci API. Selain itu, Anda akan secara otomatis menerima fitur dan peningkatan terbaru segera setelah dirilis.
3. Server MCP Jarak Jauh (Autentikasi Berbasis Kunci API): Hubungkan ke server MCP terkelola Neon menggunakan kunci API untuk autentikasi. Metode ini berguna jika Anda ingin menghubungkan agen jarak jauh ke Neon di mana OAuth tidak tersedia. Selain itu, Anda akan secara otomatis menerima fitur dan peningkatan terbaru segera setelah dirilis.

Prasyarat

• Aplikasi Klien MCP.
• Akun Neon.
• Node.js (>= v18.0.0): Unduh dari nodejs.org.
• Jika IP Allow diaktifkan, tambahkan 34.192.103.46 dan 23.22.233.166 ke daftar izin Anda (mcp.neon.tech IP statis).

Untuk pengembangan, Anda memerlukan Node.js 22+ (pnpm disediakan melalui Corepack — jalankan corepack enable untuk mengaktifkannya).

Opsi 1. Penyiapan Cepat dengan Kunci API

Tidak ingin membuat kunci API secara manual?

Jalankan neon@latest init untuk mengonfigurasi Server MCP Neon secara otomatis dengan satu perintah:

npx neon@latest init

Ini berfungsi dengan Cursor, VS Code (GitHub Copilot), dan Claude Code. Ini akan mengautentikasi melalui OAuth, membuat kunci API Neon untuk Anda, dan mengonfigurasi editor Anda secara otomatis.

Opsi 2. Server MCP Jarak Jauh yang Dihosting (Autentikasi Berbasis OAuth)

Hubungkan ke server MCP terkelola Neon menggunakan OAuth untuk autentikasi. Ini adalah penyiapan termudah, tidak memerlukan instalasi lokal server ini, dan tidak memerlukan kunci API Neon yang dikonfigurasi di klien.

Jalankan perintah berikut untuk menambahkan Server MCP Neon untuk semua agen dan editor yang terdeteksi di ruang kerja Anda:

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

Tambahkan flag -g untuk menambahkan Server MCP Neon ke daftar server MCP global, bukan lingkup proyek.

Atau, Anda dapat menambahkan entri "Neon" berikut ke file konfigurasi server MCP klien Anda (mis., mcp.json, mcp_config.json):

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

Kiro: Tambahkan yang berikut ke file konfigurasi MCP Kiro Anda (~/.kiro/settings/mcp.json untuk global, atau .kiro/settings/mcp.json untuk lingkup proyek):

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

Atau gunakan tombol instal sekali klik di bagian atas README ini. Untuk informasi lebih lanjut, lihat dokumentasi Kiro MCP.

• Mulai ulang atau segarkan klien MCP Anda.
• Jendela OAuth akan terbuka di browser Anda. Ikuti petunjuk untuk mengotorisasi klien MCP Anda mengakses akun Neon Anda.

Dengan autentikasi berbasis OAuth, server MCP akan, secara default, beroperasi pada proyek di bawah akun Neon pribadi Anda. Untuk mengakses atau mengelola proyek milik organisasi, Anda harus secara eksplisit memberikan org_id atau project_id dalam prompt Anda ke klien MCP.

Opsi 3. Server MCP Jarak Jauh yang Dihosting (Autentikasi Berbasis Kunci API)

Server MCP Jarak Jauh juga mendukung autentikasi menggunakan kunci API di header Authorization jika klien Anda mendukungnya.

Buat kunci API Neon di Konsol Neon. Selanjutnya, jalankan perintah berikut untuk menambahkan Server MCP Neon untuk semua agen dan editor yang terdeteksi di ruang kerja Anda:

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

Atau, Anda dapat menambahkan entri "Neon" berikut ke file konfigurasi server MCP klien Anda (mis., mcp.json, mcp_config.json):

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

Berikan kunci API organisasi untuk membatasi akses hanya ke proyek di bawah organisasi tersebut.

Cakupan dan Mode Hanya-Baca

Neon MCP mendukung cakupan OAuth read, write, dan * (* berarti keduanya). Klien MCP Anda dapat meminta cakupan ini secara langsung, atau Anda dapat membuat pilihan di UI izin OAuth.

Mode hanya-baca membatasi alat mana yang tersedia, menonaktifkan operasi tulis seperti membuat proyek, cabang, atau menjalankan migrasi. Alat hanya-baca mencakup daftar proyek, mendeskripsikan skema, mengkueri data, dan melihat metrik kinerja.

Anda dapat mengatur mode hanya-baca dengan dua cara:

1. Pemilihan cakupan OAuth (disarankan): Di OAuth, pilih hanya-baca dengan menghapus centang Akses penuh di UI otorisasi.
2. Parameter kueri readonly: Tambahkan ?readonly=true ke URL server MCP Anda:

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

Bagaimana perilaku parameter kueri:

• Alur kunci API: readonly=true adalah cara untuk mengaktifkan mode hanya-baca (tidak ada pertukaran cakupan OAuth dalam alur ini).
• Alur OAuth: readonly=true menggantikan cakupan OAuth. Tanpanya, hanya-baca ditentukan oleh cakupan yang dipilih di UI persetujuan OAuth.

Header HTTP lawas x-read-only juga didukung sebagai fallback (prioritas lebih rendah dari parameter kueri).

Catatan: Mode hanya-baca membatasi alat mana yang tersedia. Lebih lanjut, alat run_sql tetap tersedia hanya untuk kueri hanya-baca.

Parameter Kueri URL untuk Kontrol Akses

Konteks pemberian (kategori cakupan, lingkup proyek, mode hanya-baca) dikonfigurasi melalui parameter kueri URL pada URL server MCP. Konfigurasi berjalan dengan setiap permintaan dan berlaku segera — tidak perlu otentikasi ulang.

Param	Deskripsi	Contoh
readonly	Aktifkan mode hanya-baca (true/false)	?readonly=true
category	Batasi ke kategori alat tertentu (diulang atau CSV)	?category=querying&category=schema
projectId	Lingkup semua operasi ke satu proyek	?projectId=proj-123

Contoh hanya-baca + lingkup proyek:

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

Contoh yang difilter berdasarkan kategori (hanya alat kueri dan skema):

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

Anda dapat melihat pratinjau alat mana yang terlihat untuk konfigurasi apa pun menggunakan titik akhir /api/list-tools (tidak diperlukan autentikasi):

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

Alat yang tersedia dalam mode hanya-baca

• list_projects, list_shared_projects, describe_project, list_organizations
• describe_branch, list_branch_computes, compare_database_schema
• run_sql, run_sql_transaction, get_database_tables, describe_table_schema
• list_slow_queries, explain_sql_statement
• get_connection_string
• search, fetch, list_docs_resources, get_doc_resource

Alat yang memerlukan akses tulis:

• create_project, delete_project
• create_branch, delete_branch, reset_from_parent
• provision_neon_auth, provision_neon_data_api
• prepare_database_migration, complete_database_migration
• prepare_query_tuning, complete_query_tuning

Transport Server-Sent Events (SSE) (Tidak Digunakan Lagi)

MCP mendukung dua transport server jarak jauh: Server-Sent Events (SSE) yang tidak digunakan lagi dan Streamable HTTP yang lebih baru dan direkomendasikan. Jika klien LLM Anda belum mendukung Streamable HTTP, Anda dapat mengganti titik akhir dari https://mcp.neon.tech/mcp ke https://mcp.neon.tech/sse untuk menggunakan SSE sebagai gantinya.

Jalankan perintah berikut untuk menambahkan Server MCP Neon untuk semua agen dan editor yang terdeteksi di ruang kerja Anda menggunakan transport SSE:

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

Arsitektur Server Jarak Jauh

Server jarak jauh berjalan sebagai aplikasi Next.js App Router di Vercel di mcp.neon.tech.

[!NOTE] Jalur root / mengarahkan ke dokumentasi Server MCP Neon. Tidak ada halaman arahan.

Area implementasi inti:

• app/api/[transport]/route.ts: Titik akhir transport MCP untuk Streamable HTTP (/mcp) dan SSE (/sse)
• app/api/authorize/, app/callback/, app/api/token/, app/api/revoke/: Titik akhir alur OAuth
• app/.well-known/: Titik akhir metadata penemuan OAuth
• mcp/: Server MCP, alat, penangan, analitik, dan integrasi Sentry
• lib/: Pembantu yang kompatibel dengan Next.js (OAuth, konfigurasi, penanganan kesalahan)
• mcp/utils/read-only.ts: mode hanya-baca dan penanganan cakupan

Panduan

• Panduan Server MCP Neon
• Hubungkan Klien MCP ke Neon
• Cursor dengan Server MCP Neon
• Claude Desktop dengan Server MCP Neon
• Cline dengan Server MCP Neon
• Windsurf dengan Server MCP Neon
• Zed dengan Server MCP Neon

Fitur

Alat yang Didukung

Server MCP Neon menyediakan tindakan berikut, yang diekspos sebagai "alat" ke Klien MCP. Anda dapat menggunakan alat ini untuk berinteraksi dengan proyek dan basis data Neon Anda menggunakan perintah bahasa alami.

Metadata Cakupan Alat

Setiap definisi alat menyertakan kategori scope yang digunakan untuk pemfilteran alat berbasis pemberian dan UX persetujuan. Kategori saat ini adalah:

• projects
• branches
• schema
• querying
• neon_auth
• data_api
• docs
• null (alat tanpa kategori cakupan)

Catatan:

• compare_database_schema dikategorikan di bawah schema.
• provision_neon_data_api dikategorikan di bawah data_api (terpisah dari neon_auth).
• Penegakan hanya-baca masih bergantung pada readOnlySafe dan logika hanya-baca sisi server; scope adalah metadata kategori, bukan sakelar baca/tulis mandiri.
• Dalam mode lingkup proyek (?projectId=...), search dan fetch tidak tersedia.

Manajemen Proyek:

• list_projects: Mencantumkan 10 proyek Neon pertama di akun Anda, memberikan ringkasan setiap proyek. Jika Anda tidak dapat menemukan proyek tertentu, tingkatkan batasnya dengan memberikan nilai yang lebih tinggi ke parameter limit.
• list_shared_projects: Mencantumkan proyek Neon yang dibagikan dengan pengguna saat ini. Mendukung parameter pencarian dan membatasi jumlah proyek yang dikembalikan (default: 10).
• describe_project: Mengambil informasi detail tentang proyek Neon tertentu, termasuk ID, nama, serta cabang dan basis data terkait.
• create_project: Membuat proyek Neon baru di akun Neon Anda. Proyek berfungsi sebagai wadah untuk cabang, basis data, peran, dan komputasi.
• delete_project: Menghapus proyek Neon yang ada dan semua sumber daya terkaitnya.
• list_organizations: Mencantumkan semua organisasi yang dapat diakses oleh pengguna saat ini. Secara opsional, filter berdasarkan nama atau ID organisasi menggunakan parameter pencarian.

Manajemen Cabang:

• create_branch: Membuat cabang baru dalam proyek Neon yang ditentukan. Memanfaatkan fitur percabangan Neon untuk pengembangan, pengujian, atau migrasi.
• delete_branch: Menghapus cabang yang ada dari proyek Neon.
• describe_branch: Mengambil detail tentang cabang tertentu, seperti nama, ID, dan cabang induknya.
• list_branch_computes: Mencantumkan titik akhir komputasi untuk proyek atau cabang tertentu, termasuk ID komputasi, tipe, ukuran, waktu aktif terakhir, dan informasi penskalaan otomatis.
• compare_database_schema: Menampilkan perbedaan skema antara cabang anak dan induknya.
• reset_from_parent: Mengatur ulang cabang saat ini ke status induknya, membuang perubahan lokal. Secara otomatis menyimpan ke cadangan jika cabang memiliki anak, atau secara opsional menyimpan berdasarkan permintaan dengan nama kustom.

Eksekusi Kueri SQL:

• get_connection_string: Mengembalikan string koneksi basis data Anda.
• run_sql: Mengeksekusi satu kueri SQL terhadap basis data Neon yang ditentukan. Mendukung operasi baca dan tulis.
• run_sql_transaction: Mengeksekusi serangkaian kueri SQL dalam satu transaksi terhadap basis data Neon.
• get_database_tables: Mencantumkan semua tabel dalam basis data Neon yang ditentukan.
• describe_table_schema: Mengambil definisi skema dari tabel tertentu, merinci kolom, tipe data, dan batasan.

Migrasi Basis Data (Perubahan Skema):

• prepare_database_migration: Memulai proses migrasi basis data. Yang penting, ini membuat cabang sementara untuk menerapkan dan menguji migrasi dengan aman sebelum memengaruhi cabang utama.
• complete_database_migration: Menyelesaikan dan menerapkan migrasi basis data yang telah disiapkan ke cabang utama. Tindakan ini menggabungkan perubahan dari cabang migrasi sementara dan membersihkan sumber daya sementara.

Kueri dan Optimasi SQL:

• list_slow_queries: Mengidentifikasi hambatan kinerja dengan menemukan kueri paling lambat di basis data. Memerlukan ekstensi pg_stat_statements.
• explain_sql_statement: Menyediakan rencana eksekusi detail untuk kueri SQL guna membantu mengidentifikasi hambatan kinerja.
• prepare_query_tuning: Menganalisis kinerja kueri dan menyarankan optimasi, seperti pembuatan indeks. Membuat cabang sementara untuk menguji optimasi ini dengan aman.
• complete_query_tuning: Menyelesaikan penyetelan kueri dengan menerapkan optimasi ke cabang utama atau membuangnya. Membersihkan cabang penyetelan sementara.

Neon Auth:

• provision_neon_auth: Menyediakan Neon Auth untuk proyek Neon. Ini memungkinkan pengembang untuk dengan mudah menyiapkan infrastruktur autentikasi dengan membuat integrasi dengan penyedia Auth.

API Data Neon:

• provision_neon_data_api: Menyediakan API Data Neon untuk akses basis data berbasis HTTP dengan autentikasi JWT opsional melalui Neon Auth atau penyedia JWKS eksternal.

Pencarian dan Penemuan:

• search: Mencari di seluruh organisasi, proyek, dan cabang yang cocok dengan kueri. Mengembalikan ID, judul, dan tautan langsung ke Konsol Neon.
• fetch: Mengambil informasi detail tentang organisasi, proyek, atau cabang tertentu menggunakan ID (biasanya dari alat pencarian).

Dokumentasi dan Sumber Daya:

• list_docs_resources: Mencantumkan semua halaman dokumentasi Neon yang tersedia dengan mengambil indeks dari https://neon.com/docs/llms.txt. Mengembalikan URL dan judul halaman yang dapat diambil satu per satu menggunakan alat get_doc_resource.
• get_doc_resource: Mengambil halaman dokumentasi Neon tertentu sebagai konten markdown. Gunakan alat list_docs_resources terlebih dahulu untuk menemukan slug halaman yang tersedia, lalu berikan slug tersebut ke alat ini.

Migrasi

Migrasi adalah cara untuk mengelola perubahan pada skema basis data Anda dari waktu ke waktu. Dengan server MCP Neon, LLM diberdayakan untuk melakukan migrasi dengan aman menggunakan perintah "Mulai" (prepare_database_migration) dan "Komit" (complete_database_migration) yang terpisah.

Perintah "Mulai" menerima migrasi dan menjalankannya di cabang sementara baru. Setelah kembali, perintah ini memberi isyarat kepada LLM bahwa ia harus menguji migrasi di cabang ini. LLM kemudian dapat menjalankan perintah "Komit" untuk menerapkan migrasi ke cabang asli.

Pengembangan

Proyek ini menggunakan pnpm sebagai manajer paket, yang disematkan melalui Corepack.

Struktur Proyek

Kode server MCP berada di root repositori, sebuah aplikasi Next.js yang diterapkan ke Vercel di mcp.neon.tech.

corepack enable
pnpm install

Pengembangan Lokal

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

Linting dan Pemeriksaan Tipe

pnpm run lint
pnpm run typecheck

Variabel Lingkungan

Diperlukan untuk runtime server jarak jauh:

Variabel	Deskripsi
SERVER_HOST	URL Server (default ke VERCEL_URL)
UPSTREAM_OAUTH_HOST	URL penyedia OAuth Neon
CLIENT_ID	ID klien OAuth
CLIENT_SECRET	Rahasia klien OAuth
COOKIE_SECRET	Rahasia untuk cookie yang ditandatangani
KV_URL	URL Vercel KV (Upstash Redis)
OAUTH_DATABASE_URL	URL Postgres untuk penyimpanan token

Opsional:

Variabel	Deskripsi
LOG_LEVEL	Level log Winston: error, warn, info (default), debug, verbose, silly

Piramida Pengujian

Semua pengujian dijalankan dari root repositori.

# Unit tests
pnpm run test:unit

# Integration tests
pnpm run test:integration

# MCP protocol end-to-end tests (real MCP client/server tool calls)
pnpm run test:e2e:mcp

# Website end-to-end tests (Playwright; provisions/validates ephemeral DB first)
pnpm run test:e2e:web

# Full end-to-end suite
pnpm run test:e2e

# Full test pyramid (unit + integration + e2e; used in CI)
pnpm run test

Strategi pengujian:

• Utamakan E2E untuk transport/protokol dan perilaku yang terlihat oleh pengguna.
• Gunakan pengujian integrasi untuk kontrak alat deterministik dan perilaku alur kerja.
• Gunakan pengujian unit untuk logika murni dan kasus tepi.
• Hindari mengandalkan waktu aktif pihak ketiga dalam pengujian merge-gating; tirukan dependensi eksternal di tingkat integrasi/unit.

Penerapan

Vercel menerapkan server jarak jauh secara otomatis dari konfigurasi cabang repositori. Lingkungan pratinjau tersedia untuk pull request.