Couchbase

resmi

Berinteraksi 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.

Docs License Python 3.11+ PyPI version Install in Cursor Verified on MseeP Trust Score

Dokumentasi lengkap: docs.couchbase.com/mcp-server

Couchbase Server MCP server

Daftar Isi

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 users yang memenuhi status = '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 products dengan bidang-bidang berikut: …" (memerlukan CB_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 operasionalServer Operational Insights
Gunakan denganKlaster Couchbase (Capella atau dikelola sendiri)Klaster Operational Insights yang dikelola sendiri (tidak tersedia di Capella)
Subperintahoperational (default)operational-insights
String koneksicouchbase:// / couchbases://URL HTTP(S), misalnya http://localhost:8095
Variabel kredensialCB_CONNECTION_STRING, CB_USERNAME, …CB_OPERATIONAL_INSIGHTS_CONNECTION_STRING, CB_OPERATIONAL_INSIGHTS_USERNAME, …
Alat52 — kesehatan klaster, skema, KV, SQL++, indeks, pencarian teks lengkap dan vektor, performa kueri13 — skema, SQL++ (sinkron dan asinkron), indeks, ekspor
Port HTTP default80008001
File log defaultmcp_server.logmcp_server_operational_insights.log

Saat ini, subperintah bersifat opsional untuk server operasional — couchbase-mcp-server tanpa 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 dengan uvx 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 LingkunganArgumen CLIDeskripsi
CB_CONNECTION_STRING--connection-stringString koneksi ke klaster. Wajib
CB_USERNAME / CB_PASSWORD--username / --passwordAutentikasi dasar
CB_CLIENT_CERT_PATH / CB_CLIENT_KEY_PATH--client-cert-path / --client-key-pathAutentikasi mTLS
CB_CA_CERT_PATH--ca-cert-pathSertifikat 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

AlatDeskripsi
get_server_configuration_statusStatus dan konfigurasi server tanpa terhubung ke klaster: mode hanya baca, alat yang dinonaktifkan/memerlukan konfirmasi, OAuth, pencatatan log, dan penghitung audit
test_cluster_connectionPeriksa kredensial klaster dengan menghubungkan ke klaster
get_cluster_health_and_servicesKesehatan klaster dan layanan yang berjalan, dengan pemfilteran opsional melalui service_types
get_client_connectivity_reportDiagnostik 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

AlatDeskripsi
get_buckets_in_clusterCantumkan semua bucket di klaster
get_scopes_in_bucketCantumkan semua scope dalam bucket
get_collections_in_scopeCantumkan semua collection dalam scope (memerlukan layanan Query)
get_scopes_and_collections_in_bucketCantumkan semua scope dan collection dalam bucket
get_schema_for_collectionSimpulkan 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)

AlatDeskripsi
get_document_by_idDapatkan dokumen berdasarkan ID
lookup_subdocumentBaca 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

AlatDeskripsi
run_sql_plus_plus_queryJalankan 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_queryBuat dan evaluasi rencana EXPLAIN: metadata, rencana yang diekstrak, dan temuan
get_index_advisor_recommendationsRekomendasi Index Advisor untuk kueri SQL++
list_indexesCantumkan 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.

ToolDeskripsi
list_search_indexesMencantumkan indeks Search — tingkat cluster, per bucket, atau per scope
get_search_index_definitionDefinisi lengkap satu indeks Search (pemetaan, analyzer, parameter plan)
run_searchMenjalankan 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.

ToolDeskripsi
run_vector_queryPencarian 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_searchPencarian 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

ToolDeskripsi
get_longest_running_queriesKueri dengan waktu layanan rata-rata terlama
get_most_frequent_queriesKueri yang paling sering dijalankan
get_queries_with_largest_response_sizesKueri dengan ukuran respons terbesar
get_queries_with_large_result_countKueri dengan jumlah hasil terbanyak
get_queries_using_primary_indexKueri yang menggunakan indeks primer
get_queries_not_using_covering_indexKueri yang tidak menggunakan indeks covering
get_queries_not_selectiveKueri 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.

ToolDeskripsi
get_cluster_query_vitalsKesehatan mesin kueri: laju permintaan, permintaan aktif/antrean, memori, GC, waktu aktif. Memerlukan ro_admin
get_active_queriesKueri 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.

ToolEndpoint yang diperlukan
get_cluster_metricsREST Management (/pools/default/stats/range)
get_cluster_tasksREST Management (/pools/default/tasks)
get_bucket_configREST Management (/pools/default/buckets[/<name>])
get_cluster_health_snapshotREST Management, ditambah endpoint per node
get_cluster_system_eventsREST Management (/events)
get_index_statsREST Index Service (masing-masing /api/v1/stats milik pengindeks)
get_cluster_query_vitalsREST Query Service (/admin/vitals)
get_active_queriesREST Query Service (/admin/active_requests)
delete_active_queryREST Query Service (DELETE /admin/active_requests/{id})
discover_tool_input_valuesTidak 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_PROVIDERWajibOpsionalCatatan
capellaCB_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
openaiCB_MCP_EMBEDDING_MODEL_API_KEY, CB_MCP_EMBEDDING_MODELCB_MCP_EMBEDDING_MODEL_ENDPOINTTetapkan endpoint untuk menggunakan server lokal yang kompatibel dengan OpenAI (Ollama, vLLM, LM Studio)
cohereCB_MCP_EMBEDDING_MODEL_API_KEY, CB_MCP_EMBEDDING_MODELCB_MCP_EMBEDDING_MODEL_ENDPOINT
voyageCB_MCP_EMBEDDING_MODEL_API_KEY, CB_MCP_EMBEDDING_MODELCB_MCP_EMBEDDING_MODEL_ENDPOINT
bedrockCB_MCP_EMBEDDING_MODELCB_MCP_EMBEDDING_MODEL_AWS_ACCESS_KEY_ID, CB_MCP_EMBEDDING_MODEL_AWS_SECRET_ACCESS_KEY, CB_MCP_EMBEDDING_MODEL_AWS_REGIONModel 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 LingkunganArgumen CLIDeskripsiDefault
CB_CONNECTION_STRING--connection-stringString koneksi ke klaster CouchbaseWajib
CB_USERNAME--usernameNama pengguna dengan akses ke bucket yang diperlukan untuk autentikasi dasarWajib (atau Sertifikat dan Kunci Klien diperlukan untuk mTLS)
CB_PASSWORD--passwordKata sandi untuk autentikasi dasarWajib (atau Sertifikat dan Kunci Klien diperlukan untuk mTLS)
CB_CLIENT_CERT_PATH--client-cert-pathJalur ke file sertifikat klien untuk autentikasi mTLSWajib jika menggunakan mTLS (atau Nama Pengguna dan Kata Sandi diperlukan)
CB_CLIENT_KEY_PATH--client-key-pathJalur ke file kunci klien untuk autentikasi mTLSWajib jika menggunakan mTLS (atau Nama Pengguna dan Kata Sandi diperlukan)
CB_CA_CERT_PATH--ca-cert-pathJalur 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-modeCegah semua modifikasi data (KV, Query, pengelolaan scope/collection, pengelolaan indeks, dan pengelolaan indeks FTS). Jika diaktifkan, alat tulis tidak dimuat.true
CB_MCP_TRANSPORT--transportMode transportasi: stdio, httpstdio
CB_MCP_HOST--hostHost untuk mode transportasi HTTP127.0.0.1
CB_MCP_PORT--portPort untuk mode transportasi HTTP8000
CB_MCP_WORKERS--workersJumlah proses pekerja server untuk transportasi http. Nilai di atas 1 menjalankan mode HTTP stateless (lihat Beberapa Pekerja)1
CB_MCP_STATELESS_HTTP--stateless-httpTangani 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-toolsAlat yang dinonaktifkan (lihat Menonaktifkan Alat)Tidak ada
CB_MCP_CONFIRMATION_REQUIRED_TOOLS--confirmation-required-toolsAlat yang memerlukan konfirmasi eksplisit pengguna sebelum dijalankan melalui elisitasi MCP (lihat Memerlukan konfirmasi)Tidak ada
CB_MCP_LOG_LEVEL--log-levelTingkat pencatatan log untuk server MCP: off, debug, info, warning, error (lihat Pencatatan Log)info
CB_MCP_LOG_SINKS--log-sinksTujuan log yang dipisahkan koma: stderr, file, atau keduanya (lihat Pencatatan Log)stderr
CB_MCP_LOG_FILE--log-fileJalur 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-mbUkuran 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 startup1 (1 MB)
CB_MCP_LOG_MAX_BYTES--log-max-bytesUsang — 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 ditetapkanTidak ditetapkan
CB_MCP_LOG_ERROR_ROTATION_MAX_SIZE_MB--log-error-rotation-max-size-mbUkuran rotasi dalam MB untuk file log ERROR; menimpa CB_MCP_LOG_ROTATION_MAX_SIZE_MB untuk ERRORMewarisi CB_MCP_LOG_ROTATION_MAX_SIZE_MB
CB_MCP_LOG_WARNING_ROTATION_MAX_SIZE_MB--log-warning-rotation-max-size-mbUkuran rotasi dalam MB untuk file log WARNING; menimpa CB_MCP_LOG_ROTATION_MAX_SIZE_MB untuk WARNINGMewarisi CB_MCP_LOG_ROTATION_MAX_SIZE_MB
CB_MCP_LOG_INFO_ROTATION_MAX_SIZE_MB--log-info-rotation-max-size-mbUkuran rotasi dalam MB untuk file log INFO; menimpa CB_MCP_LOG_ROTATION_MAX_SIZE_MB untuk INFOMewarisi CB_MCP_LOG_ROTATION_MAX_SIZE_MB
CB_MCP_LOG_DEBUG_ROTATION_MAX_SIZE_MB--log-debug-rotation-max-size-mbUkuran rotasi dalam MB untuk file log DEBUG; menimpa CB_MCP_LOG_ROTATION_MAX_SIZE_MB untuk DEBUGMewarisi CB_MCP_LOG_ROTATION_MAX_SIZE_MB
CB_MCP_LOG_RETENTION_BACKUP_COUNT--log-retention-backup-countJumlah 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-countJumlah cadangan hasil rotasi yang disimpan untuk file log ERROR; menimpa jumlah global untuk ERRORMewarisi CB_MCP_LOG_RETENTION_BACKUP_COUNT
CB_MCP_LOG_WARNING_RETENTION_BACKUP_COUNT--log-warning-retention-backup-countJumlah cadangan hasil rotasi yang disimpan untuk file log WARNING; menimpa jumlah global untuk WARNINGMewarisi CB_MCP_LOG_RETENTION_BACKUP_COUNT
CB_MCP_LOG_INFO_RETENTION_BACKUP_COUNT--log-info-retention-backup-countJumlah cadangan hasil rotasi yang disimpan untuk file log INFO; menimpa jumlah global untuk INFOMewarisi CB_MCP_LOG_RETENTION_BACKUP_COUNT
CB_MCP_LOG_DEBUG_RETENTION_BACKUP_COUNT--log-debug-retention-backup-countJumlah cadangan hasil rotasi yang disimpan untuk file log DEBUG; menimpa jumlah global untuk DEBUGMewarisi CB_MCP_LOG_RETENTION_BACKUP_COUNT
CB_MCP_OAUTH_JWT_JWKS_URI--oauth-jwks-uriEndpoint 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-issuerKlaim JWT iss yang diharapkan. Wajib untuk mengaktifkan OAuthTidak ada
CB_MCP_OAUTH_JWT_AUDIENCE--oauth-audienceKlaim JWT aud yang diharapkan. Wajib untuk mengaktifkan OAuthTidak ada
CB_MCP_OAUTH_JWT_ALGORITHM--oauth-algorithmAlgoritma penandatanganan JWT: salah satu dari RS256/384/512, ES256/384/512, PS256/384/512RS256
CB_MCP_OAUTH_MCP_BASE_URL--oauth-mcp-base-urlURL dasar publik server ini. Jika ditetapkan, akan menerbitkan Protected Resource Metadata RFC 9728 agar klien yang mendukung PRM dapat menemukan IdPTidak ada
CB_MCP_OAUTH_SCOPE_READ_LABEL--oauth-scope-read-labelGanti 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 kanoniscouchbase-mcp:read
CB_MCP_OAUTH_SCOPE_WRITE_LABEL--oauth-scope-write-labelGanti label scope OAuth yang diperlakukan sebagai akses 'tulis'; semantiknya sama dengan label bacacouchbase-mcp:write
CB_MCP_AUDIT_LOG_ENABLED--audit-log-enabledAktifkan 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-sinksTujuan audit yang dipisahkan koma: console, file, atau keduanya. console menulis ke stderr — tidak pernah ke stdout, yang membawa protokol JSON-RPC pada stdioconsole
CB_MCP_AUDIT_LOG_FILE_PATH--audit-log-file-pathJalur 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-mbUkuran maksimum dalam MB yang dapat dicapai file audit aktif sebelum dirotasi. 0 menonaktifkan rotasi berbasis ukuran10 (10 MB)
CB_MCP_AUDIT_LOG_ROTATION_INTERVAL--audit-log-rotation-intervalUsia 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 interval1d
CB_MCP_AUDIT_LOG_RETENTION_MAX_BACKUPS--audit-log-retention-max-backupsCadangan 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 Audit10
CB_MCP_AUDIT_LOG_TOOL_ARGS--audit-log-tool-argsCatat nilai argumen alat dalam log audit. Dinonaktifkan secara default — rilis ini tidak memiliki penyamaran, sehingga mengaktifkannya akan menulis argumen apa adanya, termasuk isi dokumen lengkapfalse
CB_MCP_AUDIT_LOG_DISABLED_EVENTS--audit-log-disabled-eventsPeristiwa 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 disembunyikanTidak ada
CB_MCP_EMBEDDING_MODEL_PROVIDER--embedding-model-providerPenyedia 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 EmbeddingTidak ada
CB_MCP_EMBEDDING_MODEL--embedding-modelNama/ID model untuk penyedia embedding yang dikonfigurasiTidak ada
CB_MCP_EMBEDDING_MODEL_API_KEY--embedding-model-api-keyKunci 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-endpointPenggantian 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-idID kunci akses AWS, hanya untuk penyedia bedrock. Abaikan untuk menggunakan rantai kredensial AWS defaultTidak ada
CB_MCP_EMBEDDING_MODEL_AWS_SECRET_ACCESS_KEY--embedding-model-aws-secret-access-keyKunci akses rahasia AWS, hanya untuk penyedia bedrockTidak ada
CB_MCP_EMBEDDING_MODEL_AWS_REGION--embedding-model-aws-regionWilayah AWS, hanya untuk penyedia bedrock. Jika tidak ditetapkan, akan menggunakan resolusi wilayah milik AWS SDKTidak 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_STRING adalah URL HTTP(S), bukan string koneksi couchbase:// — misalnya http://localhost:8095, atau https://<host>:18095 melalui 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 LingkunganArgumen CLIDeskripsi
CB_OPERATIONAL_INSIGHTS_CONNECTION_STRING--connection-stringURL endpoint (HTTP/HTTPS). Wajib
CB_OPERATIONAL_INSIGHTS_USERNAME--usernameNama pengguna
CB_OPERATIONAL_INSIGHTS_PASSWORD--passwordKata sandi
CB_OPERATIONAL_INSIGHTS_CA_CERT_PATH--ca-cert-pathSertifikat root (PEM) untuk sertifikat server yang ditandatangani sendiri/tidak tepercaya
CB_OPERATIONAL_INSIGHTS_CLIENT_CERT_PATH--client-cert-pathSertifikat 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-pathKunci privat (PEM) untuk sertifikat klien. Biarkan tidak disetel untuk PKCS#12
CB_OPERATIONAL_INSIGHTS_CLIENT_CERT_PASSWORD--client-cert-passwordKata sandi untuk kunci terenkripsi atau bundel PKCS#12
CB_MCP_OPERATIONAL_INSIGHTS_QUERY_RESULT_MAX_SIZE--operational-insights-query-result-max-sizeUkuran 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-timeoutBatas 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 8001 dan file log default adalah mcp_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

AlatDeskripsi
get_server_configuration_statusAlat yang sama seperti pada server operasional

Penemuan Model Data & Skema

AlatDeskripsi
operational_insights_get_databases_in_clusterMencantumkan database
operational_insights_get_scopes_in_databaseMencantumkan scope dalam database
operational_insights_get_collections_in_scopeMencantumkan koleksi (dataset) dalam scope
operational_insights_get_schema_for_collectionMenyimpulkan skema JSON koleksi dengan mengambil sampel

Kueri dan Indeks

AlatDeskripsi
operational_insights_list_indexesMencantumkan indeks sekunder dari System.Metadata.Index
operational_insights_explain_queryMenjalankan EXPLAIN pada pernyataan SQL++ tanpa mengeksekusinya
operational_insights_run_query_syncMenjalankan SQL++ dan mengembalikan baris, hingga batas ukuran hasil; dapat mengekspor sebagai gantinya. Mode hanya-baca diberlakukan di sisi server
operational_insights_run_query_asyncMemulai 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_resultsMemeriksa kueri asinkron; mengembalikan baris (atau tujuan ekspor) saat siap
operational_insights_discard_async_query_resultsMembebaskan hasil kueri asinkron yang telah selesai
operational_insights_cancel_async_queryMenghentikan 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=false atau token dengan couchbase-mcp:write.
  • csv tidak tersedia, karena memerlukan skema keluaran eksplisit yang tidak dapat disimpulkan dari SELECT sembarang.

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_TOOLS untuk 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_id dan delete_document_by_id tidak mencegah run_sql_plus_plus_query menjalankan INSERT/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=true atau CB_MCP_WORKERS di atas 1). Server menolak untuk memulai dengan kombinasi tersebut. Di balik load balancer, konfirmasi memerlukan sesi yang melekat — lihat Load balancer.

Transport

TransportDigunakan untukEndpoint
stdio (default)Satu klien lokal yang menjalankan server sebagai subproses—
httpBeberapa klien yang berbagi satu server; mendukung OAuth dan pemeriksaan kesehatan, serta worker pada server operasionalhttp://<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 http wajib digunakan, dan server berjalan dalam mode HTTP stateless karena permintaan klien dapat diterima oleh worker yang berbeda. Anda juga dapat menyetel --stateless-http=true pada 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 balancerPengaturan serverAlat yang memerlukan konfirmasi
Sesi melekat, dirutekan berdasarkan header permintaan Mcp-Session-IdSatu worker, stateful (default)Didukung
Tanpa sesi melekat--stateless-http=trueTidak 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_handle di memori instans yang memulai kueri, termasuk dalam mode stateless. Memeriksa, membuang, atau membatalkan kueri pada instans lain akan mengembalikan Unknown query_handle. Gunakan alat ini dengan satu instans, atau dengan sesi melekat agar semua panggilan mencapai instans yang memulai kueri. Mode stateless tidak mengirim Mcp-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_ISSUER dan CB_MCP_OAUTH_JWT_AUDIENCE; jika hanya sebagian yang disetel, startup akan gagal.
  • CB_MCP_OAUTH_MCP_BASE_URL juga 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) dan couchbase-mcp:write (alat tulis). Akses penuh memerlukan keduanya. Ubah namanya dengan CB_MCP_OAUTH_SCOPE_READ_LABEL / CB_MCP_OAUTH_SCOPE_WRITE_LABEL jika 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) atau debug.
  • CB_MCP_LOG_SINKS — stderr, file, atau keduanya. Dengan file, satu file bergilir untuk setiap level ditulis di sebelah CB_MCP_LOG_FILE (mcp_server.info.log, mcp_server.error.log, …).
  • Rotasi dan retensi — CB_MCP_LOG_ROTATION_MAX_SIZE_MB (default 1 MB) dan CB_MCP_LOG_RETENTION_BACKUP_COUNT (default 1) berlaku untuk setiap level; ganti per level dengan CB_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_BYTES sudah usang.
  • Snapshot konfigurasi — dengan sink file, catatan JSON tentang lingkungan dan konfigurasi server yang disamarkan ditulis ke mcp_server_config.log.json setiap 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_userid adalah pemanggil: oauth (subjek token), local (pengguna OS, pada stdio), atau anonymous (HTTP tanpa OAuth, yang menampilkan peringatan saat startup).
  • Korelasi — cid mengelompokkan setiap catatan dari satu permintaan, dan dikirim sebagai client_context_id SQL++, sehingga dapat digabungkan secara tepat dengan clientContextId milik 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). query dan search merupakan 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 sebagai descriptor.json dalam paket. Server operasional menggunakan blok 0xF000 (61440), Operational Insights menggunakan 0x10000 (65536), dan keduanya berbagi 0xE000 (57344) untuk peristiwa inti.
  • Pemfilteran — CB_MCP_AUDIT_LOG_DISABLED_EVENTS menyembunyikan peristiwa baca berdasarkan ID numerik (misalnya 61490,61492). Peristiwa tulis dan keamanan tidak dapat dinonaktifkan, begitu pula kategori peristiwa tunggal query (61507, atau 65603 pada Operational Insights) dan search (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, default 1d), mana pun yang tercapai lebih dahulu; 0 menonaktifkan keduanya. File yang dirotasi diberi stempel waktu dan dikompresi dengan gzip; file aktif tetap berupa teks biasa untuk tail -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 file audit.*.log* yang lama.
  • Tetap berjalan saat gagal — jika file tidak dapat ditulis, server tetap melayani permintaan dan menghitung catatan yang terbuang; get_server_configuration_status melaporkan written / 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
  1. Buka file konfigurasi (lihat panduan mulai cepat MCP):
    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows: %APPDATA%\Claude\claude_desktop_config.json
  2. Tambahkan server di bawah mcpServers lalu mulai ulang Claude Desktop.

Log: macOS ~/Library/Logs/Claude, Windows %APPDATA%\Claude\Logs. Lihat panduan pemecahan masalah MCP.

Cursor
  1. 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.
  2. Tambahkan konfigurasi di bawah mcpServers lalu simpan.
  3. Segarkan daftar server MCP untuk memastikan couchbase diaktifkan.

Log: di panel bawah, buka Output lalu pilih Cursor MCP.

Windsurf Editor
  1. Buka Command Palette > Windsurf MCP Configuration Panel, atau Windsurf Settings > Advanced > Cascade > Model Context Protocol (MCP) Servers (lihat dokumentasi MCP Windsurf).
  2. Klik Add Server > Add custom server, tempel konfigurasi lalu simpan.
  3. Segarkan daftar server untuk memastikan couchbase diaktifkan.
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
  1. Instal plugin AI Assistant atau Junie.
  2. Buka Settings > Tools > AI Assistant (or Junie) > MCP Server, klik +, tambahkan konfigurasi lalu klik Apply.
  3. 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.internal sebagai string koneksi (lihat jaringan Docker). Gunakan --network=<your_network> untuk bergabung dengan jaringan kontainer lain.
  • Tambahkan operational-insights alih-alih operational untuk menjalankan server Operational Insights (port 8001).
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 ke command.
  • Saat menjalankan dari sumber, periksa jalur repositori dalam konfigurasi, lalu jalankan uv sync setelah mengambil pembaruan.
  • Panggil get_server_configuration_status untuk 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!