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 License Python 3.11+ PyPI version Install in Cursor Verified on MseeP Trust Score

เอกสารฉบับเต็ม: docs.couchbase.com/mcp-server

Couchbase Server MCP server

สารบัญ

เหตุผลที่ควรใช้ 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 serverOperational Insights server
ใช้กับคลัสเตอร์ Couchbase (Capella หรือจัดการเอง)คลัสเตอร์ Operational Insights ที่จัดการเอง (ไม่มีให้บริการบน Capella)
Subcommandoperational (ค่าเริ่มต้น)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 เริ่มต้น80008001
ไฟล์ล็อกเริ่มต้นmcp_server.logmcp_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_metricsManagement REST (/pools/default/stats/range)
get_cluster_tasksManagement REST (/pools/default/tasks)
get_bucket_configManagement REST (/pools/default/buckets[/<name>])
get_cluster_health_snapshotManagement REST รวมถึงปลายทางระดับโหนด
get_cluster_system_eventsManagement REST (/events)
get_index_statsIndex Service REST (/api/v1/stats ของ indexer แต่ละตัว)
get_cluster_query_vitalsQuery service REST (/admin/vitals)
get_active_queriesQuery service REST (/admin/active_requests)
delete_active_queryQuery 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จำเป็นไม่บังคับหมายเหตุ
capellaCB_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
openaiCB_MCP_EMBEDDING_MODEL_API_KEY, CB_MCP_EMBEDDING_MODELCB_MCP_EMBEDDING_MODEL_ENDPOINTตั้งค่า endpoint เพื่อใช้เซิร์ฟเวอร์ภายในเครื่องที่เข้ากันได้กับ 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_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, httpstdio
CB_MCP_HOST--hostโฮสต์สำหรับโหมดการขนส่ง HTTP127.0.0.1
CB_MCP_PORT--portพอร์ตสำหรับโหมดการขนส่ง HTTP8000
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-issuerclaim JWT iss ที่คาดหวัง จำเป็นสำหรับเปิดใช้งาน OAuthไม่มี
CB_MCP_OAUTH_JWT_AUDIENCE--oauth-audienceclaim JWT aud ที่คาดหวัง จำเป็นสำหรับเปิดใช้งาน OAuthไม่มี
CB_MCP_OAUTH_JWT_ALGORITHM--oauth-algorithmอัลกอริทึมการลงนาม JWT: เลือกหนึ่งรายการจาก RS256/384/512, ES256/384/512, PS256/384/512RS256
CB_MCP_OAUTH_MCP_BASE_URL--oauth-mcp-base-urlURL พื้นฐานสาธารณะของเซิร์ฟเวอร์นี้ เมื่อกำหนดค่านี้ จะเผยแพร่ 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'; มีความหมายเช่นเดียวกับป้ายกำกับ readcouchbase-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 เมื่อใช้ stdioconsole
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-idAWS access key ID ใช้กับผู้ให้บริการ bedrock เท่านั้น ไม่ต้องระบุหากต้องการใช้ AWS credential chain เริ่มต้นไม่มี
CB_MCP_EMBEDDING_MODEL_AWS_SECRET_ACCESS_KEY--embedding-model-aws-secret-access-keyAWS secret access key ใช้กับผู้ให้บริการ bedrock เท่านั้นไม่มี
CB_MCP_EMBEDDING_MODEL_AWS_REGION--embedding-model-aws-regionAWS 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-stringURL ของปลายทาง (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-IdWorker หนึ่งตัว แบบมีสถานะ (ค่าเริ่มต้น)รองรับ
ไม่มี 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
  1. เปิดไฟล์การกำหนดค่า (ดู คู่มือเริ่มต้นใช้งาน MCP):
    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows: %APPDATA%\Claude\claude_desktop_config.json
  2. เพิ่มเซิร์ฟเวอร์ใต้ mcpServers แล้วเริ่ม Claude Desktop ใหม่

บันทึก: macOS ~/Library/Logs/Claude, Windows %APPDATA%\Claude\Logs ดู คู่มือแก้ไขปัญหา MCP.

Cursor
  1. ไปที่ Cursor Settings > Tools & Integrations > MCP Tools (ดู เอกสาร MCP ของ Cursor) หรือใช้ลิงก์ ติดตั้งใน Cursor แบบคลิกเดียว — จากนั้นแทนที่สตริงการเชื่อมต่อและข้อมูลรับรองตัวอย่าง
  2. เพิ่มการกำหนดค่าใต้ mcpServers แล้วบันทึก
  3. รีเฟรชรายการเซิร์ฟเวอร์ MCP เพื่อตรวจสอบว่าเปิดใช้ couchbase แล้ว

บันทึก: ในแผงด้านล่าง ให้เปิด Output แล้วเลือก Cursor MCP

Windsurf Editor
  1. เปิด Command Palette > Windsurf MCP Configuration Panel หรือ Windsurf Settings > Advanced > Cascade > Model Context Protocol (MCP) Servers (ดู เอกสาร MCP ของ Windsurf)
  2. คลิก Add Server > Add custom server วางการกำหนดค่าแล้วบันทึก
  3. รีเฟรชรายการเซิร์ฟเวอร์เพื่อตรวจสอบว่าเปิดใช้ 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
  1. ติดตั้งปลั๊กอิน AI Assistant หรือ Junie
  2. ไปที่ Settings > Tools > AI Assistant (or Junie) > MCP Server คลิก + เพิ่มการกำหนดค่า แล้วคลิก Apply
  3. วางเมาส์เหนือสถานะของเซิร์ฟเวอร์เพื่อดูเครื่องมือ

บันทึก: 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 ที่ใช้อยู่ตามปกติ

ขอขอบคุณที่ใช้และมีส่วนร่วมในโครงการนี้!