Couchbase
ทางการโต้ตอบกับข้อมูลที่เก็บอยู่ในคลัสเตอร์ Couchbase โดยใช้ภาษาธรรมชาติ
คุณทำอะไรได้บ้างด้วย Couchbase MCP?
- สำรวจข้อมูลคลัสเตอร์ — แสดงรายการบักเก็ต สโคป และคอลเลกชัน จากนั้นอนุมานสคีมาของคอลเลกชัน เช่น
orders - เรียกใช้คิวรี SQL++ — เรียกใช้คิวรี SQL++ แบบอ่านอย่างเดียวกับบักเก็ตและสโคป พร้อมอธิบายแผนคิวรี
- ตรวจสอบเอกสาร — ดึงเอกสารด้วย ID หรืออ่านเส้นทางของเอกสารย่อยที่ระบุ โดยไม่ต้องโหลดเอกสารทั้งฉบับ
- ตรวจสอบสถานะคลัสเตอร์ — รายงานสถานะคลัสเตอร์ บริการที่กำลังทำงาน และการวินิจฉัยการเชื่อมต่อ
- วิเคราะห์ประสิทธิภาพคิวรี — ค้นหาคิวรีที่ใช้เวลานานที่สุด เรียกใช้บ่อยที่สุด หรือไม่ได้ใช้ดัชนีแบบครอบคลุม
- ค้นหาและคิวรีเวกเตอร์ — เรียกใช้การค้นหาข้อความเต็มและคิวรีความคล้ายคลึงของเวกเตอร์กับดัชนีที่กำหนดค่าไว้
เอกสาร
Couchbase MCP Server
Couchbase MCP Server เป็น Server แบบ self-hosted MCP ที่ช่วยให้ AI agent เชื่อมต่อและโต้ตอบกับข้อมูลใน Couchbase Server (ไม่ว่าจะโฮสต์บน Capella หรือจัดการเอง) หรือ Operational Insights Enterprise ได้ โดยมีเครื่องมือหลายหมวดหมู่ เช่น Cluster Health, Data Schema, Query และอื่น ๆ พร้อมการควบคุมความปลอดภัยผ่านโหมดอ่านอย่างเดียวและการปิดใช้เครื่องมือแบบละเอียด รองรับทั้งการขนส่งแบบ STDIO และ Streamable HTTP พร้อมความสามารถ OAuth
Couchbase MCP Server เผยแพร่เป็นแพ็กเกจ Python Package Index (PyPI) และผ่าน Docker สามารถรับการสนับสนุนระดับองค์กรสำหรับ Couchbase MCP Server ได้โดยการอนุญาตใช้ Couchbase AI Data Plane ซึ่งยังให้สิทธิ์ใช้งานและรับการสนับสนุนระดับองค์กรสำหรับ Couchbase Agent Memory และ Couchbase Agent Catalog ด้วย
เอกสารฉบับเต็ม: docs.couchbase.com/mcp-server
สารบัญ
- เหตุผลที่ควรใช้ Couchbase MCP Server
- การเลือก Server
- Operational Server
- Operational Insights Server
- การกำหนดค่าทั่วไป
- การตั้งค่า Client
- Docker
- การแก้ไขปัญหา
- คำถามที่พบบ่อย
- การมีส่วนร่วม
- ข้อมูลการใช้งาน ความเสี่ยงของ LLM และนโยบายการสนับสนุน
เหตุผลที่ควรใช้ Couchbase MCP Server
- ปลอดภัยโดยค่าเริ่มต้น — จะไม่โหลดเครื่องมือเขียน และจะบล็อกคิวรีที่แก้ไขข้อมูล เว้นแต่คุณจะตั้งค่า
CB_MCP_READ_ONLY_MODE=false; นอกจากนี้ยังปิดใช้เครื่องมือแต่ละรายการหรือกำหนดให้ต้องได้รับการยืนยันจากผู้ใช้ก่อนใช้งานได้ - Couchbase Server และ Operational Insights — operational server เชื่อมต่อกับ Couchbase Capella หรือคลัสเตอร์ Couchbase Server ที่จัดการเองโดยใช้การกำหนดค่าเดียวกัน ส่วน Operational Insights server เชื่อมต่อกับคลัสเตอร์ Operational Insights ที่จัดการเอง
- คำนึงถึง RBAC — การควบคุมเครื่องมือเป็นแนวทางให้ LLM แต่การควบคุมการเข้าถึงตามบทบาทของผู้ใช้ Couchbase ยังคงเป็นขอบเขตความปลอดภัยที่มีอำนาจสูงสุด
- การขนส่งสำหรับระบบใช้งานจริง — ใช้ STDIO สำหรับ client บนเดสก์ท็อปภายในเครื่อง หรือ Streamable HTTP พร้อม OAuth 2.1 ที่เลือกใช้ได้ (รองรับ IdP ที่เผยแพร่ JWKS ทุกราย เช่น Auth0, Okta, Keycloak, Entra, Cognito, …) การตรวจสอบสถานะ และการบันทึกการตรวจสอบสำหรับการติดตั้งใช้งานร่วมกัน นอกจากนี้ operational server ยังสามารถเรียกใช้ หลาย worker เพื่อใช้ประโยชน์จาก CPU หลายคอร์ได้
- ใช้ได้กับ MCP client ทุกราย — ทดสอบแล้วกับ Claude Desktop, Cursor, Windsurf, VS Code และ JetBrains AI Assistant/Junie
เมื่อเชื่อมต่อแล้ว คุณสามารถถามคำถาม เช่น:
- "ฉันมี bucket, scope และ collection อะไรบ้าง และ collection
ordersมี schema อย่างไร?" - "ค้นหาเอกสาร 10 รายการล่าสุดใน
usersที่มีstatus = 'active'" - "คิวรี 5 รายการที่ช้าที่สุดในชั่วโมงที่ผ่านมาเป็นรายการใดบ้าง และมีรายการใดขาด covering index หรือไม่?"
- "คลัสเตอร์นี้มีสถานะปกติหรือไม่ และมี service ใดกำลังทำงานอยู่บ้าง?"
- "แทรกเอกสารใหม่ลงใน
productsโดยมีฟิลด์เหล่านี้: …" (ต้องใช้CB_MCP_READ_ONLY_MODE=false)
การเลือก Server
แพ็กเกจนี้มาพร้อม MCP server สองตัว แต่ละตัวเริ่มทำงานด้วย subcommand ของตัวเอง เชื่อมต่อกับคลัสเตอร์คนละประเภท และมีเครื่องมือของตัวเอง เลือกตัวที่ตรงกับคลัสเตอร์ของคุณ แล้วทำตามหัวข้อการตั้งค่าและเครื่องมือของตัวนั้น จากนั้นดู การกำหนดค่าทั่วไป สำหรับการตั้งค่าที่ใช้ร่วมกัน หากต้องการใช้ทั้งสองตัว ให้ลงทะเบียนแต่ละตัวเป็น server แยกกันใน MCP client
| Operational server | Operational Insights server | |
|---|---|---|
| ใช้กับ | คลัสเตอร์ Couchbase (Capella หรือจัดการเอง) | คลัสเตอร์ Operational Insights ที่จัดการเอง (ไม่มีให้บริการบน Capella) |
| Subcommand | operational (ค่าเริ่มต้น) | operational-insights |
| สตริงการเชื่อมต่อ | couchbase:// / couchbases:// | URL แบบ HTTP(S) เช่น http://localhost:8095 |
| ตัวแปรข้อมูลรับรอง | CB_CONNECTION_STRING, CB_USERNAME, … | CB_OPERATIONAL_INSIGHTS_CONNECTION_STRING, CB_OPERATIONAL_INSIGHTS_USERNAME, … |
| เครื่องมือ | 52 — สถานะคลัสเตอร์, schema, KV, SQL++, index, การค้นหาแบบ full-text และ vector, ประสิทธิภาพคิวรี | 13 — schema, SQL++ (แบบ sync และ async), index, การส่งออก |
| พอร์ต HTTP เริ่มต้น | 8000 | 8001 |
| ไฟล์ล็อกเริ่มต้น | mcp_server.log | mcp_server_operational_insights.log |
ปัจจุบัน subcommand เป็นตัวเลือกสำหรับ operational server — เรียกใช้
couchbase-mcp-serverเปล่า ๆ เพื่อเริ่มทำงานได้ — แต่การระบุชื่อไว้จะช่วยให้การกำหนดค่าชัดเจนไม่กำกวม ตัวเลือกต้องอยู่หลัง subcommand:couchbase-mcp-server operational --transport=httpตรวจสอบเวอร์ชันที่ติดตั้งด้วยuvx couchbase-mcp-server --version
Operational Server
Server operational เชื่อมต่อกับคลัสเตอร์ Couchbase บน Capella หรือ Couchbase Server ที่จัดการเอง โดยใช้ Python SDK couchbase
เริ่มต้นใช้งาน Operational
คุณต้องมีคลัสเตอร์ Couchbase ที่กำลังทำงานอยู่ — ระดับใช้งานฟรีของ Capella เป็นวิธีที่รวดเร็วที่สุดในการเริ่มใช้งาน (คุณสามารถ นำเข้าชุดข้อมูลตัวอย่าง) — และ MCP client เพิ่มการกำหนดค่า เพียงหนึ่งรายการ ต่อไปนี้ลงใน client ของคุณ (ดูตำแหน่งไฟล์กำหนดค่าของแต่ละ client ได้ที่ การตั้งค่า Client) หาก client มี server อื่นอยู่แล้ว ให้เพิ่ม couchbase ลงในออบเจ็กต์ mcpServers ที่มีอยู่
จาก PyPI ด้วย uvx (ต้องใช้ uv และ 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"
}
}
}
}
ด้วย Docker (ต้องใช้ 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"
]
}
}
}
จากซอร์ส
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/ คือพาธไปยังโคลนของคุณ — อย่าลบเครื่องหมายทับท้าย หลังจากดึงการอัปเดตแล้ว ให้เรียกใช้ uv sync เพื่ออัปเดต dependencies
การเชื่อมต่อและการยืนยันตัวตนของ Operational
ใช้ อย่างใดอย่างหนึ่ง ระหว่างชื่อผู้ใช้และรหัสผ่าน หรือ ใบรับรอง client (mTLS) หากกำหนดทั้งสองอย่าง ระบบจะใช้ใบรับรอง
| ตัวแปรสภาพแวดล้อม | อาร์กิวเมนต์ CLI | คำอธิบาย |
|---|---|---|
CB_CONNECTION_STRING | --connection-string | สตริงการเชื่อมต่อกับคลัสเตอร์ จำเป็น |
CB_USERNAME / CB_PASSWORD | --username / --password | การยืนยันตัวตนแบบพื้นฐาน |
CB_CLIENT_CERT_PATH / CB_CLIENT_KEY_PATH | --client-cert-path / --client-key-path | การยืนยันตัวตนแบบ mTLS |
CB_CA_CERT_PATH | --ca-cert-path | ใบรับรอง root สำหรับใบรับรอง server ที่ลงนามเอง/ไม่น่าเชื่อถือ (ไม่จำเป็นสำหรับ Capella) |
ตัวอย่าง 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"
}
}
}
}
เครื่องมือ Operational
เครื่องมือเขียน (ทำเครื่องหมายด้วย ✏️) จะไม่ถูกโหลด ขณะที่เปิดใช้ โหมดอ่านอย่างเดียว ซึ่งเป็นค่าเริ่มต้น เครื่องมือที่ทำเครื่องหมายด้วย 🖥️ ใช้ได้เฉพาะกับระบบที่จัดการเองเท่านั้น — เครื่องมือเหล่านี้ใช้ REST endpoint สำหรับผู้ดูแลระบบที่ Capella ไม่เปิดให้ใช้ หรือ (discover_tool_input_values) ให้บริการเฉพาะข้อมูลอ้างอิงสำหรับเครื่องมือที่ใช้ endpoint ดังกล่าว — จึงต้องใช้ Couchbase Server 7.6 ขึ้นไปที่จัดการเอง และ จะไม่ลงทะเบียนเมื่อเชื่อมต่อกับ Capella
การตั้งค่าและสถานะคลัสเตอร์
| เครื่องมือ | คำอธิบาย |
|---|---|
get_server_configuration_status | สถานะและการกำหนดค่า Server โดยไม่ต้องเชื่อมต่อกับคลัสเตอร์: โหมดอ่านอย่างเดียว เครื่องมือที่ปิดใช้/ต้องยืนยันก่อนใช้ OAuth การบันทึกล็อก และตัวนับการตรวจสอบ |
test_cluster_connection | ตรวจสอบข้อมูลรับรองของคลัสเตอร์โดยเชื่อมต่อกับคลัสเตอร์ |
get_cluster_health_and_services | สถานะคลัสเตอร์และ service ที่กำลังทำงาน โดยเลือกกรองผ่าน service_types ได้ |
get_client_connectivity_report | ข้อมูลวินิจฉัยการเชื่อมต่อที่ SDK แคชไว้ โดยไม่มีการตรวจสอบเครือข่ายแบบแอ็กทีฟ |
get_cluster_metrics 🖥️ | สถิติคลัสเตอร์ในช่วงเวลาย้อนหลัง (stats-range endpoint) |
get_cluster_tasks 🖥️ | งานที่กำลังทำงานอยู่ในขณะนี้ — rebalance, compaction, XDCR, การสร้าง index ต้องใช้ ro_admin |
get_cluster_health_snapshot 🖥️ | สถานะสุขภาพรายโหนด: โทโพโลยี service, การเป็นสมาชิก, orchestrator และสรุปสถานะสุขภาพ ต้องใช้ ro_admin |
get_bucket_config 🖥️ | การกำหนดค่าและสถานะปัจจุบันของ bucket หนึ่งรายการ (หรือทุกรายการ) — โควตา การขับข้อมูลออก replica ความทนทาน พื้นที่จัดเก็บ และ compaction ต้องใช้ ro_admin |
get_cluster_system_events 🖥️ | บันทึกเหตุการณ์ของระบบ (การเปลี่ยนแปลงการกำหนดค่า failover, rebalance, การรีสตาร์ต) โดยกำหนดช่วงเวลาด้วย since_time ต้องมีสิทธิ์ Full Admin หรือ Cluster Admin |
discover_tool_input_values 🖥️ | ค้นหาค่าข้อมูลนำเข้าที่ตรงกันทุกประการซึ่งเครื่องมืออื่นต้องใช้ (เช่น ชื่อ metric ทั้งหมดสำหรับ get_cluster_metrics) ใช้งานแบบออฟไลน์ได้ |
การค้นพบโมเดลข้อมูลและ schema
| เครื่องมือ | คำอธิบาย |
|---|---|
get_buckets_in_cluster | แสดงรายการ bucket ทั้งหมดในคลัสเตอร์ |
get_scopes_in_bucket | แสดงรายการ scope ทั้งหมดใน bucket |
get_collections_in_scope | แสดงรายการ collection ทั้งหมดใน scope (ต้องใช้ Query service) |
get_scopes_and_collections_in_bucket | แสดงรายการ scope และ collection ทั้งหมดใน bucket |
get_schema_for_collection | อนุมานโครงสร้างของ collection |
create_scope ✏️ | สร้าง scope ใน bucket (Server 7.6 ขึ้นไปและ Capella) |
create_collection ✏️ | สร้าง collection ใน scope ที่มีอยู่ (Server 7.6 ขึ้นไปและ Capella) |
delete_scope ✏️ | ลบ scope และ collection ทั้งหมดใน scope นั้น — ลบถาวร |
delete_collection ✏️ | ลบ collection และเอกสารทั้งหมดใน collection — ลบถาวร |
การดำเนินการกับเอกสาร (KV)
| เครื่องมือ | คำอธิบาย |
|---|---|
get_document_by_id | ดึงเอกสารด้วย ID |
lookup_subdocument | อ่านพาธที่ระบุ ตรวจสอบการมีอยู่ หรือนับจำนวน โดยไม่ต้องดึงเอกสารทั้งฉบับ |
upsert_document_by_id ✏️ | Upsert เอกสารด้วย ID |
insert_document_by_id ✏️ | แทรกเอกสารใหม่ (ล้มเหลวหากมีเอกสารนั้นอยู่แล้ว) |
replace_document_by_id ✏️ | แทนที่เอกสารที่มีอยู่ (ล้มเหลวหากไม่มีเอกสารนั้น) |
delete_document_by_id ✏️ | ลบเอกสารด้วย ID |
mutate_subdocument ✏️ | แก้ไขพาธในเอกสารที่มีอยู่ (upsert, insert, replace, remove, การดำเนินการกับ array, ตัวนับ) |
คิวรีและการทำดัชนี
| เครื่องมือ | คำอธิบาย |
|---|---|
run_sql_plus_plus_query | เรียกใช้คิวรี SQL++ ที่กำหนดขอบเขตตาม bucket และ scope — ใช้ชื่อ collection ได้โดยตรง (SELECT * FROM users) คำสั่งที่แก้ไขข้อมูลจะถูกบล็อกในโหมดอ่านอย่างเดียว |
explain_sql_plus_plus_query | สร้างและประเมินแผน EXPLAIN: metadata, แผนที่แยกวิเคราะห์แล้ว และข้อค้นพบ |
get_index_advisor_recommendations | คำแนะนำจาก Index Advisor สำหรับคิวรี SQL++ |
list_indexes | แสดงรายการ index พร้อมคำจำกัดความ โดยกรองตาม bucket/scope/collection/name ได้ และระบุ vector index (is_vector, vector_type) |
get_index_stats 🖥️ | ขนาดของแต่ละ index การแตกกระจาย ปริมาณการสแกน และความล่าช้า แยกตามโหนด — ใช้ค้นหาจุดที่มีแรงกดดันและ index ที่ไม่ได้ใช้งาน |
create_query_index ✏️ | สร้าง scalar, Hyperscale vector หรือ Composite vector GSI index (index_type) โดยค่าเริ่มต้นจะเลื่อนการสร้างไว้ — เรียกใช้ build_index ต่อจากนั้น |
create_index ✏️ | เลิกใช้แล้ว — ใช้ create_query_index แทน นำออกในเวอร์ชัน 2.0 |
build_index ✏️ | สร้าง index ที่เลื่อนการสร้างไว้ทั้งหมดใน collection |
drop_index ✏️ | ลบ GSI index (scalar หรือ vector) |
การค้นหาแบบ Full-text (FTS)
ต้องใช้ Couchbase Server 7.6 ขึ้นไปและ Search service รองรับทั้ง index ระดับ scope และระดับคลัสเตอร์ (แบบเดิม): ส่ง bucket_name และ scope_name พร้อมกันสำหรับระดับ scope หรือไม่ต้องระบุทั้งสองรายการ
| เครื่องมือ | คำอธิบาย |
|---|---|
list_search_indexes | แสดงรายการดัชนี Search — ระดับคลัสเตอร์ แยกตาม bucket หรือแยกตาม scope |
get_search_index_definition | คำจำกัดความทั้งหมดของดัชนี Search หนึ่งรายการ (mappings, analyzers, plan params) |
run_search | เรียกใช้คิวรี FTS ที่ไม่ใช่เวกเตอร์จากเนื้อหา JSON ดิบใดก็ได้; explain=true ส่งคืนแผนการดำเนินการ |
upsert_search_index ✏️ | สร้างหรืออัปเดตดัชนี Search รวมถึง mappings ของฟิลด์เวกเตอร์ การอัปเดตจะทริกเกอร์การสร้างใหม่ทั้งหมด — ส่ง uuid ปัจจุบันเพื่อหลีกเลี่ยงการเขียนทับการเปลี่ยนแปลงที่เกิดขึ้นพร้อมกัน |
drop_search_index ✏️ | ลบดัชนี Search — ถาวร |
การค้นหาเวกเตอร์
เครื่องมือทั้งสองจะฝังข้อความคิวรีธรรมดาด้วยโมเดลที่กำหนดค่าไว้ใน Embedding Providers ใช้ได้บน Couchbase Server ที่จัดการเองและ Capella
| เครื่องมือ | คำอธิบาย |
|---|---|
run_vector_query | ค้นหาความคล้ายคลึงกับดัชนีเวกเตอร์ GSI (Server 8.0+) ผ่าน APPROX_VECTOR_DISTANCE() ระบบจะเลือกดัชนีโดยอัตโนมัติ รองรับตัวกรองล่วงหน้า SQL++ where และการปรับแต่ง Hyperscale (num_probes, rerank, top_n_scan) ส่งคืนเอกสารฉบับเต็ม |
run_vector_search | การค้นหาเวกเตอร์ของ Search service (Server 7.6+) กับดัชนีที่ระบุชื่อ scalar_query ทำให้เป็นแบบไฮบริด; prefilter จำกัดผู้สมัครให้แคบลงก่อน ส่งคืนฟิลด์ที่จัดเก็บในดัชนีสำหรับแต่ละผลลัพธ์ |
การวิเคราะห์ประสิทธิภาพคิวรี
| เครื่องมือ | คำอธิบาย |
|---|---|
get_longest_running_queries | คิวรีที่ใช้เวลานานที่สุด โดยพิจารณาจากเวลาให้บริการเฉลี่ย |
get_most_frequent_queries | คิวรีที่เรียกใช้บ่อยที่สุด |
get_queries_with_largest_response_sizes | คิวรีที่มีขนาดการตอบกลับใหญ่ที่สุด |
get_queries_with_large_result_count | คิวรีที่มีจำนวนผลลัพธ์มากที่สุด |
get_queries_using_primary_index | คิวรีที่ใช้ดัชนีหลัก |
get_queries_not_using_covering_index | คิวรีที่ไม่ได้ใช้ดัชนีแบบ covering |
get_queries_not_selective | คิวรีที่การสแกน — ดัชนีรอง ดัชนีหลัก หรือการสแกนตามลำดับ — ส่งคืนเอกสารมากกว่าผลลัพธ์สุดท้ายอย่างมาก |
สถานะบริการ Query 🖥️
เครื่องมือเหล่านี้เรียกใช้ REST API สำหรับผู้ดูแลระบบของบริการ Query เองบนทุกโหนด Query
| เครื่องมือ | คำอธิบาย |
|---|---|
get_cluster_query_vitals | สถานะของ Query engine: อัตราคำขอ คำขอที่กำลังทำงาน/อยู่ในคิว หน่วยความจำ GC และเวลาเปิดใช้งาน ต้องมี ro_admin |
get_active_queries | คิวรีที่กำลังทำงานอยู่ในขณะนี้บนทุกโหนด Query ต้องมี ro_admin |
delete_active_query ✏️ | ยกเลิกคิวรีที่กำลังทำงานโดยใช้ request ID ต้องมี Full Admin หรือ Cluster Admin |
เครื่องมือที่ปิดใช้งานโดยอัตโนมัติบน Capella
เครื่องมือ 🖥️ เข้าถึง Couchbase ผ่านปลายทาง REST สำหรับผู้ดูแลระบบ ซึ่ง Capella ไม่เปิดให้ใช้งาน (ยกเว้น discover_tool_input_values ซึ่งถูกระงับไว้เพราะให้บริการเฉพาะเครื่องมือที่ต้องใช้ปลายทางเหล่านั้น) เมื่อ host ทุกตัวใน CB_CONNECTION_STRING ลงท้ายด้วย .cloud.couchbase.com เซิร์ฟเวอร์จะไม่ลงทะเบียนเครื่องมือเหล่านี้ และรายงานเครื่องมือเหล่านี้พร้อมกับ เครื่องมือที่ปิดใช้งาน ของคุณใน get_server_configuration_status และบันทึกเริ่มต้นระบบ เครื่องมือที่ใช้ SDK เช่น get_cluster_health_and_services และ get_client_connectivity_report ยังคงใช้งานได้
| เครื่องมือ | ปลายทางที่ต้องใช้ |
|---|---|
get_cluster_metrics | Management REST (/pools/default/stats/range) |
get_cluster_tasks | Management REST (/pools/default/tasks) |
get_bucket_config | Management REST (/pools/default/buckets[/<name>]) |
get_cluster_health_snapshot | Management REST รวมถึงปลายทางระดับโหนด |
get_cluster_system_events | Management REST (/events) |
get_index_stats | Index Service REST (/api/v1/stats ของ indexer แต่ละตัว) |
get_cluster_query_vitals | Query service REST (/admin/vitals) |
get_active_queries | Query service REST (/admin/active_requests) |
delete_active_query | Query service REST (DELETE /admin/active_requests/{id}) |
discover_tool_input_values | ไม่มี (ทำงานแบบออฟไลน์ได้) แต่ให้บริการเฉพาะ get_cluster_metrics ซึ่ง Capella ไม่มี |
ผู้ให้บริการ Embedding
run_vector_query และ run_vector_search จะฝังข้อความคิวรีด้วยผู้ให้บริการที่กำหนดไว้ใน CB_MCP_EMBEDDING_MODEL_PROVIDER ตัวเลือกนี้ไม่บังคับ: หากไม่ได้ตั้งค่า เซิร์ฟเวอร์จะเริ่มทำงานตามปกติและเครื่องมือทั้งสองยังคงลงทะเบียนไว้ แต่เมื่อเรียกใช้จะส่งคืนข้อผิดพลาดที่อธิบายว่าต้องตั้งค่าอะไร
CB_MCP_EMBEDDING_MODEL_PROVIDER | จำเป็น | ไม่บังคับ | หมายเหตุ |
|---|---|---|---|
capella | CB_MCP_EMBEDDING_MODEL_API_KEY, CB_MCP_EMBEDDING_MODEL, CB_MCP_EMBEDDING_MODEL_ENDPOINT | — | Capella Model Service CB_MCP_EMBEDDING_MODEL_ENDPOINT คือ URL เฉพาะของ deployment ของคุณเอง (เช่น https://<id>.ai.couchbase.com) จาก Capella's AI Data Plane > Models |
openai | CB_MCP_EMBEDDING_MODEL_API_KEY, CB_MCP_EMBEDDING_MODEL | CB_MCP_EMBEDDING_MODEL_ENDPOINT | ตั้งค่า endpoint เพื่อใช้เซิร์ฟเวอร์ภายในเครื่องที่เข้ากันได้กับ 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 | โมเดล embedding ของ Amazon Titan (เช่น amazon.titan-embed-text-v2:0) — ผู้ให้บริการส่งคำขอในรูปแบบ inputText ของ Titan ดังนั้นโมเดล embedding อื่น ๆ ของ Bedrock เช่น Cohere Embed จึงยังไม่รองรับ ละเว้นข้อมูลรับรองเพื่อใช้ AWS chain เริ่มต้น ต้องมีส่วนเพิ่มเติม: 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-..."
}
ตัวเลือกทั้งหมด
ตัวแปรสภาพแวดล้อมและแฟล็ก CLI ทุกตัวสำหรับเซิร์ฟเวอร์ operational server
เซิร์ฟเวอร์ Operational Insights ยอมรับตัวเลือกเดียวกัน ยกเว้นมี การตั้งค่าการเชื่อมต่อ ของตัวเอง และไม่มีตัวเลือก CB_MCP_EMBEDDING_MODEL_*
| ตัวแปรสภาพแวดล้อม | อาร์กิวเมนต์ CLI | คำอธิบาย | ค่าเริ่มต้น |
|---|---|---|---|
CB_CONNECTION_STRING | --connection-string | สตริงการเชื่อมต่อไปยังคลัสเตอร์ Couchbase | จำเป็น |
CB_USERNAME | --username | ชื่อผู้ใช้ที่มีสิทธิ์เข้าถึงบักเก็ตที่จำเป็นสำหรับการยืนยันตัวตนพื้นฐาน | จำเป็น (หรือจำเป็นต้องใช้ใบรับรองและคีย์ไคลเอ็นต์สำหรับ mTLS) |
CB_PASSWORD | --password | รหัสผ่านสำหรับการยืนยันตัวตนพื้นฐาน | จำเป็น (หรือจำเป็นต้องใช้ใบรับรองและคีย์ไคลเอ็นต์สำหรับ mTLS) |
CB_CLIENT_CERT_PATH | --client-cert-path | พาธไปยังไฟล์ใบรับรองไคลเอ็นต์สำหรับการยืนยันตัวตนด้วย mTLS | จำเป็นหากใช้ mTLS (หรือจำเป็นต้องใช้ชื่อผู้ใช้และรหัสผ่าน) |
CB_CLIENT_KEY_PATH | --client-key-path | พาธไปยังไฟล์คีย์ไคลเอ็นต์สำหรับการยืนยันตัวตนด้วย mTLS | จำเป็นหากใช้ mTLS (หรือจำเป็นต้องใช้ชื่อผู้ใช้และรหัสผ่าน) |
CB_CA_CERT_PATH | --ca-cert-path | พาธไปยังใบรับรองรากของเซิร์ฟเวอร์สำหรับ TLS หากเซิร์ฟเวอร์กำหนดค่าให้ใช้ใบรับรองที่ลงนามด้วยตนเอง/ไม่น่าเชื่อถือ ไม่จำเป็นต้องใช้ค่านี้หากเชื่อมต่อกับ Capella | |
CB_MCP_READ_ONLY_MODE | --read-only-mode | ป้องกันการแก้ไขข้อมูลทั้งหมด (KV, Query, การจัดการ scope/collection, การจัดการดัชนี และการจัดการดัชนี FTS) เมื่อเปิดใช้งาน เครื่องมือเขียนจะไม่ถูกโหลด | true |
CB_MCP_TRANSPORT | --transport | โหมดการขนส่ง: stdio, http | stdio |
CB_MCP_HOST | --host | โฮสต์สำหรับโหมดการขนส่ง HTTP | 127.0.0.1 |
CB_MCP_PORT | --port | พอร์ตสำหรับโหมดการขนส่ง HTTP | 8000 |
CB_MCP_WORKERS | --workers | จำนวนโปรเซสเวิร์กเกอร์ของเซิร์ฟเวอร์สำหรับการขนส่งแบบ http ค่าที่มากกว่า 1 จะทำงานในโหมด HTTP แบบไร้สถานะ (ดู เวิร์กเกอร์หลายตัว) | 1 |
CB_MCP_STATELESS_HTTP | --stateless-http | จัดการคำขอ HTTP แต่ละรายการโดยไม่เก็บสถานะต่อเซสชัน ใช้ได้เฉพาะกับ http; ใช้ร่วมกับเครื่องมือที่ต้องมีการยืนยันไม่ได้ (ดู เวิร์กเกอร์หลายตัว) | true เมื่อ workers > 1 มิฉะนั้น false |
CB_MCP_DISABLED_TOOLS | --disabled-tools | เครื่องมือที่ต้องการปิดใช้งาน (ดู การปิดใช้งานเครื่องมือ) | ไม่มี |
CB_MCP_CONFIRMATION_REQUIRED_TOOLS | --confirmation-required-tools | เครื่องมือที่ต้องได้รับการยืนยันจากผู้ใช้อย่างชัดเจนก่อนดำเนินการผ่าน MCP elicitation (ดู การกำหนดให้ยืนยัน) | ไม่มี |
CB_MCP_LOG_LEVEL | --log-level | ระดับการบันทึกล็อกสำหรับเซิร์ฟเวอร์ MCP: off, debug, info, warning, error (ดู การบันทึกล็อก) | info |
CB_MCP_LOG_SINKS | --log-sinks | ปลายทางล็อกที่คั่นด้วยจุลภาค: stderr, file หรือทั้งสองอย่าง (ดู การบันทึกล็อก) | stderr |
CB_MCP_LOG_FILE | --log-file | พาธพื้นฐานสำหรับไฟล์ล็อกแยกตามระดับ (ใช้เฉพาะเมื่อเปิดใช้งาน sink file) | mcp_server.log |
CB_MCP_LOG_ROTATION_MAX_SIZE_MB | --log-rotation-max-size-mb | ขนาดสูงสุดส่วนกลาง เป็น MB ต่อไฟล์ล็อกก่อนหมุนเวียน โดยใช้กับทุกระดับ เว้นแต่จะกำหนดค่าแยกไว้ ค่า 0 — หรือค่าที่ใช้ไม่ได้ เช่น ค่าติดลบ nan หรือ inf — ถือว่าไม่ถูกต้อง และจะกลับไปใช้ค่าเริ่มต้นพร้อมคำเตือนเมื่อเริ่มต้นระบบ | 1 (1 MB) |
CB_MCP_LOG_MAX_BYTES | --log-max-bytes | เลิกใช้แล้ว — ให้ใช้ CB_MCP_LOG_ROTATION_MAX_SIZE_MB (MB) แทน ขนาดการหมุนเวียนส่วนกลาง เป็นไบต์ ซึ่งยังรองรับเพื่อความเข้ากันได้แบบย้อนหลัง โดยจะถูกละเว้นเมื่อกำหนด CB_MCP_LOG_ROTATION_MAX_SIZE_MB ด้วย | ไม่ได้กำหนด |
CB_MCP_LOG_ERROR_ROTATION_MAX_SIZE_MB | --log-error-rotation-max-size-mb | ขนาดการหมุนเวียน เป็น MB สำหรับไฟล์ล็อก ERROR; ใช้แทนค่า CB_MCP_LOG_ROTATION_MAX_SIZE_MB สำหรับ ERROR | สืบทอดจาก CB_MCP_LOG_ROTATION_MAX_SIZE_MB |
CB_MCP_LOG_WARNING_ROTATION_MAX_SIZE_MB | --log-warning-rotation-max-size-mb | ขนาดการหมุนเวียน เป็น MB สำหรับไฟล์ล็อก WARNING; ใช้แทนค่า CB_MCP_LOG_ROTATION_MAX_SIZE_MB สำหรับ WARNING | สืบทอดจาก CB_MCP_LOG_ROTATION_MAX_SIZE_MB |
CB_MCP_LOG_INFO_ROTATION_MAX_SIZE_MB | --log-info-rotation-max-size-mb | ขนาดการหมุนเวียน เป็น MB สำหรับไฟล์ล็อก INFO; ใช้แทนค่า CB_MCP_LOG_ROTATION_MAX_SIZE_MB สำหรับ INFO | สืบทอดจาก CB_MCP_LOG_ROTATION_MAX_SIZE_MB |
CB_MCP_LOG_DEBUG_ROTATION_MAX_SIZE_MB | --log-debug-rotation-max-size-mb | ขนาดการหมุนเวียน เป็น MB สำหรับไฟล์ล็อก DEBUG; ใช้แทนค่า CB_MCP_LOG_ROTATION_MAX_SIZE_MB สำหรับ DEBUG | สืบทอดจาก CB_MCP_LOG_ROTATION_MAX_SIZE_MB |
CB_MCP_LOG_RETENTION_BACKUP_COUNT | --log-retention-backup-count | จำนวนไฟล์สำรองที่หมุนเวียนแล้วซึ่งเก็บไว้ต่อไฟล์ล็อกแต่ละระดับ (ไม่รวมไฟล์ที่กำลังใช้งาน) โดยใช้กับทุกระดับ เว้นแต่จะกำหนดค่าแยกไว้ ค่า 0 จะเก็บไว้เฉพาะไฟล์ที่กำลังใช้งาน (ดู การบันทึกล็อก) | 1 |
CB_MCP_LOG_ERROR_RETENTION_BACKUP_COUNT | --log-error-retention-backup-count | จำนวนไฟล์สำรองที่หมุนเวียนแล้วซึ่งเก็บไว้สำหรับไฟล์ล็อก ERROR; ใช้แทนจำนวนส่วนกลางสำหรับ ERROR | สืบทอดจาก CB_MCP_LOG_RETENTION_BACKUP_COUNT |
CB_MCP_LOG_WARNING_RETENTION_BACKUP_COUNT | --log-warning-retention-backup-count | จำนวนไฟล์สำรองที่หมุนเวียนแล้วซึ่งเก็บไว้สำหรับไฟล์ล็อก WARNING; ใช้แทนจำนวนส่วนกลางสำหรับ WARNING | สืบทอดจาก CB_MCP_LOG_RETENTION_BACKUP_COUNT |
CB_MCP_LOG_INFO_RETENTION_BACKUP_COUNT | --log-info-retention-backup-count | จำนวนไฟล์สำรองที่หมุนเวียนแล้วซึ่งเก็บไว้สำหรับไฟล์ล็อก INFO; ใช้แทนจำนวนส่วนกลางสำหรับ INFO | สืบทอดจาก CB_MCP_LOG_RETENTION_BACKUP_COUNT |
CB_MCP_LOG_DEBUG_RETENTION_BACKUP_COUNT | --log-debug-retention-backup-count | จำนวนไฟล์สำรองที่หมุนเวียนแล้วซึ่งเก็บไว้สำหรับไฟล์ล็อก DEBUG; ใช้แทนจำนวนส่วนกลางสำหรับ DEBUG | สืบทอดจาก CB_MCP_LOG_RETENTION_BACKUP_COUNT |
CB_MCP_OAUTH_JWT_JWKS_URI | --oauth-jwks-uri | ปลายทาง JWKS ของผู้ให้บริการข้อมูลระบุตัวตนที่ใช้ตรวจสอบ bearer JWT เมื่อกำหนดค่านี้พร้อม issuer และ audience จะเปิดใช้งาน OAuth (ดู การให้สิทธิ์ OAuth 2.1) | ไม่มี |
CB_MCP_OAUTH_JWT_ISSUER | --oauth-issuer | claim JWT iss ที่คาดหวัง จำเป็นสำหรับเปิดใช้งาน OAuth | ไม่มี |
CB_MCP_OAUTH_JWT_AUDIENCE | --oauth-audience | claim JWT aud ที่คาดหวัง จำเป็นสำหรับเปิดใช้งาน OAuth | ไม่มี |
CB_MCP_OAUTH_JWT_ALGORITHM | --oauth-algorithm | อัลกอริทึมการลงนาม JWT: เลือกหนึ่งรายการจาก RS256/384/512, ES256/384/512, PS256/384/512 | RS256 |
CB_MCP_OAUTH_MCP_BASE_URL | --oauth-mcp-base-url | URL พื้นฐานสาธารณะของเซิร์ฟเวอร์นี้ เมื่อกำหนดค่านี้ จะเผยแพร่ Protected Resource Metadata ตาม RFC 9728 เพื่อให้ไคลเอ็นต์ที่รองรับ PRM ค้นพบ IdP ได้ | ไม่มี |
CB_MCP_OAUTH_SCOPE_READ_LABEL | --oauth-scope-read-label | แทนที่ป้ายกำกับ scope ของ OAuth ที่ถือเป็นสิทธิ์ 'read' (ประกาศใน PRM และจับคู่กับ claim scope/scp ของโทเค็น) ใช้เมื่อ IdP ของคุณไม่สามารถส่งรูปแบบมาตรฐานได้ | couchbase-mcp:read |
CB_MCP_OAUTH_SCOPE_WRITE_LABEL | --oauth-scope-write-label | แทนที่ป้ายกำกับ scope ของ OAuth ที่ถือเป็นสิทธิ์ 'write'; มีความหมายเช่นเดียวกับป้ายกำกับ read | couchbase-mcp:write |
CB_MCP_AUDIT_LOG_ENABLED | --audit-log-enabled | เปิดใช้งานการบันทึกการตรวจสอบ — เป็น sink แยกจากล็อกการปฏิบัติงาน CB_MCP_LOG_* โดยมีสคีมาที่คงที่และนโยบายการเก็บรักษาของตนเอง (ดู การตรวจสอบ) | false |
CB_MCP_AUDIT_LOG_SINKS | --audit-log-sinks | ปลายทางการตรวจสอบที่คั่นด้วยจุลภาค: console, file หรือทั้งสองอย่าง console เขียนไปยัง stderr — ไม่ใช่ stdout ซึ่งใช้ส่งโปรโตคอล JSON-RPC เมื่อใช้ stdio | console |
CB_MCP_AUDIT_LOG_FILE_PATH | --audit-log-file-path | พาธไปยังไฟล์ล็อกการตรวจสอบ จำเป็นเมื่อ file อยู่ใน sinks โดยจะแทรกชื่อโฮสต์และรหัสโปรเซสไว้ก่อนนามสกุล (audit.log → audit.<host>.<pid>.log) | ไม่มี |
CB_MCP_AUDIT_LOG_ROTATION_MAX_SIZE_MB | --audit-log-rotation-max-size-mb | ขนาดสูงสุด เป็น MB ที่ไฟล์การตรวจสอบที่กำลังใช้งานจะมีได้ก่อนหมุนเวียน ค่า 0 จะปิดการหมุนเวียนตามขนาด | 10 (10 MB) |
CB_MCP_AUDIT_LOG_ROTATION_INTERVAL | --audit-log-rotation-interval | อายุสูงสุดของไฟล์การตรวจสอบที่กำลังใช้งานก่อนหมุนเวียน ในรูปแบบ <value><unit> โดยหน่วยคือ d (24 ชั่วโมง) หรือ w (7 วัน) — เช่น 1d, 30d, 8w ค่า 0 จะปิดการหมุนเวียนตามช่วงเวลา | 1d |
CB_MCP_AUDIT_LOG_RETENTION_MAX_BACKUPS | --audit-log-retention-max-backups | จำนวนไฟล์สำรองที่หมุนเวียนแล้วซึ่งเก็บไว้ ต่อไฟล์การตรวจสอบ โดยไม่รวมไฟล์ที่กำลังใช้งาน ไฟล์สำรองจะถูกบีบอัดด้วย gzip ค่า 0 จะไม่เก็บไฟล์สำรองใด ๆ ซึ่งจำกัดจำนวนไฟล์ ไม่ใช่ขนาดไดเรกทอรี — ดู การตรวจสอบ | 10 |
CB_MCP_AUDIT_LOG_TOOL_ARGS | --audit-log-tool-args | บันทึกค่าอาร์กิวเมนต์ของเครื่องมือในล็อกการตรวจสอบ ปิดไว้โดยค่าเริ่มต้น — รุ่นนี้ไม่มีการปกปิดข้อมูล ดังนั้นการเปิดใช้งานจะเขียนอาร์กิวเมนต์ตามจริง รวมถึงเนื้อหาเอกสารทั้งหมด | false |
CB_MCP_AUDIT_LOG_DISABLED_EVENTS | --audit-log-disabled-events | เหตุการณ์การตรวจสอบที่ต้องการระงับ: รหัสเหตุการณ์ตัวเลขที่คั่นด้วยจุลภาค (เช่น 61490,61492) หรือไฟล์ที่มีหนึ่งรหัสต่อบรรทัด ระงับได้เฉพาะเหตุการณ์ที่กรองได้เท่านั้น | ไม่มี |
CB_MCP_EMBEDDING_MODEL_PROVIDER | --embedding-model-provider | ผู้ให้บริการ embedding สำหรับ run_vector_query / run_vector_search: เลือกหนึ่งรายการจาก capella, openai, cohere, voyage, bedrock หากไม่ได้กำหนดค่า ขั้นตอน embedding ของเครื่องมือทั้งสองจะถูกปิดใช้งานจนกว่าจะกำหนดค่า — ดู การกำหนดค่าผู้ให้บริการ Embedding | ไม่มี |
CB_MCP_EMBEDDING_MODEL | --embedding-model | ชื่อ/ID ของโมเดลสำหรับผู้ให้บริการ embedding ที่กำหนดค่าไว้ | ไม่มี |
CB_MCP_EMBEDDING_MODEL_API_KEY | --embedding-model-api-key | คีย์ API สำหรับผู้ให้บริการที่กำหนดค่าไว้ ไม่ใช้โดย bedrock (ใช้ AWS credential chain / CB_MCP_EMBEDDING_MODEL_AWS_* แทน) | ไม่มี |
CB_MCP_EMBEDDING_MODEL_ENDPOINT | --embedding-model-endpoint | การแทนที่ URL พื้นฐาน (เซิร์ฟเวอร์ภายในที่เข้ากันได้กับ OpenAI หรือ URL ของการติดตั้ง Capella Model Service เอง — จำเป็น เมื่อใช้ CB_MCP_EMBEDDING_MODEL_PROVIDER=capella) | ไม่มี |
CB_MCP_EMBEDDING_MODEL_AWS_ACCESS_KEY_ID | --embedding-model-aws-access-key-id | AWS access key ID ใช้กับผู้ให้บริการ bedrock เท่านั้น ไม่ต้องระบุหากต้องการใช้ AWS credential chain เริ่มต้น | ไม่มี |
CB_MCP_EMBEDDING_MODEL_AWS_SECRET_ACCESS_KEY | --embedding-model-aws-secret-access-key | AWS secret access key ใช้กับผู้ให้บริการ bedrock เท่านั้น | ไม่มี |
CB_MCP_EMBEDDING_MODEL_AWS_REGION | --embedding-model-aws-region | AWS region ใช้กับผู้ให้บริการ bedrock เท่านั้น หากไม่ได้กำหนดค่า จะใช้การค้นหา region ของ AWS SDK เอง | ไม่มี |
เซิร์ฟเวอร์ Operational Insights
เซิร์ฟเวอร์ operational-insights เชื่อมต่อกับคลัสเตอร์ Operational Insights ที่จัดการด้วยตนเอง Operational Insights เป็นฐานข้อมูลวิเคราะห์แบบเรียลไทม์ (RT-OLAP) สำหรับแอปแบบเรียลไทม์และข้อมูลเชิงลึกด้านการปฏิบัติงาน เซิร์ฟเวอร์นี้ ไม่พร้อมใช้งานสำหรับ Capella โดยใช้ SDK couchbase-operational-insights และทำงานเป็นโปรเซสของตนเอง แยกจากเซิร์ฟเวอร์การปฏิบัติงาน
[!IMPORTANT]
CB_OPERATIONAL_INSIGHTS_CONNECTION_STRINGเป็น URL แบบ HTTP(S) ไม่ใช่สตริงการเชื่อมต่อcouchbase://— เช่นhttp://localhost:8095หรือhttps://<host>:18095ผ่าน TLS นี่คือการกำหนดค่าผิดพลาดที่พบบ่อยที่สุด
เริ่มต้นใช้งาน Operational Insights อย่างรวดเร็ว
จาก PyPI ด้วย 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"
}
}
}
}
ด้วย 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"
]
}
}
}
หากสร้างจากซอร์ส ให้ใช้ การกำหนดค่าซอร์สสำหรับ operational โดยใส่ operational-insights เป็นอาร์กิวเมนต์สุดท้าย พร้อมตัวแปรด้านบน
การเชื่อมต่อและการยืนยันตัวตนของ Operational Insights
| ตัวแปรสภาพแวดล้อม | อาร์กิวเมนต์ CLI | คำอธิบาย |
|---|---|---|
CB_OPERATIONAL_INSIGHTS_CONNECTION_STRING | --connection-string | URL ของปลายทาง (HTTP/HTTPS) จำเป็น |
CB_OPERATIONAL_INSIGHTS_USERNAME | --username | ชื่อผู้ใช้ |
CB_OPERATIONAL_INSIGHTS_PASSWORD | --password | รหัสผ่าน |
CB_OPERATIONAL_INSIGHTS_CA_CERT_PATH | --ca-cert-path | ใบรับรองรูท (PEM) สำหรับใบรับรองเซิร์ฟเวอร์ที่ลงนามด้วยตนเอง/ไม่น่าเชื่อถือ |
CB_OPERATIONAL_INSIGHTS_CLIENT_CERT_PATH | --client-cert-path | ใบรับรองไคลเอ็นต์สำหรับ mTLS — PEM (พร้อมคีย์) หรือชุด PKCS#12 (.p12/.pfx ไม่มีคีย์) ต้องใช้ URL https://; ใช้แทนชื่อผู้ใช้/รหัสผ่าน |
CB_OPERATIONAL_INSIGHTS_CLIENT_KEY_PATH | --client-key-path | คีย์ส่วนตัว (PEM) สำหรับใบรับรองไคลเอ็นต์ เว้นว่างไว้หากใช้ PKCS#12 |
CB_OPERATIONAL_INSIGHTS_CLIENT_CERT_PASSWORD | --client-cert-password | รหัสผ่านสำหรับคีย์ที่เข้ารหัสหรือชุด PKCS#12 |
CB_MCP_OPERATIONAL_INSIGHTS_QUERY_RESULT_MAX_SIZE | --operational-insights-query-result-max-size | ขนาดผลลัพธ์การค้นหาสูงสุด หน่วยเป็นไบต์ หากไม่กำหนดจะไม่มีขีดจำกัด เมื่อกำหนดไว้ การอ่านจะหยุดเมื่อถึงงบประมาณ และการตอบกลับจะแจ้ง truncated: true; แถวที่จะทำให้เกินขีดจำกัดจะไม่ถูกส่งกลับ ค่าที่มากกว่า 4 MiB (4194304) จะถูกจำกัดไว้ที่ 4 MiB พร้อมคำเตือนบน stderr เมื่อเริ่มต้น |
CB_MCP_OPERATIONAL_INSIGHTS_ASYNC_QUERY_RESULT_TIMEOUT | --operational-insights-async-query-result-timeout | ระยะหมดเวลา หน่วยเป็นวินาที สำหรับคำขอค้นหาแบบ async แต่ละครั้ง ได้แก่ การเริ่มค้นหา การตรวจสอบสถานะ การดึงผลลัพธ์ การทิ้งผลลัพธ์ และการยกเลิก สำหรับการดึงผลลัพธ์ ค่านี้ครอบคลุมการดาวน์โหลดทั้งหมด ดังนั้นหากอ่านผลลัพธ์ใช้เวลานานกว่านี้ การทำงานจะล้มเหลว เพิ่มค่านี้สำหรับผลลัพธ์ขนาดใหญ่หรือลิงก์ที่ช้า ต้องเป็นจำนวนเต็มบวก ค่าเริ่มต้นคือ 30 และค่าสูงสุดคือ 600 ค่าที่มากกว่านี้จะถูกจำกัดไว้ที่ 600 พร้อมคำเตือน ส่วนค่าอื่นที่ไม่ถูกต้องจะถูกบันทึกเป็นคำเตือนและใช้ค่า 30 |
การตั้งค่า ทั่วไป ทั้งหมดมีผล โดยมีข้อแตกต่างจากเซิร์ฟเวอร์ปฏิบัติการดังนี้:
- พอร์ตเริ่มต้นคือ
8001และไฟล์บันทึกเริ่มต้นคือmcp_server_operational_insights.logเพื่อให้เซิร์ฟเวอร์ทั้งสองทำงานพร้อมกันได้ - รองรับ worker เพียงหนึ่งตัว (
CB_MCP_WORKERS=1) เนื่องจากแฮนเดิลการค้นหาแบบ async อยู่ในหน่วยความจำของโปรเซส - ไม่มีตัวเลือก
CB_MCP_EMBEDDING_MODEL_*
เครื่องมือ Operational Insights
ชื่อทั้งหมด ยกเว้น get_server_configuration_status จะมีคำนำหน้า operational_insights_ เพื่อให้ลงทะเบียนเซิร์ฟเวอร์ทั้งสองในไคลเอ็นต์เดียวกันได้โดยไม่ชนกัน เครื่องมือเขียน (ทำเครื่องหมาย ✏️) จะไม่ถูกโหลด ขณะเปิดใช้โหมดอ่านอย่างเดียว ซึ่งเป็นค่าเริ่มต้น
สถานะเซิร์ฟเวอร์
| เครื่องมือ | คำอธิบาย |
|---|---|
get_server_configuration_status | เครื่องมือเดียวกับที่มีในเซิร์ฟเวอร์ปฏิบัติการ |
การค้นพบโมเดลข้อมูลและสคีมา
| เครื่องมือ | คำอธิบาย |
|---|---|
operational_insights_get_databases_in_cluster | แสดงรายการฐานข้อมูล |
operational_insights_get_scopes_in_database | แสดงรายการ scope ในฐานข้อมูล |
operational_insights_get_collections_in_scope | แสดงรายการ collection (ชุดข้อมูล) ใน scope |
operational_insights_get_schema_for_collection | อนุมาน JSON schema ของ collection โดยสุ่มตัวอย่าง |
การค้นหาและดัชนี
| เครื่องมือ | คำอธิบาย |
|---|---|
operational_insights_list_indexes | แสดงรายการดัชนีรองจาก System.Metadata.Index |
operational_insights_explain_query | อธิบาย (EXPLAIN) คำสั่ง SQL++ โดยไม่เรียกใช้ |
operational_insights_run_query_sync | เรียกใช้ SQL++ และส่งคืนแถว โดยไม่เกินขีดจำกัดขนาดผลลัพธ์ หรือจะส่งออกแทนก็ได้ มีการบังคับใช้โหมดอ่านอย่างเดียวที่ฝั่งเซิร์ฟเวอร์ |
operational_insights_run_query_async | เริ่มการค้นหาที่ใช้เวลานานและส่งคืน query_handle โดยไม่รอแถว และแนะนำให้ใช้กับการส่งออกขนาดใหญ่ด้วย มีการบังคับใช้โหมดอ่านอย่างเดียวที่ฝั่งเซิร์ฟเวอร์ |
operational_insights_get_async_query_results | ตรวจสอบการค้นหาแบบ async และส่งคืนแถว (หรือปลายทางส่งออก) เมื่อพร้อม |
operational_insights_discard_async_query_results | ล้างผลลัพธ์ของการค้นหาแบบ async ที่เสร็จสิ้นแล้ว |
operational_insights_cancel_async_query | หยุดการค้นหาแบบ async ที่ยังทำงานอยู่ (อนุญาตในโหมดอ่านอย่างเดียว) |
operational_insights_create_index ✏️ | สร้างดัชนีรองผ่าน CREATE INDEX |
การค้นหาแบบ async ทำงานตามลำดับ เริ่ม → ตรวจสอบ → ทิ้งหรือยกเลิก: operational_insights_run_query_async ส่งคืน query_handle, จากนั้นตรวจสอบ operational_insights_get_async_query_results จนกว่าจะพร้อม แล้ว operational_insights_discard_async_query_results จะล้างผลลัพธ์ หรือ operational_insights_cancel_async_query จะหยุดการค้นหาที่ยังทำงานอยู่
การส่งออกผลลัพธ์ขนาดใหญ่
แทนที่จะส่งคืนแถว operational_insights_run_query_sync และ operational_insights_run_query_async สามารถครอบคำสั่งด้วย COPY ... TO และเขียนแถวไปยังที่เก็บออบเจ็กต์ภายนอกได้ ระบุทั้งสามรายการ ได้แก่ copy_to_link (ลิงก์ที่มีอยู่ซึ่งสร้างด้วย CREATE LINK ... TYPE S3), copy_to_bucket และ copy_to_path พร้อมกับ copy_to_format ซึ่งเป็นตัวเลือกเสริม (json เป็นค่าเริ่มต้น หรือ parquet) จากนั้นเครื่องมือจะส่งคืนข้อความยืนยันโดยไม่มีแถว:
{
"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. ..."
}
- ระบบปฏิเสธปลายทางที่ระบุไม่ครบ แทนที่จะส่งคืนแถวโดยไม่แจ้งให้ทราบ
- เครื่องมือแบบ sync จะรอจนกว่าจะอัปโหลดเสร็จทั้งหมด สำหรับการส่งออกขนาดใหญ่ ควรใช้เครื่องมือแบบ async
- การส่งออกถูกบล็อกในโหมดอ่านอย่างเดียว (เนื่องจากเป็นการเขียนไปยังที่เก็บข้อมูลภายนอก) จึงต้องใช้
CB_MCP_READ_ONLY_MODE=falseหรือโทเค็นที่มีcouchbase-mcp:write - ไม่มี
csvให้ใช้ เนื่องจากต้องระบุสคีมาผลลัพธ์อย่างชัดเจน ซึ่งไม่สามารถอนุมานจากSELECTที่กำหนดเองได้
การตั้งค่าทั่วไป
การตั้งค่าเหล่านี้ทำงานเหมือนกันสำหรับเซิร์ฟเวอร์ทั้งสอง สามารถกำหนดแต่ละตัวเลือกเป็นตัวแปรสภาพแวดล้อมหรือเป็นแฟล็ก CLI หลังคำสั่งย่อยได้
การควบคุมความปลอดภัย
ปฏิบัติตามหลักการรักษาความปลอดภัยเหล่านี้:
- กำหนดสิทธิ์ให้ผู้ใช้ฐานข้อมูลเท่าที่จำเป็น — RBAC เป็นขอบเขตควบคุมที่มีอำนาจสูงสุด (ดูด้านล่าง)
- ให้เฉพาะเครื่องมือที่เอเจนต์จำเป็นต้องใช้ และปิดใช้งานเครื่องมืออื่น — เครื่องมือทุกตัวที่โหลดไว้คือสิ่งที่ LLM เรียกใช้ได้ ใช้โหมดอ่านอย่างเดียวและ
CB_MCP_DISABLED_TOOLSเพื่อให้รายการเครื่องมือมีเพียงเท่าที่จำเป็น - กำหนดให้ยืนยันก่อนใช้เครื่องมือที่มีความอ่อนไหว ที่ยังเปิดใช้งานอยู่ — ดูการกำหนดให้ยืนยัน
การควบคุมด้านล่างแบ่งเป็นสามชั้น ตั้งแต่ขอบเขตกว้างที่สุดไปจนถึงแคบที่สุด ใช้ร่วมกันได้ แต่โปรดจำไว้ว่า ไม่มีข้อใดใช้แทน RBAC ได้
[!IMPORTANT] สิทธิ์ RBAC ของผู้ใช้ฐานข้อมูลเป็นมาตรการควบคุมความปลอดภัยที่มีอำนาจสูงสุด ตัวอย่างเช่น การปิดใช้งาน
upsert_document_by_idและdelete_document_by_idไม่ได้ป้องกันrun_sql_plus_plus_queryจากการเรียกใช้INSERT/UPDATE/DELETE/MERGE— มีเพียงโหมดอ่านอย่างเดียวหรือการไม่มีสิทธิ์ RBAC เท่านั้นที่ทำได้ กำหนดสิทธิ์ให้ผู้ใช้ฐานข้อมูลของเซิร์ฟเวอร์เท่าที่จำเป็น
โหมดอ่านอย่างเดียว
CB_MCP_READ_ONLY_MODE (ค่าเริ่มต้น true) เป็นสวิตช์เดียวสำหรับควบคุมการเขียน:
true— เครื่องมือเขียนที่ทำเครื่องหมาย ✏️ ในรายการเครื่องมือของแต่ละเซิร์ฟเวอร์จะไม่ถูกโหลด และคำค้นหาที่แก้ไขข้อมูลหรือโครงสร้างจะถูกบล็อกfalse— โหลดเครื่องมือเขียนและอนุญาตให้ใช้คำค้นหาที่แก้ไขข้อมูลหรือโครงสร้าง
การปิดใช้งานเครื่องมือ
CB_MCP_DISABLED_TOOLS นำเครื่องมือออกจากการค้นพบทั้งหมด โดยรับรายการที่คั่นด้วยจุลภาคหรือพาธไปยังไฟล์ที่มีชื่อเครื่องมือหนึ่งชื่อต่อบรรทัด (# ใช้เริ่มความคิดเห็น):
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
บน Capella เซิร์ฟเวอร์ปฏิบัติการยังปิดใช้งานเครื่องมือผู้ดูแลระบบบางรายการโดยอัตโนมัติด้วย
การกำหนดให้ยืนยัน (elicitation)
CB_MCP_CONFIRMATION_REQUIRED_TOOLS ขอให้ผู้ใช้ยืนยันก่อนเรียกใช้เครื่องมือที่ระบุ โดยใช้ MCP elicitation รูปแบบที่รับเหมือนกับการปิดใช้งานเครื่องมือ คือรายการที่คั่นด้วยจุลภาคหรือไฟล์:
CB_MCP_CONFIRMATION_REQUIRED_TOOLS="delete_document_by_id,replace_document_by_id"
- หากไคลเอ็นต์รองรับ elicitation ระบบจะแจ้งให้ผู้ใช้ยืนยันก่อนเรียกใช้เครื่องมือ
- หากไม่รองรับ เครื่องมือจะทำงานโดยไม่ต้องยืนยัน เพื่อให้เข้ากันได้กับเวอร์ชันก่อนหน้า
- การยืนยันต้องใช้เซสชัน MCP จึงใช้ร่วมกับ HTTP แบบไร้สถานะไม่ได้ (
CB_MCP_STATELESS_HTTP=trueหรือCB_MCP_WORKERSที่มากกว่า 1) เซิร์ฟเวอร์จะปฏิเสธการเริ่มทำงานเมื่อใช้การตั้งค่าร่วมกันนี้ หากอยู่หลัง load balancer การยืนยันต้องใช้ sticky sessions — ดูLoad balancers
ทรานสปอร์ต
| ทรานสปอร์ต | ใช้สำหรับ | ปลายทาง |
|---|---|---|
stdio (ค่าเริ่มต้น) | ไคลเอ็นต์ภายในเครื่องหนึ่งตัวที่เปิดเซิร์ฟเวอร์เป็น subprocess | — |
http | ไคลเอ็นต์หลายตัวที่ใช้เซิร์ฟเวอร์ร่วมกัน รองรับ OAuth, การตรวจสอบสถานะ และ worker บนเซิร์ฟเวอร์ปฏิบัติการ | http://<host>:<port>/mcp |
กำหนดทรานสปอร์ตด้วย CB_MCP_TRANSPORT, ที่อยู่ bind ด้วย CB_MCP_HOST (ค่าเริ่มต้น 127.0.0.1) และพอร์ตด้วย CB_MCP_PORT (พอร์ตเริ่มต้นของแต่ละเซิร์ฟเวอร์เมื่อไม่ได้กำหนด) หากไม่มี OAuth ปลายทาง HTTP จะไม่มีการยืนยันตัวตน
uvx couchbase-mcp-server operational \
--connection-string='<couchbase_connection_string>' \
--username='<database_username>' \
--password='<database_password>' \
--transport=http
จากนั้นกำหนด URL นี้ให้ไคลเอ็นต์ของคุณ:
{
"mcpServers": {
"couchbase-http": {
"url": "http://localhost:8000/mcp"
}
}
}
Worker หลายตัว
หนึ่งโปรเซสใช้ CPU ไม่เกินประมาณหนึ่งคอร์ --workers N (CB_MCP_WORKERS) เรียกใช้ N โปรเซสผ่าน host และพอร์ตเดียวกัน จำนวนคอร์ที่พร้อมใช้งานเป็นจุดเริ่มต้นที่เหมาะสม รองรับ worker เฉพาะเซิร์ฟเวอร์ปฏิบัติการเท่านั้น เมื่อใช้ worker มากกว่าหนึ่งตัว:
- ต้องใช้ทรานสปอร์ต
httpและเซิร์ฟเวอร์จะทำงานในโหมด HTTP แบบไร้สถานะ เนื่องจากคำขอของไคลเอ็นต์อาจไปถึง worker คนละตัว นอกจากนี้ยังตั้งค่า--stateless-http=trueบน worker ตัวเดียวได้ เช่น เมื่ออยู่หลัง load balancer ที่ไม่มี sticky sessions - ไม่สามารถใช้เครื่องมือที่ต้องยืนยันได้
- แต่ละโปรเซสจะเขียนไฟล์บันทึกของตนเอง โดยตั้งชื่อตาม host และ process id (
mcp_server.<host>.<pid>.info.log) — มีหนึ่งชุดสำหรับ supervisor และอีกหนึ่งชุดต่อ worker
Load balancers
คุณสามารถเรียกใช้เซิร์ฟเวอร์หลายอินสแตนซ์หลัง load balancer ได้ แต่ละอินสแตนซ์เก็บเซสชัน MCP ไว้ในหน่วยความจำของตนเอง ดังนั้นการตั้งค่า load balancer จึงเป็นตัวกำหนดว่าสิ่งใดจะทำงานได้:
| Load balancer | การตั้งค่าเซิร์ฟเวอร์ | เครื่องมือที่ต้องยืนยัน |
|---|---|---|
Sticky sessions โดยกำหนดเส้นทางตามส่วนหัวคำขอ Mcp-Session-Id | Worker หนึ่งตัว แบบมีสถานะ (ค่าเริ่มต้น) | รองรับ |
| ไม่มี sticky sessions | --stateless-http=true | ไม่รองรับ — เซิร์ฟเวอร์จะปฏิเสธการเริ่มทำงานหากมีการกำหนดค่าไว้ |
- หากไม่มี sticky sessions อินสแตนซ์แบบมีสถานะจะปฏิเสธทุกคำขอที่เซสชันถูกสร้างขึ้นบนอินสแตนซ์อื่น ในกรณีนี้ให้ใช้โหมดไร้สถานะ
- กำหนดเส้นทางตามส่วนหัว
Mcp-Session-Idไม่ใช่คุกกี้ ไคลเอ็นต์ MCP จำนวนมากไม่เก็บคุกกี้ไว้ - หากอินสแตนซ์รีสตาร์ตหรือเกิด failover เซสชันและข้อความแจ้งยืนยันที่รอดำเนินการทั้งหมดจะสูญหาย ไคลเอ็นต์ต้องเริ่มเซสชันใหม่
- การค้นหาแบบ async ของ Operational Insights เก็บ
query_handleไว้ในหน่วยความจำของอินสแตนซ์ที่เริ่มการค้นหา แม้ในโหมดไร้สถานะก็ตาม การตรวจสอบ การทิ้ง หรือการยกเลิกการค้นหาบนอินสแตนซ์อื่นจะส่งคืนUnknown query_handleใช้เครื่องมือเหล่านี้กับอินสแตนซ์เดียว หรือใช้ sticky sessions เพื่อให้การเรียกทั้งหมดไปถึงอินสแตนซ์ที่เริ่มการค้นหา โหมดไร้สถานะจะไม่ส่งMcp-Session-Idจึงต้องใช้คีย์สำหรับกำหนดความสัมพันธ์อื่น เช่น ที่อยู่ IP ของไคลเอ็นต์
การตรวจสอบสถานะ
ในโหมด HTTP GET /health จะส่งคืน {"status": "ok", "server": "<server>"} บนพอร์ต MCP นี่คือการตรวจสอบว่าโปรเซสยังทำงานอยู่ โดยจะไม่เชื่อมต่อกับคลัสเตอร์ (ดังนั้นคลัสเตอร์ขัดข้องก็ไม่ทำให้คอนเทนเนอร์ที่ยังทำงานปกติถูกรีสตาร์ต) ไม่ต้องยืนยันตัวตนแม้เปิดใช้ OAuth และให้บริการโดย worker ทุกตัว ดูตัวอย่างการตรวจสอบได้ที่ Docker
การอนุญาต OAuth 2.1
เมื่อใช้ --transport=http เซิร์ฟเวอร์ใดเซิร์ฟเวอร์หนึ่งก็สามารถทำหน้าที่เป็น เซิร์ฟเวอร์ทรัพยากร OAuth 2.1 โดยตรวจสอบ bearer JWT กับ JWKS ของผู้ให้บริการข้อมูลประจำตัวของคุณ ใช้ได้กับผู้ให้บริการ OAuth 2.1/OIDC ทุกรายที่เผยแพร่ JWKS และไม่มีการออกโทเค็นหรือจัดการผู้ใช้ การตั้งค่า OAuth จะไม่มีผลกับ stdio
- OAuth จะเปิดใช้งานก็ต่อเมื่อกำหนด
CB_MCP_OAUTH_JWT_JWKS_URI,CB_MCP_OAUTH_JWT_ISSUERและCB_MCP_OAUTH_JWT_AUDIENCEครบทั้งสามรายการ หากกำหนดเพียงบางรายการ การเริ่มต้นจะล้มเหลว CB_MCP_OAUTH_MCP_BASE_URLยังเผยแพร่ Protected Resource Metadata ตาม RFC 9728 เพื่อให้ไคลเอ็นต์ค้นพบเซิร์ฟเวอร์การอนุญาตได้- การเข้าถึงจะถูกควบคุมด้วย scope สองรายการใน claim
scope/scpของโทเค็น ได้แก่couchbase-mcp:read(เครื่องมืออ่าน) และcouchbase-mcp:write(เครื่องมือเขียน) การเข้าถึงแบบเต็มต้องมีทั้งสองรายการ เปลี่ยนชื่อได้ด้วยCB_MCP_OAUTH_SCOPE_READ_LABEL/CB_MCP_OAUTH_SCOPE_WRITE_LABELหาก IdP ของคุณไม่สามารถออกป้ายกำกับเหล่านี้ได้ เซิร์ฟเวอร์ทั้งสองใช้ป้ายกำกับเดียวกัน ดังนั้นการกำหนดค่า IdP เพียงชุดเดียวจึงครอบคลุมทั้งสองเซิร์ฟเวอร์
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>'
ดูเอกสาร OAuth สำหรับเซิร์ฟเวอร์ปฏิบัติการ และเซิร์ฟเวอร์ Operational Insights เพื่อดูวิธีตั้งค่า IdP
การบันทึก
โดยค่าเริ่มต้น แต่ละเซิร์ฟเวอร์จะบันทึกลงใน stderr ที่ระดับ info
CB_MCP_LOG_LEVEL—off,error,warning,info(เหตุการณ์วงจรการทำงานและการเรียกใช้เครื่องมือ) หรือdebug.CB_MCP_LOG_SINKS—stderr,fileหรือทั้งสองอย่าง เมื่อใช้fileจะเขียนไฟล์ที่หมุนเวียนหนึ่งไฟล์ต่อระดับไว้ข้างCB_MCP_LOG_FILE(mcp_server.info.log,mcp_server.error.log, …).- การหมุนเวียนและการเก็บรักษา —
CB_MCP_LOG_ROTATION_MAX_SIZE_MB(ค่าเริ่มต้น 1 MB) และCB_MCP_LOG_RETENTION_BACKUP_COUNT(ค่าเริ่มต้น 1) มีผลกับทุกระดับ; กำหนดค่าแยกตามระดับได้ด้วยCB_MCP_LOG_<LEVEL>_ROTATION_MAX_SIZE_MB/CB_MCP_LOG_<LEVEL>_RETENTION_BACKUP_COUNT. หากขนาดไม่ถูกต้อง จะใช้ค่าเริ่มต้นพร้อมคำเตือนเมื่อเริ่มทำงานCB_MCP_LOG_MAX_BYTESเลิกใช้แล้ว - สแนปช็อตการกำหนดค่า — เมื่อใช้ sink
fileระบบจะเขียนระเบียน JSON ของสภาพแวดล้อมและการกำหนดค่าเซิร์ฟเวอร์ที่ปกปิดข้อมูลแล้วลงในmcp_server_config.log.jsonทุกครั้งที่เริ่มทำงาน เพื่อใช้ในการสนับสนุน
# Debug logging to stderr and rotating per-level files
uvx couchbase-mcp-server operational --log-level=debug --log-sinks=stderr,file
โดยปกติไคลเอ็นต์ MCP ของคุณจะบันทึก stderr ของเซิร์ฟเวอร์ด้วย — ดูตำแหน่งได้ที่ การตั้งค่าไคลเอ็นต์ รายละเอียดเพิ่มเติม: เอกสารการบันทึกสำหรับ เซิร์ฟเวอร์ปฏิบัติการ และ เซิร์ฟเวอร์ Operational Insights.
การตรวจสอบ
บันทึกการตรวจสอบจะบันทึก ใครทำอะไร และได้รับอนุญาตหรือไม่ — แยกจากบันทึกการปฏิบัติงาน ซึ่งบันทึกสิ่งที่ผิดพลาด เซิร์ฟเวอร์ MCP เป็นชั้นเดียวที่ตอบคำถามนี้เกี่ยวกับเอเจนต์ได้: ทุกคำขอจะไปถึงคลัสเตอร์ในฐานะผู้ใช้ฐานข้อมูลรายเดียว และการตัดสินใจต่าง ๆ เช่น การปฏิเสธขอบเขต การบล็อกแบบอ่านอย่างเดียว หรือการปฏิเสธการยืนยัน จะไม่ไปถึงคลัสเตอร์เลย
การตรวจสอบ ปิดอยู่โดยค่าเริ่มต้น เปิดใช้ด้วย CB_MCP_AUDIT_LOG_ENABLED=true; ระบบจะเขียนลง stderr เว้นแต่คุณจะตั้งค่า CB_MCP_AUDIT_LOG_SINKS=file และ 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
ระเบียนใช้รูปแบบ JSON Lines โดยใช้คำศัพท์ของฟิลด์เดียวกับ Couchbase Server และ 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"}
การทำงานของการตรวจสอบ
- ข้อมูลระบุตัวตน —
real_useridคือผู้เรียกใช้:oauth(หัวเรื่องของโทเค็น),local(ผู้ใช้ OS บน stdio) หรือanonymous(HTTP ที่ไม่มี OAuth ซึ่งจะแสดงคำเตือนเมื่อเริ่มทำงาน) - ความสัมพันธ์ของระเบียน —
cidจัดกลุ่มระเบียนทั้งหมดจากคำขอเดียวกัน และส่งไปเป็นclient_context_idของ SQL++ จึงเชื่อมโยงกับclientContextIdของ Couchbase Server ได้อย่างตรงกัน โดยตั้งใจไม่ให้มีตัวระบุเซสชัน - เหตุการณ์ — แค็ตตาล็อกหมายเลขตายตัว (วงจรการทำงาน, initialize, ปฏิเสธโทเค็น, ปฏิเสธขอบเขต, บล็อกแบบอ่านอย่างเดียว, ปฏิเสธ/ข้ามการยืนยัน และคู่เหตุการณ์อ่าน/เขียนสำหรับแต่ละหมวดหมู่เครื่องมือ)
queryและsearchเป็นข้อยกเว้น: แต่ละรายการจะบันทึกเป็นเหตุการณ์เดียวแทนคู่เหตุการณ์อ่าน/เขียน เนื่องจากไม่สามารถแยกความแตกต่างได้อย่างน่าเชื่อถือสำหรับส่วนที่ขับเคลื่อนด้วยคำสั่งและส่วนค้นหา การดำเนินการเวกเตอร์อยู่ภายในสองหมวดหมู่นี้ แค็ตตาล็อกฉบับเต็มอยู่ในแพ็กเกจในชื่อdescriptor.jsonเซิร์ฟเวอร์ปฏิบัติการใช้บล็อก0xF000(61440), Operational Insights ใช้0x10000(65536) และทั้งสองใช้0xE000(57344) ร่วมกันสำหรับเหตุการณ์หลัก - การกรอง —
CB_MCP_AUDIT_LOG_DISABLED_EVENTSระงับเหตุการณ์ อ่าน ตาม ID ตัวเลข (เช่น61490,61492) ไม่สามารถปิดเหตุการณ์เขียนและเหตุการณ์ความปลอดภัยได้ เช่นเดียวกับหมวดหมู่เหตุการณ์เดียวquery(61507 หรือ 65603 บน Operational Insights) และsearch(61510): เหตุการณ์เดียวครอบคลุมทั้งการเขียนและการอ่านของแต่ละหมวดหมู่ ดังนั้นการปิดเหตุการณ์ดังกล่าวจะทำให้สูญเสียระเบียนการเปลี่ยนแปลงข้อมูล - การหมุนเวียน — ตามขนาด (
CB_MCP_AUDIT_LOG_ROTATION_MAX_SIZE_MB, ค่าเริ่มต้น 10) และอายุ (CB_MCP_AUDIT_LOG_ROTATION_INTERVAL, ค่าเริ่มต้น1d) โดยใช้เงื่อนไขที่เกิดก่อน;0ปิดการหมุนเวียนอย่างใดอย่างหนึ่ง ไฟล์ที่หมุนเวียนจะมีการประทับเวลาและบีบอัดด้วย gzip; ไฟล์ที่ใช้งานอยู่จะเป็นข้อความธรรมดาสำหรับtail -f. - ไฟล์แยกตามโปรเซส — ระบบจะแทรก host และ pid ลงในชื่อไฟล์ (
audit.log→audit.<host>.<pid>.log) เพื่อไม่ให้โปรเซสที่ทำงานพร้อมกันใช้ไฟล์ร่วมกัน - การเก็บรักษาแยกตามไฟล์ —
CB_MCP_AUDIT_LOG_RETENTION_MAX_BACKUPS(ค่าเริ่มต้น 10) จำกัดจำนวนไฟล์สำรองของไฟล์หนึ่งไฟล์ แต่ละโปรเซสใหม่จะเขียนไฟล์ใหม่ และไม่มีการลบไฟล์เก่าโดยอัตโนมัติ ดังนั้นควรจัดสรรพื้นที่ดิสก์หรือกวาดล้างไฟล์audit.*.log*เก่า - Fail-open — หากเขียนไฟล์ไม่ได้ เซิร์ฟเวอร์จะยังคงให้บริการและนับจำนวนระเบียนที่ทิ้งไป;
get_server_configuration_statusรายงานwritten/dropped/write_errors. - อาร์กิวเมนต์ของเครื่องมือ — บันทึกเฉพาะเมื่อใช้
CB_MCP_AUDIT_LOG_TOOL_ARGS=trueซึ่งจะแสดงคำเตือนเมื่อเริ่มทำงาน รุ่นนี้ไม่มีการปกปิดข้อมูล ดังนั้นอาร์กิวเมนต์ รวมถึงเนื้อหาเอกสารฉบับเต็ม จะถูกเขียนตามต้นฉบับ
การตั้งค่าไคลเอ็นต์
ไคลเอ็นต์แต่ละตัวต้องมีการกำหนดค่าเซิร์ฟเวอร์จากคู่มือเริ่มต้นใช้งานฉบับย่อของ เซิร์ฟเวอร์ปฏิบัติการ หรือ Operational Insights ในตำแหน่งการกำหนดค่าของตนเอง ตัวอย่างด้านล่างใช้เซิร์ฟเวอร์ปฏิบัติการ
Claude Desktop
- เปิดไฟล์การกำหนดค่า (ดู คู่มือเริ่มต้นใช้งาน MCP):
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
- macOS:
- เพิ่มเซิร์ฟเวอร์ใต้
mcpServersแล้วเริ่ม Claude Desktop ใหม่
บันทึก: macOS ~/Library/Logs/Claude, Windows %APPDATA%\Claude\Logs ดู คู่มือแก้ไขปัญหา MCP.
Cursor
- ไปที่ Cursor Settings > Tools & Integrations > MCP Tools (ดู เอกสาร MCP ของ Cursor) หรือใช้ลิงก์ ติดตั้งใน Cursor แบบคลิกเดียว — จากนั้นแทนที่สตริงการเชื่อมต่อและข้อมูลรับรองตัวอย่าง
- เพิ่มการกำหนดค่าใต้
mcpServersแล้วบันทึก - รีเฟรชรายการเซิร์ฟเวอร์ MCP เพื่อตรวจสอบว่าเปิดใช้
couchbaseแล้ว
บันทึก: ในแผงด้านล่าง ให้เปิด Output แล้วเลือก Cursor MCP
Windsurf Editor
- เปิด Command Palette > Windsurf MCP Configuration Panel หรือ Windsurf Settings > Advanced > Cascade > Model Context Protocol (MCP) Servers (ดู เอกสาร MCP ของ Windsurf)
- คลิก Add Server > Add custom server วางการกำหนดค่าแล้วบันทึก
- รีเฟรชรายการเซิร์ฟเวอร์เพื่อตรวจสอบว่าเปิดใช้
couchbaseแล้ว
VS Code
VS Code ใช้ servers เป็นคีย์ระดับบนสุดแทน mcpServers วางการกำหนดค่าใน .vscode/mcp.json สำหรับ workspace หรือเรียกใช้ MCP: Open User Configuration เพื่อใช้กับทุก workspace (ดู เอกสาร 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"
}
}
}
}
เมื่อบันทึกไฟล์ เซิร์ฟเวอร์จะเริ่มทำงาน; ใช้การดำเนินการ Running | Stop | n Tools ที่อยู่เหนือไฟล์เพื่อจัดการเซิร์ฟเวอร์
บันทึก: เรียกใช้ MCP: List Servers เลือก couchbase แล้วเลือก Show Output
JetBrains IDEs
- ติดตั้งปลั๊กอิน AI Assistant หรือ Junie
- ไปที่ Settings > Tools > AI Assistant (or Junie) > MCP Server คลิก + เพิ่มการกำหนดค่า แล้วคลิก Apply
- วางเมาส์เหนือสถานะของเซิร์ฟเวอร์เพื่อดูเครื่องมือ
บันทึก: Help > Show Log in Finder (Explorer) > mcp > couchbase
Docker
อิมเมจที่สร้างไว้ล่วงหน้าเผยแพร่บน Docker Hub ในชื่อ couchbase/mcp-server และมีรายชื่อเซิร์ฟเวอร์อยู่ใน Docker MCP Catalog กำหนดค่าคอนเทนเนอร์ด้วยตัวแปรสภาพแวดล้อมเดียวกับด้านบน ดู หน้า Docker Hub (DOCKER.md) สำหรับแท็ก วอลุ่ม และตัวอย่าง health check
การเรียกใช้ผ่าน HTTP — โปรดทราบว่าเซิร์ฟเวอร์ต้อง bind กับ 0.0.0.0 จึงจะเข้าถึงได้จากภายนอกคอนเทนเนอร์:
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
- หาก Couchbase ทำงานบนเครื่อง host ให้ใช้
couchbase://host.docker.internalเป็นสตริงการเชื่อมต่อ (ดู เครือข่าย Docker) ใช้--network=<your_network>เพื่อเข้าร่วมเครือข่ายของคอนเทนเนอร์อื่น - ต่อท้าย
operational-insightsแทนoperationalเพื่อเรียกใช้ เซิร์ฟเวอร์ Operational Insights (พอร์ต8001)
การสร้างอิมเมจจากซอร์ส
docker build -t mcp/couchbase-src .
./build.sh [image-name] สร้างอิมเมจด้วยอาร์กิวเมนต์เดียวกับ CI — โดยกำหนด build args GIT_COMMIT_HASH และ BUILD_DATE และติดแท็กอิมเมจเป็น latest และ <short-commit> (ชื่อเริ่มต้นคือ mcp/couchbase-src) หากต้องการสร้างพร้อมป้ายกำกับด้วยตนเอง:
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
การแก้ไขปัญหา
ดูคู่มือฉบับเต็มได้ที่เอกสารการแก้ไขปัญหาสำหรับ เซิร์ฟเวอร์ปฏิบัติการ และ เซิร์ฟเวอร์ Operational Insights รวมถึงแนวทางด้านความปลอดภัยสำหรับ เซิร์ฟเวอร์ปฏิบัติการ และ เซิร์ฟเวอร์ Operational Insights รายการตรวจสอบเบื้องต้น:
- ตรวจสอบสตริงการเชื่อมต่อ ชื่อผู้ใช้/รหัสผ่าน หรือเส้นทางใบรับรอง
- สำหรับ Capella ตรวจสอบให้แน่ใจว่าคลัสเตอร์ อนุญาตการเชื่อมต่อ จากเครื่องที่ใช้เรียกใช้เซิร์ฟเวอร์
- ตรวจสอบว่าผู้ใช้ฐานข้อมูลเข้าถึง bucket ได้อย่างน้อยหนึ่งรายการ
- หากไคลเอ็นต์ค้นหา
uv/uvxไม่พบ ให้ระบุเส้นทางแบบสัมบูรณ์ในcommand - เมื่อเรียกใช้จากซอร์ส ให้ตรวจสอบเส้นทาง repository ในการกำหนดค่า และเรียกใช้
uv syncหลังดึงข้อมูลอัปเดต - เรียกใช้
get_server_configuration_statusเพื่อดูการกำหนดค่าที่เซิร์ฟเวอร์แก้ไขได้จริง และตรวจสอบบันทึกของไคลเอ็นต์ (ดู การตั้งค่าไคลเอ็นต์)
คำถามที่พบบ่อย
ฉันจะเชื่อมต่อ Claude Desktop กับ Couchbase ได้อย่างไร? เพิ่มการกำหนดค่า เริ่มต้นใช้งานฉบับย่อ ลงใน claude_desktop_config.json แล้วเริ่ม Claude Desktop ใหม่ — ดู การตั้งค่าไคลเอ็นต์
ใช้กับ Couchbase Capella ได้ไหม? ได้ โดยใช้ เซิร์ฟเวอร์ปฏิบัติการ: การกำหนดค่าเดียวกันใช้ได้กับทั้ง Capella และคลัสเตอร์ที่จัดการเอง แม้ว่าเครื่องมือผู้ดูแลระบบบางรายการจะใช้ได้เฉพาะกับคลัสเตอร์ที่จัดการเองเท่านั้น (ดู เครื่องมือ) ส่วน เซิร์ฟเวอร์ Operational Insights ใช้ได้เฉพาะกับคลัสเตอร์ Operational Insights ที่จัดการเองเท่านั้น
การอนุญาตให้เอเจนต์ AI เขียนลงฐานข้อมูลปลอดภัยหรือไม่? โดยค่าเริ่มต้น ไม่ปลอดภัย เครื่องมือเขียนจะไม่ถูกโหลด และ SQL++ ที่แก้ไขข้อมูลจะถูกบล็อก หากเปิดใช้การเขียน คุณยังปิดใช้เครื่องมือแต่ละรายการหรือกำหนดให้ต้องยืนยันได้ — แต่สิทธิ์ RBAC ของผู้ใช้ Couchbase ยังคงเป็นขอบเขตความปลอดภัยที่แท้จริง ดู การควบคุมความปลอดภัย
ฉันจำเป็นต้องรู้ SQL++ หรือไม่? ไม่จำเป็น ถามด้วยภาษาทั่วไป แล้วผู้ช่วยจะเขียน SQL++ ให้ run_sql_plus_plus_query นอกจากนี้ยังอธิบายแผนการสืบค้นหรือขอคำแนะนำจาก Index Advisor ได้ด้วย
STDIO หรือ Streamable HTTP? ใช้ STDIO สำหรับไคลเอ็นต์ภายในเครื่องเพียงตัวเดียว ใช้ Streamable HTTP เพื่อแชร์เซิร์ฟเวอร์เดียวระหว่างไคลเอ็นต์หลายตัว พร้อม OAuth ดู การขนส่ง
Couchbase สนับสนุนอย่างเป็นทางการหรือไม่? สนับสนุน หากมีใบอนุญาต Couchbase AI Data Plane หากไม่มี วิศวกร Couchbase จะให้ความช่วยเหลือตามความเหมาะสมผ่าน GitHub issues ดู นโยบายการสนับสนุน
การมีส่วนร่วม
ยินดีรับการมีส่วนร่วม ทั้งการแก้บั๊ก ฟีเจอร์ และเอกสาร หากต้องการรายงานบั๊กหรือขอความช่วยเหลือ เปิด GitHub issue
ดู CONTRIBUTING.md สำหรับการตั้งค่าสภาพแวดล้อมพัฒนา การตรวจ lint การทดสอบ โครงสร้างโปรเจกต์ และขั้นตอนการทำงาน เริ่มต้นได้ดังนี้:
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
การทดสอบการผสานรวม จะทำงานกับคลัสเตอร์จริง ส่งออก CB_CONNECTION_STRING, CB_USERNAME, CB_PASSWORD และ CB_MCP_TEST_BUCKET (ไม่บังคับ); การทดสอบ Operational Insights ยังใช้ CB_OPERATIONAL_INSIGHTS_CONNECTION_STRING / _USERNAME / _PASSWORD และจะข้ามการทดสอบเมื่อไม่ได้กำหนดค่าเหล่านี้ จากนั้นเรียกใช้:
uv run --extra dev pytest tests/integration -v
ข้อมูลการใช้งาน ความเสี่ยงจาก LLM และนโยบายการสนับสนุน
การเก็บรวบรวมข้อมูลการใช้งาน
ผลิตภัณฑ์นี้เก็บรวบรวมข้อมูลการใช้งานและประสิทธิภาพโดยอัตโนมัติ (เช่น ชื่อและเวอร์ชันของผลิตภัณฑ์) รวมถึงข้อมูลเบราว์เซอร์ (เช่น ที่อยู่ IP) (เรียกรวมกันว่า "ข้อมูลการใช้งาน") Couchbase ใช้ข้อมูลการใช้งานร่วมกับข้อมูลอื่น ๆ ที่คุณอาจให้แก่ Couchbase (เช่น ชื่อผู้ใช้หรือที่อยู่อีเมล) เพื่อพัฒนาและปรับปรุงผลิตภัณฑ์ของเรา ตลอดจนใช้ประกอบโครงการด้านการขายและการตลาด เราไม่เข้าถึงหรือเก็บรวบรวมข้อมูลใด ๆ ที่คุณจัดเก็บไว้ในผลิตภัณฑ์ของ Couchbase เราใช้ข้อมูลการใช้งานเพื่อทำความเข้าใจรูปแบบการใช้งานโดยรวมและทำให้ผลิตภัณฑ์ของเรามีประโยชน์ต่อคุณมากยิ่งขึ้น สำหรับข้อมูลเพิ่มเติมเกี่ยวกับวิธีที่ Couchbase เก็บรวบรวม ปกป้อง และประมวลผลข้อมูล โปรดดูนโยบายความเป็นส่วนตัวของ Couchbase ที่ https://www.couchbase.com/privacy-policy.
ความเสี่ยงที่เกี่ยวข้องกับ LLM
- การใช้โมเดลภาษาขนาดใหญ่และเทคโนโลยีที่คล้ายกันมีความเสี่ยง รวมถึงความเป็นไปได้ที่จะได้ผลลัพธ์ที่ไม่ถูกต้องหรือเป็นอันตราย
- Couchbase ไม่ได้ตรวจสอบหรือประเมินคุณภาพหรือความถูกต้องของผลลัพธ์ดังกล่าว และผลลัพธ์เหล่านั้นอาจไม่สะท้อนมุมมองของ Couchbase
- คุณเป็นผู้รับผิดชอบแต่เพียงผู้เดียวในการพิจารณาว่าจะใช้โมเดลภาษาขนาดใหญ่และเทคโนโลยีที่เกี่ยวข้องหรือไม่ รวมถึงการปฏิบัติตามข้อกำหนดของใบอนุญาต เงื่อนไขการใช้งาน และนโยบายขององค์กรที่กำกับดูแลการใช้งานดังกล่าวของคุณ
นโยบายการสนับสนุน
Couchbase MCP Server เป็นโอเพนซอร์สและดูแลโดยวิศวกรของ Couchbase วิธีขอความช่วยเหลือขึ้นอยู่กับวิธีที่คุณใช้งาน:
- การใช้งานโดยชุมชน — รายงานข้อบกพร่อง ถามคำถาม และขอฟีเจอร์ได้โดย เปิดประเด็นใน GitHub วิศวกรของ Couchbase ติดตามที่เก็บโค้ดและตอบกลับตามความเหมาะสม โดยไม่มีการรับประกันระยะเวลาตอบกลับ พอร์ทัลการสนับสนุนของ Couchbase ไม่สามารถช่วยเหลือการใช้งานโดยชุมชนได้
- การสนับสนุนสำหรับองค์กร — ใช้ได้เมื่อได้รับสิทธิ์ใช้งาน Couchbase AI Data Plane ซึ่งครอบคลุม Couchbase Agent Memory และ Couchbase Agent Catalog ด้วย ลูกค้าที่ได้รับสิทธิ์ใช้งานสามารถขอความช่วยเหลือผ่านช่องทางการสนับสนุนของ Couchbase ที่ใช้อยู่ตามปกติ
ขอขอบคุณที่ใช้และมีส่วนร่วมในโครงการนี้!