Model Context Protocol (MCP)

Experimental

Integrasi MCP masih Experimental. Nama tool, format input, dan batas kemampuan dapat berubah pada rilis berikutnya. MCP Web bersifat read-only; untuk MCP lokal, tinjau setiap pemanggilan tool yang akan menulis data dan jangan aktifkan persetujuan otomatis untuk tool write.

MCP memungkinkan aplikasi AI eksternal seperti Codex, Claude, dan VS Code mengakses konteks ERD Builder Pro melalui tool standar. Ini berbeda dari AI Assistant di dalam ERD Builder Pro: percakapan tetap berlangsung di klien AI eksternal, sedangkan ERD Builder Pro menyediakan data dan tindakan yang diizinkan.

Ketersediaan

MCP tersedia melalui dua transport yang terpisah:

• Local stdio: CLI melalui erdbpro mcp dan Desktop melalui erdbpro mcp --desktop;
• Web Streamable HTTP: deployment Web App melalui URL HTTPS yang ditentukan oleh MCP_PUBLIC_URL, dengan OAuth provider local (Pure PostgreSQL) atau supabase.

MCP Web dinonaktifkan secara default dan tidak dapat diaktifkan pada Desktop atau CLI. Untuk Web App Pure PostgreSQL gunakan OAuth lokal; Supabase Auth tetap tersedia sebagai provider alternatif. Docker dapat mengekspos MCP Web selama menjalankan Web App dengan PostgreSQL dan konfigurasi OAuth yang sesuai.

Kemampuan	MCP lokal	MCP Web
Transport	stdio	Streamable HTTP melalui HTTPS
Autentikasi	User instalasi lokal	OAuth 2.1 dengan PKCE (local atau supabase)
Notes, Flowcharts, Drawings, ERD reguler	Ya	Ya, read-only
Riwayat dokumen	Read dan restore terkonfirmasi	Read-only
DB Client / production_db	Read-only terbatas	Tidak tersedia
Operasi write	Proposal/apply tertentu	Tidak tersedia

MCP Web (public API)

Endpoint Web mengikuti spesifikasi otorisasi MCP 2026-07-28. Server memublikasikan OAuth Protected Resource Metadata, mengembalikan challenge Bearer untuk request tanpa token, memvalidasi issuer, audience, masa berlaku, dan client_id. Setiap query hanya dapat membaca dokumen pribadi user OAuth atau dokumen pada Team yang membership-nya masih aktif; MCP tidak menerima scope Team dari klien.

Menentukan domain

Gunakan satu URL kanonis lengkap, termasuk path endpoint:

# Domain yang sama dengan Web App
MCP_PUBLIC_URL=https://app.example.com/api/mcp

# Atau subdomain khusus
# MCP_PUBLIC_URL=https://mcp.example.com/api/mcp

Untuk domain yang sama, tidak ada DNS tambahan. Untuk subdomain khusus, arahkan DNS dan reverse proxy subdomain ke backend ERD Builder Pro yang sama, aktifkan TLS, pertahankan header Host, lalu tambahkan origin Web App ke CORS_ORIGINS. Path request harus sama persis dengan path pada MCP_PUBLIC_URL.

URL kanonis

MCP_PUBLIC_URL juga menjadi OAuth resource identifier. Pada provider supabase, URL ini wajib sama dengan claim JWT aud; pada provider local, URL ini dipakai untuk mengikat resource dan token MCP. Jika URL, domain, atau path berubah, hubungkan ulang klien agar memperoleh token baru.

OAuth lokal untuk Pure PostgreSQL

Gunakan provider local untuk Web App self-hosted yang memakai Pure PostgreSQL. Provider ini menyimpan client, authorization code, access token, dan refresh token MCP secara terpisah dari session login aplikasi.

Atur variabel server berikut lalu restart atau deploy ulang:

DATABASE_URL=postgresql://user:password@db:5432/erd_builder_pro
MCP_PUBLIC_URL=https://app.example.com/api/mcp
MCP_AUTH_PROVIDER=local
MCP_CONSENT_URL=https://app.example.com/oauth/consent

# Jangan set SUPABASE_URL pada mode ini.

MCP_CONSENT_URL boleh dihilangkan jika memakai default origin dari MCP_PUBLIC_URL dengan path /oauth/consent. URL consent harus berada pada deployment Web App yang sama dan memakai HTTPS. User harus login ke Web App sebelum menyetujui akses read-only.

Provider lokal hanya menerima Pure PostgreSQL. Ia tidak aktif pada Desktop/CLI, tidak boleh digabung dengan SUPABASE_URL, dan tidak menggunakan MCP_AUTH_ISSUER_URL.

OAuth Supabase (opsional)

Gunakan provider supabase jika Web App memakai Supabase Auth:

1. Di Supabase Dashboard > Authentication > URL Configuration, set Site URL ke domain Web App yang menampilkan halaman login.
2. Di Authentication > OAuth Server, aktifkan OAuth 2.1 dan set Authorization Path ke /oauth/consent.
3. Aktifkan Dynamic Client Registration jika klien MCP akan mendaftarkan dirinya otomatis. Jika dinonaktifkan, daftarkan setiap klien secara manual.
4. Buat Custom Access Token Hook yang, khusus token OAuth MCP, mengatur claim aud persis ke nilai MCP_PUBLIC_URL. Pertahankan semua claim wajib Supabase dan gunakan client_id untuk membatasi hook ke klien yang diizinkan. Lihat Token Security Supabase.
5. Set variabel server dan deploy ulang:

MCP_PUBLIC_URL=https://app.example.com/api/mcp
MCP_AUTH_PROVIDER=supabase
SUPABASE_URL=https://project-ref.supabase.co
SUPABASE_ANON_KEY=your-anon-key

# Hanya jika Auth memakai custom domain/issuer
# MCP_AUTH_ISSUER_URL=https://auth.example.com/auth/v1

Halaman /oauth/consent menggunakan sesi Web App yang sudah ada. Jika user belum login, aplikasi menampilkan login tanpa membuang authorization_id; setelah login user kembali ke halaman consent untuk menyetujui atau menolak akses.

Untuk detail pengaturan dashboard dan registrasi klien, lihat Supabase OAuth 2.1 Getting Started.

Memverifikasi deployment

Untuk endpoint /api/mcp, metadata berada di:

curl https://app.example.com/.well-known/oauth-protected-resource/api/mcp

Response harus berisi resource yang sama persis dengan MCP_PUBLIC_URL. Pada provider local, authorization_servers memakai root domain Web App; pada provider supabase, nilainya menunjuk ke issuer Supabase. Request MCP tanpa token harus ditolak dengan 401 dan header WWW-Authenticate:

curl -i -X POST https://app.example.com/api/mcp \
  -H 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2026-07-28","capabilities":{},"clientInfo":{"name":"check","version":"1"}}}'

Di klien MCP yang mendukung remote OAuth, tambahkan URL https://app.example.com/api/mcp. Klien akan menemukan issuer, menjalankan OAuth Authorization Code + PKCE, membuka halaman consent ERD Builder Pro, lalu menyimpan access/refresh token sesuai kebijakan klien tersebut.

Tool MCP Web

Tool	Fungsi
workspace_list_files	Daftar project aktif, Notes, Flowcharts, Drawings, dan ERD reguler.
document_read	Membaca satu dokumen Web App yang diizinkan.
history_list	Daftar revisi riwayat dokumen yang diizinkan.
history_read	Membaca satu revisi tanpa restore.

MCP Web tidak mendaftarkan tool DB Client, koneksi database, query SQL, kredensial, filesystem, trash, restore, append, atau write lain. Diagram dengan source_type=production_db disaring dari daftar dan ditolak jika diminta langsung.

MCP lokal (CLI dan Desktop)

Database lokal yang digunakan

erdbpro mcp membaca data instalasi CLI di ~/.erdbpro/data.db. erdbpro mcp --desktop membaca database milik aplikasi Desktop. Keduanya merupakan instalasi terpisah dan tidak otomatis berbagi data.

Persiapan berdasarkan OS

1. Perbarui ERD Builder Pro ke versi yang sudah menyertakan MCP.
2. Buka aplikasi CLI atau Desktop setidaknya satu kali agar database dan user lokal dibuat.
3. Pilih tab OS Anda untuk melihat langkah instalasi. Setelah aplikasi berjalan, konfigurasi klien dibuat dari Settings → MCP Integration.

macOS

CLI

npm install -g erdbpro@latest
erdbpro --version

Pasang Desktop dari rilis .dmg, buka aplikasi sekali, lalu gunakan Settings → MCP Integration. Jangan menyalin path .app atau argumen --mcp secara manual; panel tersebut menyediakan launcher yang benar untuk instalasi aktif.

Windows

CLI

npm install -g erdbpro@latest
erdbpro --version

Pasang Desktop dari rilis .msi, buka aplikasi sekali, lalu gunakan Settings → MCP Integration. Jangan menyalin path .exe atau argumen --mcp secara manual; panel tersebut menyediakan launcher dan escaping Windows yang benar.

Linux

CLI

npm install -g erdbpro@latest
erdbpro --version

Pasang Desktop dari rilis .deb, buka aplikasi sekali, lalu gunakan Settings → MCP Integration. Jangan menyalin path executable atau argumen --mcp secara manual; panel tersebut menyediakan launcher dan escaping POSIX yang benar.

Perintah erdbpro mcp menggunakan stdio, sehingga tidak menampilkan antarmuka web atau membuka port jaringan.

Konfigurasi dari aplikasi Desktop atau CLI

Pada aplikasi Desktop atau CLI, buka Settings → MCP Integration. Halaman ini menampilkan launcher stdio yang sesuai dengan instalasi aktif dan menyediakan konfigurasi siap salin untuk:

• JetBrains AI;
• VS Code;
• Codex;
• Hermes Agent; dan
• klien MCP generik yang mendukung stdio.

Pilih klien, klik Copy, lalu tempel konfigurasi tersebut pada klien AI. command dan args dihasilkan dari runtime aktif, sehingga tidak boleh diganti dengan contoh tetap. Pada Windows, perintah Codex memakai escaping Windows; pada macOS/Linux, memakai quoting POSIX. Untuk satu klien AI, gunakan satu konfigurasi saja agar tidak menjalankan dua server MCP lokal yang sama.

Konfigurasi klien

Codex

Pilih tab Codex, klik Copy, lalu jalankan perintah yang ditampilkan satu kali di terminal. Perintah tersebut sudah memuat command dan args runtime yang benar untuk OS serta instalasi Desktop/CLI aktif. Setelah itu, verifikasi dengan:

codex mcp list

Lihat juga dokumentasi MCP Codex.

JetBrains AI

Buka Settings → Tools → AI Assistant → Model Context Protocol (MCP), lalu salin output dari tab JetBrains AI ke konfigurasi JSON JetBrains. Jangan mengganti command atau args dengan erdbpro mcp.

Lihat juga dokumentasi MCP JetBrains.

Visual Studio Code

Buat .vscode/mcp.json di workspace atau buka MCP: Open User Configuration, lalu tempel output dari tab VS Code. Output tersebut sudah menggunakan format servers dan type: "stdio" yang dibutuhkan VS Code.

Setelah disimpan, jalankan MCP: List Servers lalu mulai atau restart server erdbpro. Lihat referensi konfigurasi MCP VS Code.

Hermes Agent

Pilih tab Hermes Agent, lalu isi dialog Add MCP Server menggunakan nilai yang ditampilkan:

• Name: erdbpro;
• Transport: stdio;
• Command: nilai Command dari panel;
• Args: nilai Args dari panel; dan
• Environment: kosong.

Jangan mengganti nilai tersebut dengan command lama. Jika Args menampilkan (leave empty), biarkan field args kosong.

Generic MCP (STDIO)

Untuk agen lain yang menerima konfigurasi MCP standar, pilih tab Generic MCP (STDIO) dan tempel JSON yang dihasilkan. Gunakan command dan args apa adanya dari panel.

Setelah koneksi berhasil, uji dengan permintaan read-only seperti “daftarkan project dan dokumen Desktop saya”.

Tool lokal yang tersedia

Tool	Akses	Fungsi
workspace_list_files	Read-only	Daftar project, Notes, Flowchart, dan ERD.
document_read	Read-only	Membaca satu Note, Flowchart, atau ERD.
history_list	Read-only	Daftar snapshot pada entity_changes.
history_read	Read-only	Membaca satu snapshot tanpa melakukan restore.
history_restore_propose	Read-only	Membuat preview pemulihan dari snapshot.
history_restore_apply	Write	Menerapkan pemulihan snapshot yang telah dikonfirmasi.
db_list_catalogs	Read-only	Daftar katalog DB Client tanpa password atau kunci TLS.
db_read_schema	Read-only	Membaca tabel, kolom, indeks, check, dan foreign key.
db_query_read_only	Read-only	Menjalankan satu SELECT/CTE pada PostgreSQL atau MySQL.
note_append_propose	Read-only	Membuat preview penambahan teks pada Note.
note_append_apply	Write	Menerapkan proposal Append yang telah dikonfirmasi.

Drawings belum disertakan. Write untuk Flowchart, ERD, struktur database, dan record DB Client juga belum tersedia.

Perlindungan data lokal

• MCP tidak mengirim password database, private key TLS, atau kredensial koneksi ke klien.
• Query DB Client dipaksa menggunakan sesi read-only, hanya menerima satu SELECT/CTE, dan membatasi hasil maksimal 500 baris.
• Append Notes memakai dua tahap: proposal lalu apply dengan ID konfirmasi yang sama.
• Proposal kedaluwarsa setelah 10 menit dan ditolak jika Note berubah setelah preview dibuat.
• Teks yang ditambahkan di-escape sebelum disimpan.
• Sebelum append atau restore diterapkan, versi pengaman disimpan ke entity_changes dengan sumber mcp atau restore.

waspada

Persetujuan tool tetap dikendalikan oleh klien MCP. Periksa nama dokumen, preview, dan isi perubahan sebelum menyetujui note_append_apply atau history_restore_apply.

Contoh penggunaan

• “Daftar semua ERD dalam project ini dan jelaskan tabel yang berhubungan dengan autentikasi.”
• “Baca schema katalog PostgreSQL ini dan sarankan indeks tanpa mengubah database.”
• “Baca riwayat Note ini dan bandingkan dua snapshot terakhir.”
• “Buat proposal untuk mengembalikan ERD ini ke snapshot tertentu, lalu tampilkan preview tanpa menerapkannya.”
• “Buat proposal untuk menambahkan ringkasan berikut ke Note dokumentasi.”
• “Melalui MCP Web, baca Drawings dalam project ini tanpa mengubah workspace.”

Pemecahan masalah

erdbpro: command not found

Pastikan paket CLI terpasang secara global dan direktori binary npm tersedia pada PATH:

npm install -g erdbpro@latest
erdbpro --version

User lokal tidak ditemukan

Buka instalasi ERD Builder Pro yang sama setidaknya satu kali, lalu jalankan ulang klien MCP.

Terdapat beberapa user lokal

Tetapkan user secara eksplisit melalui environment variable ERDBPRO_MCP_USER_ID pada konfigurasi MCP klien.

Koneksi DB Client gagal

Uji koneksi dari panel DB Client terlebih dahulu. MCP memakai account, mode TLS, safe mode, dan timeout yang tersimpan di aplikasi tanpa mengekspos kredensial tersebut.

MCP Web selalu mengembalikan 401

Pastikan MCP_PUBLIC_URL benar-benar sama dengan URL yang dimasukkan ke klien, termasuk path /api/mcp, lalu hubungkan ulang klien setelah mengubahnya. Untuk MCP_AUTH_PROVIDER=local, pastikan DATABASE_URL Pure PostgreSQL, SUPABASE_URL tidak diatur, dan consent sudah disetujui oleh user Web App yang benar. Untuk MCP_AUTH_PROVIDER=supabase, token harus memiliki iss yang sama dengan MCP_AUTH_ISSUER_URL (atau ${SUPABASE_URL}/auth/v1), claim client_id, claim exp, dan claim aud yang sama persis dengan MCP_PUBLIC_URL. Token sesi Web App biasa memiliki audience berbeda dan sengaja ditolak.

Metadata OAuth tidak ditemukan

Pastikan reverse proxy meneruskan path /.well-known/oauth-protected-resource/... ke backend yang sama. Untuk MCP_PUBLIC_URL=https://mcp.example.com/api/mcp, path metadata adalah /.well-known/oauth-protected-resource/api/mcp pada host mcp.example.com.