Couchbase
resmiBerinteraksi dengan data yang tersimpan di klaster Couchbase menggunakan bahasa alami.
Apa yang bisa Anda lakukan dengan Couchbase MCP?
- Jelajahi data cluster — Daftar bucket, scope, dan collection, lalu simpulkan skema collection seperti
orders. - Jalankan kueri SQL++ — Jalankan kueri SQL++ hanya-baca pada bucket dan scope, serta jelaskan rencana kueri.
- Periksa dokumen — Ambil dokumen berdasarkan ID atau baca jalur subdokumen tertentu tanpa memuat seluruh dokumen.
- Periksa kesehatan cluster — Laporkan kesehatan cluster, layanan yang berjalan, dan diagnostik koneksi.
- Analisis performa kueri — Temukan kueri dengan waktu eksekusi terlama, paling sering dijalankan, atau tidak tercakup oleh indeks.
- Pencarian dan kueri vektor — Jalankan pencarian teks lengkap dan kueri kemiripan vektor pada indeks yang dikonfigurasi.
Dokumentasi
Couchbase MCP Server
Couchbase MCP Server adalah Server MCP yang dihosting sendiri dan memungkinkan agen AI terhubung serta berinteraksi dengan data di Couchbase Server (baik yang dihosting di Capella maupun yang dikelola sendiri) atau Operational Insights Enterprise. Server ini menyediakan berbagai alat dalam kategori seperti Kesehatan Klaster, Skema Data, Kueri, dan lainnya — dengan kontrol keamanan melalui mode hanya baca dan penonaktifan alat secara terperinci. Server ini mendukung transportasi STDIO dan Streamable HTTP dengan kemampuan OAuth.
Couchbase MCP Server didistribusikan sebagai paket Python Package Index (PyPI) dan melalui Docker. Dukungan enterprise untuk Couchbase MCP Server tersedia dengan melisensikan Couchbase AI Data Plane, yang juga memberikan hak penggunaan dan dukungan enterprise untuk Couchbase Agent Memory dan Couchbase Agent Catalog.
Dokumentasi lengkap: docs.couchbase.com/mcp-server
Daftar Isi
- Alasan menggunakan Couchbase MCP Server
- Memilih Server
- Server Operasional
- Server Operational Insights
- Konfigurasi Umum
- Penyiapan Klien
- Docker
- Pemecahan Masalah
- FAQ
- Berkontribusi
- Data Penggunaan, Risiko LLM, dan Kebijakan Dukungan
Alasan menggunakan Couchbase MCP Server
- Aman secara default — alat tulis tidak dimuat dan kueri yang mengubah data diblokir kecuali Anda menetapkan
CB_MCP_READ_ONLY_MODE=false; alat tertentu juga dapat dinonaktifkan atau dibatasi dengan konfirmasi pengguna. - Couchbase Server dan Operational Insights — server operasional terhubung ke Couchbase Capella atau klaster Couchbase Server yang dikelola sendiri dengan konfigurasi yang sama; server Operational Insights terhubung ke klaster Operational Insights yang dikelola sendiri.
- Memperhatikan RBAC — kontrol alat memandu LLM; kontrol akses berbasis peran pengguna Couchbase tetap menjadi batas keamanan yang berwenang.
- Transportasi untuk produksi — STDIO untuk klien desktop lokal, atau Streamable HTTP dengan OAuth 2.1 opsional (IdP apa pun yang menerbitkan JWKS: Auth0, Okta, Keycloak, Entra, Cognito, …), pemeriksaan kesehatan, dan pencatatan audit untuk deployment bersama. Server operasional juga dapat menjalankan beberapa worker untuk memanfaatkan lebih banyak inti CPU.
- Klien MCP apa pun — telah diuji dengan Claude Desktop, Cursor, Windsurf, VS Code, dan JetBrains AI Assistant/Junie.
Setelah terhubung, Anda dapat mengajukan pertanyaan seperti:
- "Bucket, scope, dan collection apa saja yang saya miliki, dan bagaimana skema collection
orders?" - "Temukan 10 dokumen terbaru di
usersyang memenuhistatus = 'active'." - "Apa 5 kueri paling lambat dalam satu jam terakhir, dan apakah ada yang tidak memiliki indeks penutup?"
- "Apakah klaster ini sehat, dan layanan apa saja yang sedang berjalan?"
- "Sisipkan dokumen baru ke
productsdengan bidang-bidang berikut: …" (memerlukanCB_MCP_READ_ONLY_MODE=false)
Memilih Server
Paket ini menyediakan dua server MCP. Masing-masing dijalankan dengan subperintah tersendiri, terhubung ke jenis klaster yang berbeda, dan memiliki alatnya sendiri. Pilih server yang sesuai dengan klaster Anda, ikuti bagian penyiapan dan alatnya, lalu gunakan Konfigurasi Umum untuk pengaturan yang digunakan bersama. Untuk menggunakan keduanya, daftarkan masing-masing sebagai server terpisah di klien MCP Anda.
| Server operasional | Server Operational Insights | |
|---|---|---|
| Gunakan dengan | Klaster Couchbase (Capella atau dikelola sendiri) | Klaster Operational Insights yang dikelola sendiri (tidak tersedia di Capella) |
| Subperintah | operational (default) | operational-insights |
| String koneksi | couchbase:// / couchbases:// | URL HTTP(S), misalnya http://localhost:8095 |
| Variabel kredensial | CB_CONNECTION_STRING, CB_USERNAME, … | CB_OPERATIONAL_INSIGHTS_CONNECTION_STRING, CB_OPERATIONAL_INSIGHTS_USERNAME, … |
| Alat | 52 — kesehatan klaster, skema, KV, SQL++, indeks, pencarian teks lengkap dan vektor, performa kueri | 13 — skema, SQL++ (sinkron dan asinkron), indeks, ekspor |
| Port HTTP default | 8000 | 8001 |
| File log default | mcp_server.log | mcp_server_operational_insights.log |
Saat ini, subperintah bersifat opsional untuk server operasional —
couchbase-mcp-servertanpa argumen akan menjalankannya — tetapi mencantumkan subperintah membuat konfigurasi Anda tidak ambigu. Opsi ditulis setelah subperintah:couchbase-mcp-server operational --transport=http. Periksa versi yang terpasang denganuvx couchbase-mcp-server --version.
Server Operasional
Server operational terhubung ke klaster Couchbase di Capella atau Couchbase Server yang dikelola sendiri, menggunakan SDK Python couchbase.
Mulai Cepat Operasional
Anda memerlukan klaster Couchbase yang sedang berjalan — tingkat gratis Capella adalah cara tercepat untuk mendapatkannya (Anda dapat mengimpor set data contoh) — dan klien MCP. Tambahkan satu konfigurasi berikut ke klien Anda (lihat Penyiapan Klien untuk mengetahui lokasi konfigurasi setiap klien). Jika klien sudah memiliki server lain, tambahkan couchbase ke objek mcpServers yang sudah ada.
Dari PyPI dengan uvx (memerlukan uv dan Python 3.11+):
{
"mcpServers": {
"couchbase": {
"command": "uvx",
"args": ["couchbase-mcp-server", "operational"],
"env": {
"CB_CONNECTION_STRING": "couchbases://connection-string",
"CB_USERNAME": "username",
"CB_PASSWORD": "password"
}
}
}
}
Dengan Docker (hanya memerlukan Docker):
{
"mcpServers": {
"couchbase": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"-e", "CB_CONNECTION_STRING=couchbases://connection-string",
"-e", "CB_USERNAME=username",
"-e", "CB_PASSWORD=password",
"couchbase/mcp-server:latest", "operational"
]
}
}
}
Dari sumber
git clone https://github.com/couchbase/mcp-server-couchbase.git
{
"mcpServers": {
"couchbase": {
"command": "uv",
"args": [
"--directory", "path/to/cloned/repo/mcp-server-couchbase/",
"run", "src/mcp_server.py", "operational"
],
"env": {
"CB_CONNECTION_STRING": "couchbases://connection-string",
"CB_USERNAME": "username",
"CB_PASSWORD": "password"
}
}
}
}
path/to/cloned/repo/mcp-server-couchbase/ adalah jalur ke klon Anda — pertahankan garis miring di akhir. Setelah mengambil pembaruan, jalankan uv sync untuk memperbarui dependensi.
Koneksi dan Autentikasi Operasional
Gunakan salah satu dari nama pengguna dan kata sandi atau sertifikat klien (mTLS). Jika keduanya ditetapkan, sertifikat yang digunakan.
| Variabel Lingkungan | Argumen CLI | Deskripsi |
|---|---|---|
CB_CONNECTION_STRING | --connection-string | String koneksi ke klaster. Wajib |
CB_USERNAME / CB_PASSWORD | --username / --password | Autentikasi dasar |
CB_CLIENT_CERT_PATH / CB_CLIENT_KEY_PATH | --client-cert-path / --client-key-path | Autentikasi mTLS |
CB_CA_CERT_PATH | --ca-cert-path | Sertifikat root untuk sertifikat server yang ditandatangani sendiri/tidak tepercaya (tidak diperlukan untuk Capella) |
Contoh mTLS
{
"mcpServers": {
"couchbase": {
"command": "uvx",
"args": ["couchbase-mcp-server", "operational"],
"env": {
"CB_CONNECTION_STRING": "couchbases://connection-string",
"CB_CLIENT_CERT_PATH": "/path/to/client-certificate.pem",
"CB_CLIENT_KEY_PATH": "/path/to/client.key"
}
}
}
}
Alat Operasional
Alat tulis (ditandai ✏️) tidak dimuat saat mode hanya baca aktif, yang merupakan pengaturan default. Alat yang ditandai 🖥️ hanya untuk penggunaan mandiri — alat tersebut menggunakan endpoint REST admin yang tidak diekspos Capella, atau (discover_tool_input_values) hanya menyediakan data referensi untuk alat yang menggunakannya — sehingga memerlukan Couchbase Server 7.6+ yang dikelola sendiri dan tidak didaftarkan pada koneksi Capella.
Penyiapan dan kesehatan klaster
| Alat | Deskripsi |
|---|---|
get_server_configuration_status | Status dan konfigurasi server tanpa terhubung ke klaster: mode hanya baca, alat yang dinonaktifkan/memerlukan konfirmasi, OAuth, pencatatan log, dan penghitung audit |
test_cluster_connection | Periksa kredensial klaster dengan menghubungkan ke klaster |
get_cluster_health_and_services | Kesehatan klaster dan layanan yang berjalan, dengan pemfilteran opsional melalui service_types |
get_client_connectivity_report | Diagnostik koneksi SDK yang tersimpan dalam cache, tanpa pemeriksaan jaringan aktif |
get_cluster_metrics 🖥️ | Statistik klaster dalam rentang waktu historis (endpoint stats-range) |
get_cluster_tasks 🖥️ | Tugas yang sedang berjalan — rebalance, compaction, XDCR, pembuatan indeks. Memerlukan ro_admin |
get_cluster_health_snapshot 🖥️ | Kesehatan per node: topologi layanan, keanggotaan, orchestrator, dan ringkasan kesehatan. Memerlukan ro_admin |
get_bucket_config 🖥️ | Konfigurasi dan status langsung sebuah bucket (atau semua bucket) — kuota, eviction, replika, durabilitas, penyimpanan, compaction. Memerlukan ro_admin |
get_cluster_system_events 🖥️ | Log peristiwa sistem (perubahan konfigurasi, failover, rebalance, mulai ulang), dibatasi rentang waktunya dengan since_time. Memerlukan Full Admin atau Cluster Admin |
discover_tool_input_values 🖥️ | Cari nilai input persis yang diperlukan alat lain (misalnya, setiap nama metrik untuk get_cluster_metrics). Dapat digunakan secara offline |
Penemuan model data dan skema
| Alat | Deskripsi |
|---|---|
get_buckets_in_cluster | Cantumkan semua bucket di klaster |
get_scopes_in_bucket | Cantumkan semua scope dalam bucket |
get_collections_in_scope | Cantumkan semua collection dalam scope (memerlukan layanan Query) |
get_scopes_and_collections_in_bucket | Cantumkan semua scope dan collection dalam bucket |
get_schema_for_collection | Simpulkan struktur sebuah collection |
create_scope ✏️ | Buat scope dalam bucket (Server 7.6+ dan Capella) |
create_collection ✏️ | Buat collection dalam scope yang sudah ada (Server 7.6+ dan Capella) |
delete_scope ✏️ | Hapus scope beserta semua collection-nya — permanen |
delete_collection ✏️ | Hapus collection beserta semua dokumennya — permanen |
Operasi dokumen (KV)
| Alat | Deskripsi |
|---|---|
get_document_by_id | Dapatkan dokumen berdasarkan ID |
lookup_subdocument | Baca jalur tertentu, periksa keberadaan, atau hitung tanpa mengambil seluruh dokumen |
upsert_document_by_id ✏️ | Upsert dokumen berdasarkan ID |
insert_document_by_id ✏️ | Sisipkan dokumen baru (gagal jika dokumen sudah ada) |
replace_document_by_id ✏️ | Ganti dokumen yang sudah ada (gagal jika dokumen belum ada) |
delete_document_by_id ✏️ | Hapus dokumen berdasarkan ID |
mutate_subdocument ✏️ | Ubah jalur dalam dokumen yang sudah ada (upsert, insert, replace, remove, operasi array, penghitung) |
Kueri dan pengindeksan
| Alat | Deskripsi |
|---|---|
run_sql_plus_plus_query | Jalankan kueri SQL++ yang dibatasi ke bucket dan scope — gunakan nama collection secara langsung (SELECT * FROM users). Pernyataan yang mengubah data diblokir dalam mode hanya baca |
explain_sql_plus_plus_query | Buat dan evaluasi rencana EXPLAIN: metadata, rencana yang diekstrak, dan temuan |
get_index_advisor_recommendations | Rekomendasi Index Advisor untuk kueri SQL++ |
list_indexes | Cantumkan indeks beserta definisinya, dapat difilter berdasarkan bucket/scope/collection/nama; menandai indeks vektor (is_vector, vector_type) |
get_index_stats 🖥️ | Ukuran, fragmentasi, lalu lintas pemindaian, dan keterlambatan per indeks dan per node — menemukan tekanan dan indeks yang tidak digunakan |
create_query_index ✏️ | Buat indeks GSI skalar, vektor Hyperscale, atau vektor komposit (index_type). Secara default ditangguhkan — lanjutkan dengan build_index |
create_index ✏️ | Usang — gunakan create_query_index. Dihapus pada versi 2.0 |
build_index ✏️ | Bangun semua indeks yang ditangguhkan pada collection |
drop_index ✏️ | Hapus indeks GSI (skalar atau vektor) |
Pencarian teks lengkap (FTS)
Memerlukan Couchbase Server 7.6+ dan layanan Search. Indeks tingkat scope dan tingkat klaster (lama) sama-sama didukung: berikan bucket_name dan scope_name secara bersamaan untuk tingkat scope, atau hilangkan keduanya.
| Tool | Deskripsi |
|---|---|
list_search_indexes | Mencantumkan indeks Search — tingkat cluster, per bucket, atau per scope |
get_search_index_definition | Definisi lengkap satu indeks Search (pemetaan, analyzer, parameter plan) |
run_search | Menjalankan kueri FTS non-vektor apa pun dari isi JSON mentahnya; explain=true menampilkan rencana eksekusi |
upsert_search_index ✏️ | Membuat atau memperbarui indeks Search, termasuk pemetaan field vektor. Pembaruan memicu pembangunan ulang penuh — teruskan uuid saat ini agar perubahan serentak tidak tertimpa |
drop_search_index ✏️ | Menghapus indeks Search — permanen |
Pencarian vektor
Kedua tool menyematkan teks kueri biasa menggunakan model yang dikonfigurasi di Penyedia Embedding. Tersedia di Couchbase Server yang dikelola sendiri dan Capella.
| Tool | Deskripsi |
|---|---|
run_vector_query | Pencarian kemiripan pada indeks vektor GSI (Server 8.0+) melalui APPROX_VECTOR_DISTANCE(). Indeks dipilih secara otomatis; mendukung prapenyaringan SQL++ where dan penyetelan Hyperscale (num_probes, rerank, top_n_scan). Mengembalikan dokumen lengkap |
run_vector_search | Pencarian vektor Search Service (Server 7.6+) pada indeks bernama. scalar_query menjadikannya hibrida; prefilter mempersempit kandidat terlebih dahulu. Mengembalikan field yang disimpan dalam indeks untuk setiap hasil |
Analisis performa kueri
| Tool | Deskripsi |
|---|---|
get_longest_running_queries | Kueri dengan waktu layanan rata-rata terlama |
get_most_frequent_queries | Kueri yang paling sering dijalankan |
get_queries_with_largest_response_sizes | Kueri dengan ukuran respons terbesar |
get_queries_with_large_result_count | Kueri dengan jumlah hasil terbanyak |
get_queries_using_primary_index | Kueri yang menggunakan indeks primer |
get_queries_not_using_covering_index | Kueri yang tidak menggunakan indeks covering |
get_queries_not_selective | Kueri yang pemindaiannya — indeks sekunder, indeks primer, atau sekuensial — mengembalikan jauh lebih banyak dokumen daripada hasil akhir |
Kesehatan Query Service 🖥️
Tool ini memanggil REST API admin milik Query Service sendiri pada setiap node kueri.
| Tool | Deskripsi |
|---|---|
get_cluster_query_vitals | Kesehatan mesin kueri: laju permintaan, permintaan aktif/antrean, memori, GC, waktu aktif. Memerlukan ro_admin |
get_active_queries | Kueri yang sedang berjalan saat ini di semua node kueri. Memerlukan ro_admin |
delete_active_query ✏️ | Membatalkan kueri yang sedang berjalan berdasarkan ID permintaan. Memerlukan Full Admin atau Cluster Admin |
Tool yang dinonaktifkan secara otomatis di Capella
Tool 🖥️ mengakses Couchbase melalui endpoint REST admin yang tidak diekspos Capella (satu pengecualian, discover_tool_input_values, tidak disertakan karena hanya melayani tool yang memerlukannya). Jika setiap host di CB_CONNECTION_STRING diakhiri dengan .cloud.couchbase.com, server tidak mendaftarkan tool tersebut dan melaporkannya bersama tool yang dinonaktifkan milik Anda di get_server_configuration_status dan log startup. Tool berbasis SDK seperti get_cluster_health_and_services dan get_client_connectivity_report tetap tersedia.
| Tool | Endpoint yang diperlukan |
|---|---|
get_cluster_metrics | REST Management (/pools/default/stats/range) |
get_cluster_tasks | REST Management (/pools/default/tasks) |
get_bucket_config | REST Management (/pools/default/buckets[/<name>]) |
get_cluster_health_snapshot | REST Management, ditambah endpoint per node |
get_cluster_system_events | REST Management (/events) |
get_index_stats | REST Index Service (masing-masing /api/v1/stats milik pengindeks) |
get_cluster_query_vitals | REST Query Service (/admin/vitals) |
get_active_queries | REST Query Service (/admin/active_requests) |
delete_active_query | REST Query Service (DELETE /admin/active_requests/{id}) |
discover_tool_input_values | Tidak ada (berfungsi offline), tetapi hanya melayani get_cluster_metrics, yang tidak tersedia di Capella |
Penyedia Embedding
run_vector_query dan run_vector_search menyematkan teks kueri menggunakan penyedia yang ditetapkan di CB_MCP_EMBEDDING_MODEL_PROVIDER. Ini opsional: tanpa pengaturan ini, server tetap berjalan normal dan kedua tool tetap terdaftar, tetapi pemanggilannya akan menghasilkan error yang menjelaskan pengaturan yang perlu ditetapkan.
CB_MCP_EMBEDDING_MODEL_PROVIDER | Wajib | Opsional | Catatan |
|---|---|---|---|
capella | CB_MCP_EMBEDDING_MODEL_API_KEY, CB_MCP_EMBEDDING_MODEL, CB_MCP_EMBEDDING_MODEL_ENDPOINT | — | Capella Model Service. CB_MCP_EMBEDDING_MODEL_ENDPOINT adalah URL milik deployment Anda sendiri (misalnya https://<id>.ai.couchbase.com) dari Capella's AI Data Plane > Models |
openai | CB_MCP_EMBEDDING_MODEL_API_KEY, CB_MCP_EMBEDDING_MODEL | CB_MCP_EMBEDDING_MODEL_ENDPOINT | Tetapkan endpoint untuk menggunakan server lokal yang kompatibel dengan OpenAI (Ollama, vLLM, LM Studio) |
cohere | CB_MCP_EMBEDDING_MODEL_API_KEY, CB_MCP_EMBEDDING_MODEL | CB_MCP_EMBEDDING_MODEL_ENDPOINT | |
voyage | CB_MCP_EMBEDDING_MODEL_API_KEY, CB_MCP_EMBEDDING_MODEL | CB_MCP_EMBEDDING_MODEL_ENDPOINT | |
bedrock | CB_MCP_EMBEDDING_MODEL | CB_MCP_EMBEDDING_MODEL_AWS_ACCESS_KEY_ID, CB_MCP_EMBEDDING_MODEL_AWS_SECRET_ACCESS_KEY, CB_MCP_EMBEDDING_MODEL_AWS_REGION | Model embedding Amazon Titan (misalnya amazon.titan-embed-text-v2:0) — penyedia mengirim bentuk permintaan inputText milik Titan, sehingga model embedding Bedrock lainnya seperti Cohere Embed belum didukung. Hilangkan kredensial untuk menggunakan rantai AWS default. Memerlukan tambahan: pip install couchbase-mcp-server[bedrock-embeddings] |
"env": {
"CB_CONNECTION_STRING": "couchbases://connection-string",
"CB_USERNAME": "username",
"CB_PASSWORD": "password",
"CB_MCP_EMBEDDING_MODEL_PROVIDER": "openai",
"CB_MCP_EMBEDDING_MODEL": "text-embedding-3-small",
"CB_MCP_EMBEDDING_MODEL_API_KEY": "sk-..."
}
Semua Opsi
Setiap variabel lingkungan dan flag CLI untuk server operational server
Server Operational Insights menerima opsi yang sama, kecuali server ini memiliki pengaturan koneksi sendiri dan tidak memiliki opsi CB_MCP_EMBEDDING_MODEL_*.
| Variabel Lingkungan | Argumen CLI | Deskripsi | Default |
|---|---|---|---|
CB_CONNECTION_STRING | --connection-string | String koneksi ke klaster Couchbase | Wajib |
CB_USERNAME | --username | Nama pengguna dengan akses ke bucket yang diperlukan untuk autentikasi dasar | Wajib (atau Sertifikat dan Kunci Klien diperlukan untuk mTLS) |
CB_PASSWORD | --password | Kata sandi untuk autentikasi dasar | Wajib (atau Sertifikat dan Kunci Klien diperlukan untuk mTLS) |
CB_CLIENT_CERT_PATH | --client-cert-path | Jalur ke file sertifikat klien untuk autentikasi mTLS | Wajib jika menggunakan mTLS (atau Nama Pengguna dan Kata Sandi diperlukan) |
CB_CLIENT_KEY_PATH | --client-key-path | Jalur ke file kunci klien untuk autentikasi mTLS | Wajib jika menggunakan mTLS (atau Nama Pengguna dan Kata Sandi diperlukan) |
CB_CA_CERT_PATH | --ca-cert-path | Jalur ke sertifikat root server untuk TLS jika server dikonfigurasi dengan sertifikat yang ditandatangani sendiri/tidak tepercaya. Ini tidak diperlukan jika Anda terhubung ke Capella | |
CB_MCP_READ_ONLY_MODE | --read-only-mode | Cegah semua modifikasi data (KV, Query, pengelolaan scope/collection, pengelolaan indeks, dan pengelolaan indeks FTS). Jika diaktifkan, alat tulis tidak dimuat. | true |
CB_MCP_TRANSPORT | --transport | Mode transportasi: stdio, http | stdio |
CB_MCP_HOST | --host | Host untuk mode transportasi HTTP | 127.0.0.1 |
CB_MCP_PORT | --port | Port untuk mode transportasi HTTP | 8000 |
CB_MCP_WORKERS | --workers | Jumlah proses pekerja server untuk transportasi http. Nilai di atas 1 menjalankan mode HTTP stateless (lihat Beberapa Pekerja) | 1 |
CB_MCP_STATELESS_HTTP | --stateless-http | Tangani setiap permintaan HTTP tanpa status per sesi. Hanya berlaku dengan http; tidak dapat digabungkan dengan alat yang memerlukan konfirmasi (lihat Beberapa Pekerja) | true jika pekerja > 1, jika tidak false |
CB_MCP_DISABLED_TOOLS | --disabled-tools | Alat yang dinonaktifkan (lihat Menonaktifkan Alat) | Tidak ada |
CB_MCP_CONFIRMATION_REQUIRED_TOOLS | --confirmation-required-tools | Alat yang memerlukan konfirmasi eksplisit pengguna sebelum dijalankan melalui elisitasi MCP (lihat Memerlukan konfirmasi) | Tidak ada |
CB_MCP_LOG_LEVEL | --log-level | Tingkat pencatatan log untuk server MCP: off, debug, info, warning, error (lihat Pencatatan Log) | info |
CB_MCP_LOG_SINKS | --log-sinks | Tujuan log yang dipisahkan koma: stderr, file, atau keduanya (lihat Pencatatan Log) | stderr |
CB_MCP_LOG_FILE | --log-file | Jalur dasar untuk file log per tingkat (hanya digunakan saat sink file diaktifkan) | mcp_server.log |
CB_MCP_LOG_ROTATION_MAX_SIZE_MB | --log-rotation-max-size-mb | Ukuran maksimum global dalam MB untuk setiap file log sebelum dirotasi, diwarisi oleh setiap tingkat kecuali ditimpa. 0 — atau nilai yang tidak dapat digunakan, seperti nilai negatif, nan atau inf — tidak valid dan akan menggunakan nilai default disertai peringatan saat startup | 1 (1 MB) |
CB_MCP_LOG_MAX_BYTES | --log-max-bytes | Usang — gunakan CB_MCP_LOG_ROTATION_MAX_SIZE_MB (MB). Ukuran rotasi global dalam byte, tetap didukung untuk kompatibilitas mundur; diabaikan jika CB_MCP_LOG_ROTATION_MAX_SIZE_MB juga ditetapkan | Tidak ditetapkan |
CB_MCP_LOG_ERROR_ROTATION_MAX_SIZE_MB | --log-error-rotation-max-size-mb | Ukuran rotasi dalam MB untuk file log ERROR; menimpa CB_MCP_LOG_ROTATION_MAX_SIZE_MB untuk ERROR | Mewarisi CB_MCP_LOG_ROTATION_MAX_SIZE_MB |
CB_MCP_LOG_WARNING_ROTATION_MAX_SIZE_MB | --log-warning-rotation-max-size-mb | Ukuran rotasi dalam MB untuk file log WARNING; menimpa CB_MCP_LOG_ROTATION_MAX_SIZE_MB untuk WARNING | Mewarisi CB_MCP_LOG_ROTATION_MAX_SIZE_MB |
CB_MCP_LOG_INFO_ROTATION_MAX_SIZE_MB | --log-info-rotation-max-size-mb | Ukuran rotasi dalam MB untuk file log INFO; menimpa CB_MCP_LOG_ROTATION_MAX_SIZE_MB untuk INFO | Mewarisi CB_MCP_LOG_ROTATION_MAX_SIZE_MB |
CB_MCP_LOG_DEBUG_ROTATION_MAX_SIZE_MB | --log-debug-rotation-max-size-mb | Ukuran rotasi dalam MB untuk file log DEBUG; menimpa CB_MCP_LOG_ROTATION_MAX_SIZE_MB untuk DEBUG | Mewarisi CB_MCP_LOG_ROTATION_MAX_SIZE_MB |
CB_MCP_LOG_RETENTION_BACKUP_COUNT | --log-retention-backup-count | Jumlah file cadangan hasil rotasi yang disimpan untuk setiap file log per tingkat (tidak termasuk file aktif), diterapkan ke setiap tingkat kecuali ditimpa. 0 hanya menyimpan file aktif (lihat Pencatatan Log) | 1 |
CB_MCP_LOG_ERROR_RETENTION_BACKUP_COUNT | --log-error-retention-backup-count | Jumlah cadangan hasil rotasi yang disimpan untuk file log ERROR; menimpa jumlah global untuk ERROR | Mewarisi CB_MCP_LOG_RETENTION_BACKUP_COUNT |
CB_MCP_LOG_WARNING_RETENTION_BACKUP_COUNT | --log-warning-retention-backup-count | Jumlah cadangan hasil rotasi yang disimpan untuk file log WARNING; menimpa jumlah global untuk WARNING | Mewarisi CB_MCP_LOG_RETENTION_BACKUP_COUNT |
CB_MCP_LOG_INFO_RETENTION_BACKUP_COUNT | --log-info-retention-backup-count | Jumlah cadangan hasil rotasi yang disimpan untuk file log INFO; menimpa jumlah global untuk INFO | Mewarisi CB_MCP_LOG_RETENTION_BACKUP_COUNT |
CB_MCP_LOG_DEBUG_RETENTION_BACKUP_COUNT | --log-debug-retention-backup-count | Jumlah cadangan hasil rotasi yang disimpan untuk file log DEBUG; menimpa jumlah global untuk DEBUG | Mewarisi CB_MCP_LOG_RETENTION_BACKUP_COUNT |
CB_MCP_OAUTH_JWT_JWKS_URI | --oauth-jwks-uri | Endpoint JWKS penyedia identitas yang digunakan untuk memverifikasi JWT bearer. Mengaktifkan OAuth jika ditetapkan bersama issuer dan audience (lihat Otorisasi OAuth 2.1) | Tidak ada |
CB_MCP_OAUTH_JWT_ISSUER | --oauth-issuer | Klaim JWT iss yang diharapkan. Wajib untuk mengaktifkan OAuth | Tidak ada |
CB_MCP_OAUTH_JWT_AUDIENCE | --oauth-audience | Klaim JWT aud yang diharapkan. Wajib untuk mengaktifkan OAuth | Tidak ada |
CB_MCP_OAUTH_JWT_ALGORITHM | --oauth-algorithm | Algoritma penandatanganan JWT: salah satu dari RS256/384/512, ES256/384/512, PS256/384/512 | RS256 |
CB_MCP_OAUTH_MCP_BASE_URL | --oauth-mcp-base-url | URL dasar publik server ini. Jika ditetapkan, akan menerbitkan Protected Resource Metadata RFC 9728 agar klien yang mendukung PRM dapat menemukan IdP | Tidak ada |
CB_MCP_OAUTH_SCOPE_READ_LABEL | --oauth-scope-read-label | Ganti label scope OAuth yang diperlakukan sebagai akses 'baca' (diiklankan dalam PRM dan dicocokkan dengan klaim scope/scp token). Gunakan jika IdP Anda tidak dapat mengeluarkan bentuk kanonis | couchbase-mcp:read |
CB_MCP_OAUTH_SCOPE_WRITE_LABEL | --oauth-scope-write-label | Ganti label scope OAuth yang diperlakukan sebagai akses 'tulis'; semantiknya sama dengan label baca | couchbase-mcp:write |
CB_MCP_AUDIT_LOG_ENABLED | --audit-log-enabled | Aktifkan pencatatan audit — sink terpisah dari log operasional CB_MCP_LOG_*, dengan skema stabil dan retensinya sendiri (lihat Audit) | false |
CB_MCP_AUDIT_LOG_SINKS | --audit-log-sinks | Tujuan audit yang dipisahkan koma: console, file, atau keduanya. console menulis ke stderr — tidak pernah ke stdout, yang membawa protokol JSON-RPC pada stdio | console |
CB_MCP_AUDIT_LOG_FILE_PATH | --audit-log-file-path | Jalur ke file log audit. Wajib jika file ada di dalam sink; nama host dan ID proses disisipkan sebelum ekstensi (audit.log → audit.<host>.<pid>.log) | Tidak ada |
CB_MCP_AUDIT_LOG_ROTATION_MAX_SIZE_MB | --audit-log-rotation-max-size-mb | Ukuran maksimum dalam MB yang dapat dicapai file audit aktif sebelum dirotasi. 0 menonaktifkan rotasi berbasis ukuran | 10 (10 MB) |
CB_MCP_AUDIT_LOG_ROTATION_INTERVAL | --audit-log-rotation-interval | Usia maksimum file audit aktif sebelum dirotasi, sebagai <value><unit> dengan satuan d (24 jam) atau w (7 hari) — misalnya 1d, 30d, 8w. 0 menonaktifkan rotasi berbasis interval | 1d |
CB_MCP_AUDIT_LOG_RETENTION_MAX_BACKUPS | --audit-log-retention-max-backups | Cadangan hasil rotasi yang disimpan untuk setiap file audit, tidak termasuk file aktif. Cadangan dikompresi dengan gzip. 0 tidak menyimpan cadangan. Ini membatasi satu file, bukan direktori — lihat Audit | 10 |
CB_MCP_AUDIT_LOG_TOOL_ARGS | --audit-log-tool-args | Catat nilai argumen alat dalam log audit. Dinonaktifkan secara default — rilis ini tidak memiliki penyamaran, sehingga mengaktifkannya akan menulis argumen apa adanya, termasuk isi dokumen lengkap | false |
CB_MCP_AUDIT_LOG_DISABLED_EVENTS | --audit-log-disabled-events | Peristiwa audit yang akan disembunyikan: ID peristiwa numerik yang dipisahkan koma (misalnya 61490,61492), atau file dengan satu ID per baris. Hanya peristiwa yang dapat difilter yang bisa disembunyikan | Tidak ada |
CB_MCP_EMBEDDING_MODEL_PROVIDER | --embedding-model-provider | Penyedia embedding untuk run_vector_query / run_vector_search: salah satu dari capella, openai, cohere, voyage, bedrock. Jika tidak ditetapkan, langkah embedding kedua alat dinonaktifkan hingga dikonfigurasi — lihat Konfigurasi Penyedia Embedding | Tidak ada |
CB_MCP_EMBEDDING_MODEL | --embedding-model | Nama/ID model untuk penyedia embedding yang dikonfigurasi | Tidak ada |
CB_MCP_EMBEDDING_MODEL_API_KEY | --embedding-model-api-key | Kunci API untuk penyedia yang dikonfigurasi. Tidak digunakan oleh bedrock (menggunakan rantai kredensial AWS / CB_MCP_EMBEDDING_MODEL_AWS_*) | Tidak ada |
CB_MCP_EMBEDDING_MODEL_ENDPOINT | --embedding-model-endpoint | Penggantian URL dasar (server lokal yang kompatibel dengan OpenAI, atau URL milik deployment Capella Model Service — wajib saat CB_MCP_EMBEDDING_MODEL_PROVIDER=capella) | Tidak ada |
CB_MCP_EMBEDDING_MODEL_AWS_ACCESS_KEY_ID | --embedding-model-aws-access-key-id | ID kunci akses AWS, hanya untuk penyedia bedrock. Abaikan untuk menggunakan rantai kredensial AWS default | Tidak ada |
CB_MCP_EMBEDDING_MODEL_AWS_SECRET_ACCESS_KEY | --embedding-model-aws-secret-access-key | Kunci akses rahasia AWS, hanya untuk penyedia bedrock | Tidak ada |
CB_MCP_EMBEDDING_MODEL_AWS_REGION | --embedding-model-aws-region | Wilayah AWS, hanya untuk penyedia bedrock. Jika tidak ditetapkan, akan menggunakan resolusi wilayah milik AWS SDK | Tidak ada |
Server Operational Insights
Server operational-insights terhubung ke klaster Operational Insights yang dikelola sendiri. Operational Insights adalah basis data analitik real-time (RT-OLAP) untuk aplikasi real-time dan intelijen operasional. Server ini tidak tersedia untuk Capella. Server ini menggunakan SDK couchbase-operational-insights. Server ini berjalan sebagai proses tersendiri, terpisah dari server operasional.
[!IMPORTANT]
CB_OPERATIONAL_INSIGHTS_CONNECTION_STRINGadalah URL HTTP(S), bukan string koneksicouchbase://— misalnyahttp://localhost:8095, atauhttps://<host>:18095melalui TLS. Ini adalah kesalahan konfigurasi yang paling umum.
Mulai Cepat Operational Insights
Dari PyPI dengan uvx:
{
"mcpServers": {
"couchbase-operational-insights": {
"command": "uvx",
"args": ["couchbase-mcp-server", "operational-insights"],
"env": {
"CB_OPERATIONAL_INSIGHTS_CONNECTION_STRING": "http://localhost:8095",
"CB_OPERATIONAL_INSIGHTS_USERNAME": "Administrator",
"CB_OPERATIONAL_INSIGHTS_PASSWORD": "password"
}
}
}
}
Dengan Docker:
{
"mcpServers": {
"couchbase-operational-insights": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"-e", "CB_OPERATIONAL_INSIGHTS_CONNECTION_STRING=http://host.docker.internal:8095",
"-e", "CB_OPERATIONAL_INSIGHTS_USERNAME=Administrator",
"-e", "CB_OPERATIONAL_INSIGHTS_PASSWORD=password",
"couchbase/mcp-server:latest", "operational-insights"
]
}
}
}
Dari kode sumber, gunakan konfigurasi sumber operasional dengan operational-insights sebagai argumen terakhir dan variabel di atas.
Koneksi dan Autentikasi Operational Insights
| Variabel Lingkungan | Argumen CLI | Deskripsi |
|---|---|---|
CB_OPERATIONAL_INSIGHTS_CONNECTION_STRING | --connection-string | URL endpoint (HTTP/HTTPS). Wajib |
CB_OPERATIONAL_INSIGHTS_USERNAME | --username | Nama pengguna |
CB_OPERATIONAL_INSIGHTS_PASSWORD | --password | Kata sandi |
CB_OPERATIONAL_INSIGHTS_CA_CERT_PATH | --ca-cert-path | Sertifikat root (PEM) untuk sertifikat server yang ditandatangani sendiri/tidak tepercaya |
CB_OPERATIONAL_INSIGHTS_CLIENT_CERT_PATH | --client-cert-path | Sertifikat klien untuk mTLS — PEM (dengan kunci) atau bundel PKCS#12 (.p12/.pfx, tanpa kunci). Memerlukan URL https://; menggantikan nama pengguna/kata sandi |
CB_OPERATIONAL_INSIGHTS_CLIENT_KEY_PATH | --client-key-path | Kunci privat (PEM) untuk sertifikat klien. Biarkan tidak disetel untuk PKCS#12 |
CB_OPERATIONAL_INSIGHTS_CLIENT_CERT_PASSWORD | --client-cert-password | Kata sandi untuk kunci terenkripsi atau bundel PKCS#12 |
CB_MCP_OPERATIONAL_INSIGHTS_QUERY_RESULT_MAX_SIZE | --operational-insights-query-result-max-size | Ukuran maksimum hasil kueri dalam byte. Jika tidak disetel, tidak ada batas. Jika disetel, pembacaan berhenti saat mencapai batas dan respons melaporkan truncated: true; baris yang akan melampaui batas tidak dikembalikan. Nilai di atas 4 MiB (4194304) dibatasi hingga 4 MiB, dengan peringatan di stderr saat startup |
CB_MCP_OPERATIONAL_INSIGHTS_ASYNC_QUERY_RESULT_TIMEOUT | --operational-insights-async-query-result-timeout | Batas waktu dalam detik untuk setiap permintaan kueri asinkron: memulai kueri, memeriksa statusnya, mengambil hasil, membuang hasil, dan membatalkan kueri. Untuk pengambilan hasil, batas ini mencakup seluruh proses pengunduhan, sehingga hasil yang membutuhkan waktu lebih lama untuk dibaca akan gagal. Tingkatkan nilainya untuk hasil besar atau koneksi lambat. Bilangan bulat positif, default 30, maksimum 600. Nilai yang lebih besar dibatasi hingga 600 dengan peringatan; nilai tidak valid lainnya dicatat sebagai peringatan dan 30 digunakan |
Semua konfigurasi umum berlaku, dengan perbedaan berikut dari server operasional:
- Port default adalah
8001dan file log default adalahmcp_server_operational_insights.log, sehingga kedua server dapat berjalan berdampingan. - Hanya satu worker yang didukung (
CB_MCP_WORKERS=1), karena handle kueri asinkron disimpan di memori proses. - Server ini tidak memiliki opsi
CB_MCP_EMBEDDING_MODEL_*.
Alat Operational Insights
Semua nama kecuali get_server_configuration_status diawali dengan operational_insights_, sehingga kedua server dapat didaftarkan di satu klien tanpa bentrok. Alat tulis (ditandai ✏️) tidak dimuat saat mode hanya-baca aktif, yang merupakan pengaturan default.
Status Server
| Alat | Deskripsi |
|---|---|
get_server_configuration_status | Alat yang sama seperti pada server operasional |
Penemuan Model Data & Skema
| Alat | Deskripsi |
|---|---|
operational_insights_get_databases_in_cluster | Mencantumkan database |
operational_insights_get_scopes_in_database | Mencantumkan scope dalam database |
operational_insights_get_collections_in_scope | Mencantumkan koleksi (dataset) dalam scope |
operational_insights_get_schema_for_collection | Menyimpulkan skema JSON koleksi dengan mengambil sampel |
Kueri dan Indeks
| Alat | Deskripsi |
|---|---|
operational_insights_list_indexes | Mencantumkan indeks sekunder dari System.Metadata.Index |
operational_insights_explain_query | Menjalankan EXPLAIN pada pernyataan SQL++ tanpa mengeksekusinya |
operational_insights_run_query_sync | Menjalankan SQL++ dan mengembalikan baris, hingga batas ukuran hasil; dapat mengekspor sebagai gantinya. Mode hanya-baca diberlakukan di sisi server |
operational_insights_run_query_async | Memulai kueri yang berjalan lama dan mengembalikan query_handle tanpa menunggu baris; juga lebih disarankan untuk ekspor berukuran besar. Mode hanya-baca diberlakukan di sisi server |
operational_insights_get_async_query_results | Memeriksa kueri asinkron; mengembalikan baris (atau tujuan ekspor) saat siap |
operational_insights_discard_async_query_results | Membebaskan hasil kueri asinkron yang telah selesai |
operational_insights_cancel_async_query | Menghentikan kueri asinkron yang masih berjalan (diizinkan dalam mode hanya-baca) |
operational_insights_create_index ✏️ | Membuat indeks sekunder melalui CREATE INDEX |
Kueri asinkron mengikuti alur mulai → periksa → buang atau batalkan: operational_insights_run_query_async mengembalikan query_handle, operational_insights_get_async_query_results diperiksa hingga siap, lalu operational_insights_discard_async_query_results membebaskan hasil, atau operational_insights_cancel_async_query menghentikan kueri yang masih berjalan.
Mengekspor hasil berukuran besar
Alih-alih mengembalikan baris, operational_insights_run_query_sync dan operational_insights_run_query_async dapat membungkus pernyataan dalam COPY ... TO dan menulis baris ke penyimpanan objek eksternal. Berikan ketiga hal berikut: copy_to_link (tautan yang sudah ada dan dibuat dengan CREATE LINK ... TYPE S3), copy_to_bucket dan copy_to_path, serta secara opsional copy_to_format (json, default, atau parquet). Alat kemudian mengembalikan konfirmasi tanpa baris:
{
"success": true,
"exported": true,
"destination": {"link": "s3Link", "bucket": "my-exports", "path": "exports/run1", "format": "json"},
"message": "Results were written to my-exports/exports/run1 as json. ..."
}
- Tujuan yang tidak lengkap akan ditolak, bukan diam-diam mengembalikan baris.
- Alat sinkron menunggu hingga seluruh proses pengunggahan selesai; gunakan alat asinkron untuk ekspor berukuran besar.
- Ekspor diblokir dalam mode hanya-baca (karena menulis ke penyimpanan eksternal), sehingga memerlukan
CB_MCP_READ_ONLY_MODE=falseatau token dengancouchbase-mcp:write. csvtidak tersedia, karena memerlukan skema keluaran eksplisit yang tidak dapat disimpulkan dariSELECTsembarang.
Konfigurasi Umum
Pengaturan ini bekerja dengan cara yang sama untuk kedua server. Setiap opsi dapat ditetapkan sebagai variabel lingkungan atau sebagai flag CLI setelah subperintah.
Kontrol Keamanan
Ikuti prinsip keamanan berikut:
- Berikan hak akses minimum kepada pengguna database — RBAC adalah batas otoritatif (lihat di bawah).
- Sediakan hanya alat yang dibutuhkan agen, dan nonaktifkan sisanya — setiap alat yang dimuat dapat dipanggil oleh LLM. Gunakan mode hanya-baca dan
CB_MCP_DISABLED_TOOLSuntuk membatasi daftar alat seminimal mungkin. - Wajibkan konfirmasi untuk alat sensitif yang tetap diaktifkan — lihat Mewajibkan konfirmasi.
Kontrol di bawah ini membentuk tiga lapisan, dari yang paling luas hingga yang paling sempit. Gunakan semuanya bersama-sama — tetapi ingat bahwa tidak satu pun menggantikan RBAC.
[!IMPORTANT] Izin RBAC pengguna database merupakan kontrol keamanan yang otoritatif. Misalnya, menonaktifkan
upsert_document_by_iddandelete_document_by_idtidak mencegahrun_sql_plus_plus_querymenjalankanINSERT/UPDATE/DELETE/MERGE— hanya mode hanya-baca atau ketiadaan izin RBAC yang dapat mencegahnya. Berikan pengguna database server hanya izin yang dibutuhkannya.
Mode hanya-baca
CB_MCP_READ_ONLY_MODE (default true) adalah satu-satunya sakelar untuk operasi tulis:
true— alat tulis yang ditandai ✏️ dalam daftar alat setiap server tidak dimuat, dan kueri yang mengubah data atau struktur diblokir.false— alat tulis dimuat dan kueri yang mengubah data diizinkan.
Menonaktifkan alat
CB_MCP_DISABLED_TOOLS menghapus alat sepenuhnya dari penemuan. Opsi ini menerima daftar yang dipisahkan koma atau jalur ke file yang berisi satu nama alat per baris (# memulai komentar):
CB_MCP_DISABLED_TOOLS="upsert_document_by_id,delete_document_by_id"
# or
CB_MCP_DISABLED_TOOLS=/path/to/disabled_tools.txt
# disabled_tools.txt
# Write operations
upsert_document_by_id
delete_document_by_id
# Index advisor
get_index_advisor_recommendations
Di Capella, server operasional juga menonaktifkan beberapa alat admin secara otomatis.
Mewajibkan konfirmasi (elicitation)
CB_MCP_CONFIRMATION_REQUIRED_TOOLS meminta pengguna mengonfirmasi sebelum alat yang tercantum dijalankan, menggunakan MCP elicitation. Opsi ini menerima format daftar yang dipisahkan koma atau file yang sama seperti opsi alat yang dinonaktifkan:
CB_MCP_CONFIRMATION_REQUIRED_TOOLS="delete_document_by_id,replace_document_by_id"
- Jika klien mendukung elicitation, pengguna akan diminta mengonfirmasi sebelum alat dijalankan.
- Jika tidak, alat akan dijalankan tanpa konfirmasi demi kompatibilitas ke belakang.
- Konfirmasi memerlukan sesi MCP, sehingga tidak dapat digabungkan dengan HTTP stateless (
CB_MCP_STATELESS_HTTP=trueatauCB_MCP_WORKERSdi atas 1). Server menolak untuk memulai dengan kombinasi tersebut. Di balik load balancer, konfirmasi memerlukan sesi yang melekat — lihat Load balancer.
Transport
| Transport | Digunakan untuk | Endpoint |
|---|---|---|
stdio (default) | Satu klien lokal yang menjalankan server sebagai subproses | — |
http | Beberapa klien yang berbagi satu server; mendukung OAuth dan pemeriksaan kesehatan, serta worker pada server operasional | http://<host>:<port>/mcp |
Atur transport dengan CB_MCP_TRANSPORT, alamat bind dengan CB_MCP_HOST (default 127.0.0.1) dan port dengan CB_MCP_PORT (port default masing-masing server jika tidak disetel). Tanpa OAuth, endpoint HTTP tidak memerlukan autentikasi.
uvx couchbase-mcp-server operational \
--connection-string='<couchbase_connection_string>' \
--username='<database_username>' \
--password='<database_password>' \
--transport=http
Kemudian arahkan klien ke URL tersebut:
{
"mcpServers": {
"couchbase-http": {
"url": "http://localhost:8000/mcp"
}
}
}
Beberapa worker
Satu proses menggunakan paling banyak sekitar satu inti CPU. --workers N (CB_MCP_WORKERS) menjalankan N proses di balik host dan port yang sama; jumlah inti yang tersedia merupakan titik awal yang baik. Worker hanya didukung oleh server operasional. Jika menggunakan lebih dari satu worker:
- Transport
httpwajib digunakan, dan server berjalan dalam mode HTTP stateless karena permintaan klien dapat diterima oleh worker yang berbeda. Anda juga dapat menyetel--stateless-http=truepada satu worker, misalnya di balik load balancer tanpa sesi yang melekat. - Alat yang memerlukan konfirmasi tidak dapat digunakan.
- Setiap proses menulis file lognya sendiri, dengan nama yang menyertakan host dan ID proses (
mcp_server.<host>.<pid>.info.log) — satu set untuk supervisor dan satu set untuk setiap worker.
Load balancer
Anda dapat menjalankan beberapa instans server di balik load balancer. Setiap instans menyimpan sesi MCP di memorinya sendiri, sehingga pengaturan load balancer menentukan apa yang dapat berfungsi:
| Load balancer | Pengaturan server | Alat yang memerlukan konfirmasi |
|---|---|---|
Sesi melekat, dirutekan berdasarkan header permintaan Mcp-Session-Id | Satu worker, stateful (default) | Didukung |
| Tanpa sesi melekat | --stateless-http=true | Tidak didukung — server menolak untuk memulai jika alat tersebut dikonfigurasi |
- Tanpa sesi melekat, instans stateful menolak setiap permintaan yang sesinya dibuat pada instans lain. Gunakan mode stateless dalam kasus tersebut.
- Lakukan perutean berdasarkan header
Mcp-Session-Id, bukan cookie. Banyak klien MCP tidak menyimpan cookie. - Jika instans dimulai ulang atau mengalami failover, sesi dan permintaan konfirmasi yang tertunda akan hilang. Klien harus memulai sesi baru.
- Kueri asinkron Operational Insights menyimpan
query_handledi memori instans yang memulai kueri, termasuk dalam mode stateless. Memeriksa, membuang, atau membatalkan kueri pada instans lain akan mengembalikanUnknown query_handle. Gunakan alat ini dengan satu instans, atau dengan sesi melekat agar semua panggilan mencapai instans yang memulai kueri. Mode stateless tidak mengirimMcp-Session-Id, sehingga memerlukan kunci afinitas lain, seperti alamat IP klien.
Pemeriksaan kesehatan
Dalam mode HTTP, GET /health mengembalikan {"status": "ok", "server": "<server>"} pada port MCP. Ini adalah pemeriksaan liveness: tidak terhubung ke klaster (sehingga gangguan klaster tidak akan memulai ulang kontainer yang sehat), tidak memerlukan autentikasi meskipun OAuth diaktifkan, dan dilayani oleh setiap worker. Lihat Docker untuk contoh probe.
Otorisasi OAuth 2.1
Dengan --transport=http, setiap server dapat bertindak sebagai server sumber daya OAuth 2.1, memvalidasi JWT bearer terhadap JWKS penyedia identitas Anda. Fitur ini berfungsi dengan penyedia OAuth 2.1/OIDC apa pun yang menerbitkan JWKS, dan tidak menerbitkan token atau mengelola pengguna. Pengaturan OAuth diabaikan pada stdio.
- OAuth hanya aktif jika ketiga hal berikut disetel:
CB_MCP_OAUTH_JWT_JWKS_URI,CB_MCP_OAUTH_JWT_ISSUERdanCB_MCP_OAUTH_JWT_AUDIENCE; jika hanya sebagian yang disetel, startup akan gagal. CB_MCP_OAUTH_MCP_BASE_URLjuga menerbitkan Protected Resource Metadata RFC 9728 agar klien dapat menemukan server otorisasi.- Akses dikendalikan oleh dua scope dalam klaim token
scope/scp:couchbase-mcp:read(alat baca) dancouchbase-mcp:write(alat tulis). Akses penuh memerlukan keduanya. Ubah namanya denganCB_MCP_OAUTH_SCOPE_READ_LABEL/CB_MCP_OAUTH_SCOPE_WRITE_LABELjika IdP Anda tidak dapat menerbitkan label ini. Kedua server menggunakan label yang sama, sehingga satu konfigurasi IdP mencakup keduanya.
uvx couchbase-mcp-server operational \
--connection-string='<couchbase_connection_string>' \
--username='<database_username>' \
--password='<database_password>' \
--transport=http \
--oauth-jwks-uri='https://auth.example.com/.well-known/jwks.json' \
--oauth-issuer='https://auth.example.com/' \
--oauth-audience='couchbase-mcp-server' \
--oauth-mcp-base-url='<public_base_url_of_this_server>'
Lihat dokumentasi OAuth untuk server operasional dan server Operational Insights untuk penyiapan IdP.
Pencatatan log
Secara default, setiap server mencatat log ke stderr pada level info.
CB_MCP_LOG_LEVEL—off,error,warning,info(peristiwa siklus hidup dan pemanggilan alat) ataudebug.CB_MCP_LOG_SINKS—stderr,file, atau keduanya. Denganfile, satu file bergilir untuk setiap level ditulis di sebelahCB_MCP_LOG_FILE(mcp_server.info.log,mcp_server.error.log, …).- Rotasi dan retensi —
CB_MCP_LOG_ROTATION_MAX_SIZE_MB(default 1 MB) danCB_MCP_LOG_RETENTION_BACKUP_COUNT(default 1) berlaku untuk setiap level; ganti per level denganCB_MCP_LOG_<LEVEL>_ROTATION_MAX_SIZE_MB/CB_MCP_LOG_<LEVEL>_RETENTION_BACKUP_COUNT. Ukuran yang tidak valid akan menggunakan nilai default disertai peringatan saat startup.CB_MCP_LOG_MAX_BYTESsudah usang. - Snapshot konfigurasi — dengan sink
file, catatan JSON tentang lingkungan dan konfigurasi server yang disamarkan ditulis kemcp_server_config.log.jsonsetiap kali startup, untuk keperluan dukungan.
# Debug logging to stderr and rotating per-level files
uvx couchbase-mcp-server operational --log-level=debug --log-sinks=stderr,file
Klien MCP Anda biasanya juga menangkap stderr server — lihat Penyiapan Klien untuk mengetahui lokasinya. Detail: dokumentasi pencatatan untuk server operasional dan server Operational Insights.
Audit
Pencatatan audit merekam siapa melakukan apa, dan apakah tindakan itu diizinkan — terpisah dari log operasional, yang mencatat hal-hal yang tidak berjalan semestinya. Server MCP adalah satu-satunya lapisan yang dapat menjawab hal ini untuk agen: setiap permintaan mencapai klaster sebagai satu pengguna database, dan keputusan seperti penolakan cakupan, pemblokiran hanya-baca, atau konfirmasi yang ditolak tidak pernah mencapai klaster.
Audit dinonaktifkan secara default. Aktifkan dengan CB_MCP_AUDIT_LOG_ENABLED=true; audit ditulis ke stderr kecuali Anda menetapkan CB_MCP_AUDIT_LOG_SINKS=file dan CB_MCP_AUDIT_LOG_FILE_PATH.
# 90 days of daily, gzipped audit files
uvx couchbase-mcp-server operational --audit-log-enabled=true \
--audit-log-sinks=file --audit-log-file-path=/var/log/cb-mcp/audit.log \
--audit-log-rotation-interval=1d --audit-log-rotation-max-size-mb=0 \
--audit-log-retention-max-backups=90
Catatan menggunakan JSON Lines dengan kosakata kolom yang sama seperti Couchbase Server dan Sync Gateway:
{"id":61522,"name":"document write","description":"A document write operation was requested through a tool","timestamp":"2026-09-29T09:14:22.418Z","real_userid":{"domain":"oauth","user":"agent-svc-7"},"server":{"version":"1.0.2","host":"mcp-01"},"cid":"9f2c...","outcome":"success","tool_name":"upsert_document_by_id","required_scope":"write","ks":"travel-sample.inventory.airline","cb_userid":"mcp_service"}
Cara kerja audit
- Identitas —
real_useridadalah pemanggil:oauth(subjek token),local(pengguna OS, pada stdio), atauanonymous(HTTP tanpa OAuth, yang menampilkan peringatan saat startup). - Korelasi —
cidmengelompokkan setiap catatan dari satu permintaan, dan dikirim sebagaiclient_context_idSQL++, sehingga dapat digabungkan secara tepat denganclientContextIdmilik Couchbase Server. Tidak ada pengenal sesi, sesuai rancangan. - Peristiwa — katalog bernomor tetap (siklus hidup, inisialisasi, token ditolak, cakupan ditolak, pemblokiran hanya-baca, konfirmasi ditolak/dilewati, serta pasangan baca/tulis untuk setiap kategori alat).
querydansearchmerupakan pengecualian: masing-masing dicatat sebagai satu peristiwa, bukan pasangan baca/tulis, karena pembedaan tersebut tidak dapat dilakukan secara andal untuk permukaan berbasis pernyataan dan pencarian. Operasi vektor termasuk dalam kedua kategori tersebut. Katalog lengkap disertakan sebagaidescriptor.jsondalam paket. Server operasional menggunakan blok0xF000(61440), Operational Insights menggunakan0x10000(65536), dan keduanya berbagi0xE000(57344) untuk peristiwa inti. - Pemfilteran —
CB_MCP_AUDIT_LOG_DISABLED_EVENTSmenyembunyikan peristiwa baca berdasarkan ID numerik (misalnya61490,61492). Peristiwa tulis dan keamanan tidak dapat dinonaktifkan, begitu pula kategori peristiwa tunggalquery(61507, atau 65603 pada Operational Insights) dansearch(61510): satu peristiwa mencakup operasi tulis dan baca pada setiap kategori, sehingga menonaktifkannya akan menghilangkan catatan mutasi. - Rotasi — berdasarkan ukuran (
CB_MCP_AUDIT_LOG_ROTATION_MAX_SIZE_MB, default 10) dan usia (CB_MCP_AUDIT_LOG_ROTATION_INTERVAL, default1d), mana pun yang tercapai lebih dahulu;0menonaktifkan keduanya. File yang dirotasi diberi stempel waktu dan dikompresi dengan gzip; file aktif tetap berupa teks biasa untuktail -f. - File per proses — host dan pid disisipkan ke dalam nama (
audit.log→audit.<host>.<pid>.log), sehingga proses yang berjalan bersamaan tidak pernah berbagi file. - Retensi per file —
CB_MCP_AUDIT_LOG_RETENTION_MAX_BACKUPS(default 10) membatasi cadangan untuk satu file. Setiap proses baru menulis file baru dan tidak menghapus file lama, jadi sesuaikan ukuran volume atau bersihkan fileaudit.*.log*yang lama. - Tetap berjalan saat gagal — jika file tidak dapat ditulis, server tetap melayani permintaan dan menghitung catatan yang terbuang;
get_server_configuration_statusmelaporkanwritten/dropped/write_errors. - Argumen alat — hanya direkam dengan
CB_MCP_AUDIT_LOG_TOOL_ARGS=true, yang menampilkan peringatan saat startup. Rilis ini tidak melakukan penyamaran, sehingga argumen, termasuk isi dokumen lengkap, ditulis apa adanya.
Penyiapan Klien
Setiap klien memerlukan konfigurasi server dari panduan mulai cepat operasional atau Operational Insights di lokasi konfigurasinya sendiri. Contoh di bawah menggunakan server operasional.
Claude Desktop
- Buka file konfigurasi (lihat panduan mulai cepat MCP):
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
- macOS:
- Tambahkan server di bawah
mcpServerslalu mulai ulang Claude Desktop.
Log: macOS ~/Library/Logs/Claude, Windows %APPDATA%\Claude\Logs. Lihat panduan pemecahan masalah MCP.
Cursor
- Buka Cursor Settings > Tools & Integrations > MCP Tools (lihat dokumentasi MCP Cursor), atau gunakan tautan sekali klik Install in Cursor — lalu ganti string koneksi dan kredensial placeholder.
- Tambahkan konfigurasi di bawah
mcpServerslalu simpan. - Segarkan daftar server MCP untuk memastikan
couchbasediaktifkan.
Log: di panel bawah, buka Output lalu pilih Cursor MCP.
Windsurf Editor
- Buka Command Palette > Windsurf MCP Configuration Panel, atau Windsurf Settings > Advanced > Cascade > Model Context Protocol (MCP) Servers (lihat dokumentasi MCP Windsurf).
- Klik Add Server > Add custom server, tempel konfigurasi lalu simpan.
- Segarkan daftar server untuk memastikan
couchbasediaktifkan.
VS Code
VS Code menggunakan servers sebagai kunci tingkat teratas, bukan mcpServers. Letakkan konfigurasi di .vscode/mcp.json untuk ruang kerja, atau jalankan MCP: Open User Configuration untuk semua ruang kerja (lihat dokumentasi MCP VS Code):
{
"servers": {
"couchbase": {
"command": "uvx",
"args": ["couchbase-mcp-server", "operational"],
"env": {
"CB_CONNECTION_STRING": "couchbases://connection-string",
"CB_USERNAME": "username",
"CB_PASSWORD": "password"
}
}
}
}
Menyimpan file akan memulai server; gunakan tindakan Running | Stop | n Tools di atasnya untuk mengelolanya.
Log: jalankan MCP: List Servers, pilih couchbase, lalu Show Output.
JetBrains IDEs
- Instal plugin AI Assistant atau Junie.
- Buka Settings > Tools > AI Assistant (or Junie) > MCP Server, klik +, tambahkan konfigurasi lalu klik Apply.
- Arahkan kursor ke status server untuk melihat alat-alatnya.
Log: Help > Show Log in Finder (Explorer) > mcp > couchbase.
Docker
Image siap pakai dipublikasikan ke Docker Hub sebagai couchbase/mcp-server, dan server tercantum dalam Katalog Docker MCP. Konfigurasikan kontainer dengan variabel lingkungan yang sama seperti di atas. Lihat halaman Docker Hub (DOCKER.md) untuk tag, volume, dan contoh pemeriksaan kesehatan.
Menjalankan melalui HTTP — perhatikan bahwa server harus terikat ke 0.0.0.0 agar dapat dijangkau dari luar kontainer:
docker run --rm \
-e CB_CONNECTION_STRING='<couchbase_connection_string>' \
-e CB_USERNAME='<database_user>' \
-e CB_PASSWORD='<database_password>' \
-e CB_MCP_TRANSPORT=http \
-e CB_MCP_HOST=0.0.0.0 \
-p 8000:8000 \
couchbase/mcp-server:latest operational
- Jika Couchbase berjalan di mesin host Anda, gunakan
couchbase://host.docker.internalsebagai string koneksi (lihat jaringan Docker). Gunakan--network=<your_network>untuk bergabung dengan jaringan kontainer lain. - Tambahkan
operational-insightsalih-alihoperationaluntuk menjalankan server Operational Insights (port8001).
Membangun image dari sumber
docker build -t mcp/couchbase-src .
./build.sh [image-name] membangun dengan argumen yang sama seperti CI — menetapkan argumen build GIT_COMMIT_HASH dan BUILD_DATE, serta memberi tag pada image sebagai latest dan <short-commit> (nama default mcp/couchbase-src). Untuk membangun dengan label secara manual:
docker build --build-arg GIT_COMMIT_HASH=$(git rev-parse HEAD) \
--build-arg BUILD_DATE=$(date -u +'%Y-%m-%dT%H:%M:%SZ') \
-t mcp/couchbase-src .
# Check the labels
docker inspect --format='{{json .Config.Labels}}' mcp/couchbase-src:latest
Pemecahan Masalah
Untuk panduan lengkap, lihat dokumentasi pemecahan masalah untuk server operasional dan server Operational Insights, serta panduan keamanan untuk server operasional dan server Operational Insights. Pemeriksaan singkat:
- Periksa string koneksi, nama pengguna/kata sandi, atau jalur sertifikat.
- Untuk Capella, pastikan klaster mengizinkan koneksi dari mesin yang menjalankan server.
- Pastikan pengguna database dapat mengakses setidaknya satu bucket.
- Jika klien tidak dapat menemukan
uv/uvx, masukkan jalur absolut kecommand. - Saat menjalankan dari sumber, periksa jalur repositori dalam konfigurasi, lalu jalankan
uv syncsetelah mengambil pembaruan. - Panggil
get_server_configuration_statusuntuk melihat konfigurasi yang benar-benar telah diselesaikan oleh server, dan periksa log klien Anda (lihat Penyiapan Klien).
FAQ
Bagaimana cara menghubungkan Claude Desktop ke Couchbase? Tambahkan konfigurasi mulai cepat ke claude_desktop_config.json lalu mulai ulang Claude Desktop — lihat Penyiapan Klien.
Bisakah saya menggunakan ini dengan Couchbase Capella? Ya, dengan server operasional: konfigurasi yang sama berfungsi untuk Capella dan klaster yang dikelola sendiri, meskipun beberapa alat admin hanya tersedia pada klaster yang dikelola sendiri (lihat Alat). Server Operational Insights hanya untuk klaster Operational Insights yang dikelola sendiri.
Apakah aman membiarkan agen AI menulis ke database saya? Secara default, tidak ada alat tulis yang dimuat dan SQL++ yang mengubah data diblokir. Jika Anda mengaktifkan penulisan, Anda tetap dapat menonaktifkan alat tertentu atau mewajibkan konfirmasi — tetapi izin RBAC pengguna Couchbase Anda tetap menjadi batas keamanan yang sesungguhnya. Lihat Kontrol Keamanan.
Apakah saya perlu memahami SQL++? Tidak. Ajukan pertanyaan dalam bahasa sehari-hari dan asisten akan menulis SQL++ untuk run_sql_plus_plus_query. Asisten juga dapat menjelaskan rencana kueri atau meminta rekomendasi dari Index Advisor.
STDIO atau Streamable HTTP? STDIO untuk satu klien lokal. Streamable HTTP untuk berbagi satu server di antara beberapa klien, dengan OAuth. Lihat Transport.
Apakah ini didukung secara resmi oleh Couchbase? Ya, dengan lisensi Couchbase AI Data Plane. Tanpanya, teknisi Couchbase akan membantu dengan upaya terbaik melalui issue GitHub. Lihat Kebijakan Dukungan.
Kontribusi
Kontribusi dipersilakan — perbaikan bug, fitur, dan dokumentasi. Untuk melaporkan bug atau meminta bantuan, buat issue GitHub.
Lihat CONTRIBUTING.md untuk penyiapan pengembangan, linting, pengujian, struktur proyek, dan alur kerja. Untuk memulai:
git clone https://github.com/couchbase/mcp-server-couchbase.git
cd mcp-server-couchbase
uv sync --extra dev
uv run pre-commit install
./scripts/lint.sh
Pengujian integrasi dijalankan terhadap klaster aktif. Ekspor CB_CONNECTION_STRING, CB_USERNAME, CB_PASSWORD, dan secara opsional CB_MCP_TEST_BUCKET; pengujian Operational Insights juga menggunakan CB_OPERATIONAL_INSIGHTS_CONNECTION_STRING / _USERNAME / _PASSWORD dan akan dilewati jika variabel tersebut tidak ditetapkan. Lalu jalankan:
uv run --extra dev pytest tests/integration -v
Data Penggunaan, Risiko LLM, dan Kebijakan Dukungan
Pengumpulan Data Penggunaan
Produk ini secara otomatis mengumpulkan data penggunaan dan kinerja (seperti nama dan versi produk) serta informasi browser (seperti alamat IP) (secara kolektif disebut "Data Penggunaan"). Couchbase menggunakan Data Penggunaan, bersama dengan data lain yang mungkin Anda berikan kepada Couchbase (seperti nama pengguna atau alamat email), untuk mengembangkan dan menyempurnakan produk kami serta mendukung program penjualan dan pemasaran kami. Kami tidak mengakses atau mengumpulkan data apa pun yang Anda simpan di produk Couchbase. Kami menggunakan Data Penggunaan untuk memahami pola penggunaan secara agregat dan menjadikan produk kami lebih bermanfaat bagi Anda. Untuk informasi selengkapnya tentang cara Couchbase mengumpulkan, melindungi, dan memproses informasi, silakan lihat Kebijakan Privasi Couchbase di https://www.couchbase.com/privacy-policy.
Risiko yang Terkait dengan LLM
- Penggunaan model bahasa besar dan teknologi serupa memiliki risiko, termasuk kemungkinan menghasilkan keluaran yang tidak akurat atau berbahaya.
- Couchbase tidak meninjau atau mengevaluasi kualitas maupun keakuratan keluaran tersebut, dan keluaran tersebut mungkin tidak mencerminkan pandangan Couchbase.
- Anda sepenuhnya bertanggung jawab untuk menentukan apakah akan menggunakan model bahasa besar dan teknologi terkait, serta mematuhi ketentuan lisensi, ketentuan penggunaan, dan kebijakan organisasi Anda yang mengatur penggunaan teknologi tersebut.
Kebijakan Dukungan
Couchbase MCP Server adalah sumber terbuka dan dikelola oleh para engineer Couchbase. Cara Anda mendapatkan bantuan bergantung pada cara Anda menggunakannya:
- Penggunaan komunitas — laporkan bug, ajukan pertanyaan, dan minta fitur dengan membuka issue GitHub. Para engineer Couchbase memantau repositori dan merespons sesuai kemampuan, tanpa komitmen waktu respons. Portal dukungan Couchbase tidak dapat membantu penggunaan komunitas.
- Dukungan perusahaan — tersedia dengan melisensikan Couchbase AI Data Plane, yang juga mencakup Couchbase Agent Memory dan Couchbase Agent Catalog. Pelanggan berlisensi mendapatkan bantuan melalui saluran Dukungan Couchbase yang biasa mereka gunakan.
Terima kasih telah menggunakan dan berkontribusi pada proyek ini!