Couchbase

официальный

Взаимодействуйте с данными, хранящимися в кластерах Couchbase, используя естественный язык.

Что можно делать с Couchbase MCP?

  • Изучение данных кластера — Просмотр бакетов, областей и коллекций, а также определение схемы коллекции, например orders.
  • Выполнение запросов SQL++ — Выполнение запросов SQL++ только для чтения к бакету и области, а также объяснение планов запросов.
  • Просмотр документов — Получение документа по идентификатору или чтение отдельных путей к поддокументам без загрузки всего документа.
  • Проверка состояния кластера — Сведения о состоянии кластера, работающих службах и диагностике подключения.
  • Анализ производительности запросов — Поиск запросов с самым долгим временем выполнения, наиболее частых запросов или запросов без покрывающего индекса.
  • Поиск и векторные запросы — Выполнение полнотекстового поиска и запросов на векторное сходство по настроенным индексам.

Документация

MCP-сервер Couchbase

MCP-сервер Couchbase — это размещаемый самостоятельно сервер MCP, который позволяет ИИ-агентам подключаться к данным в серверах Couchbase и взаимодействовать с ними (независимо от того, размещены они в Capella или управляются самостоятельно), а также работать с Operational Insights Enterprise. Он предоставляет инструменты в таких категориях, как состояние кластера, схема данных, запросы и другие, а также средства контроля безопасности: режим только для чтения и точечное отключение инструментов. Поддерживаются транспорты STDIO и Streamable HTTP с возможностями OAuth.

MCP-сервер Couchbase распространяется как пакет Python Package Index (PyPI) и через Docker. Корпоративная поддержка MCP-сервера Couchbase доступна при лицензировании 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

Содержание

Зачем нужен MCP-сервер Couchbase

  • Безопасность по умолчанию — инструменты записи не загружаются, а запросы, изменяющие данные, блокируются, если не задано CB_MCP_READ_ONLY_MODE=false; отдельные инструменты также можно отключить или сделать доступными только после подтверждения пользователя.
  • Couchbase Server и Operational Insights — операционный сервер подключается к кластеру Couchbase Capella или самостоятельно управляемому кластеру Couchbase Server с одинаковой конфигурацией; сервер Operational Insights подключается к самостоятельно управляемым кластерам Operational Insights.
  • Учет RBAC — средства управления инструментами задают ограничения для LLM; авторитетной границей безопасности остается управление доступом на основе ролей пользователя Couchbase.
  • Транспорты для промышленной эксплуатации — STDIO для локальных настольных клиентов или Streamable HTTP с дополнительной поддержкой OAuth 2.1 (любой поставщик удостоверений, публикующий JWKS: Auth0, Okta, Keycloak, Entra, Cognito, …), проверками работоспособности и журналированием аудита для совместных развертываний. Операционный сервер также может запускать несколько рабочих процессов, чтобы задействовать больше ядер ЦП.
  • Любой MCP-клиент — проверено с Claude Desktop, Cursor, Windsurf, VS Code и JetBrains AI Assistant/Junie.

После подключения можно задавать, например, такие вопросы:

  • «Какие у меня есть бакеты, области и коллекции и какова схема коллекции orders?»
  • «Найди 10 самых новых документов в users, где status = 'active'.»
  • «Какие 5 запросов были самыми медленными за последний час и не хватает ли для каких-либо из них покрывающего индекса?»
  • «Исправен ли этот кластер и какие службы запущены?»
  • «Вставь новый документ в products с такими полями: …» (требуется CB_MCP_READ_ONLY_MODE=false)

Выбор сервера

В этот пакет входят два MCP-сервера. Каждый запускается собственной подкомандой, подключается к кластеру определенного типа и предоставляет собственные инструменты. Выберите сервер, соответствующий вашему кластеру, ознакомьтесь с разделом о его настройке и инструментах, а затем используйте раздел Общие настройки для параметров, общих для обоих серверов. Чтобы использовать оба сервера, зарегистрируйте каждый из них отдельно в MCP-клиенте.

Операционный серверСервер Operational Insights
Для чего используетсяКластер Couchbase (Capella или самостоятельно управляемый)Самостоятельно управляемый кластер Operational Insights (недоступен в Capella)
Подкоманда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 — состояние кластера, схема, KV, SQL++, индексы, полнотекстовый и векторный поиск, производительность запросов13 — схема, SQL++ (синхронный и асинхронный), индексы, экспорт
Порт HTTP по умолчанию80008001
Файл журнала по умолчаниюmcp_server.logmcp_server_operational_insights.log

Сейчас подкоманду для операционного сервера можно не указывать — достаточно запустить couchbase-mcp-server, — но явное указание делает конфигурацию однозначной. Параметры указываются после подкоманды: couchbase-mcp-server operational --transport=http. Проверьте установленную версию командой uvx couchbase-mcp-server --version.

Операционный сервер

Сервер operational подключается к кластеру Couchbase в Capella или к самостоятельно управляемому Couchbase Server, используя Python SDK couchbase.

Быстрый старт: операционный сервер

Вам понадобится работающий кластер Couchbase — быстрее всего создать его с помощью бесплатного уровня Capella (можно импортировать пример набора данных) — и MCP-клиент. Добавьте в конфигурацию клиента один из следующих вариантов (см. раздел Настройка клиента, чтобы узнать, где хранится конфигурация каждого клиента). Если в клиенте уже настроены другие серверы, добавьте 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, чтобы обновить зависимости.

Подключение и аутентификация операционного сервера

Используйте либо имя пользователя и пароль, либо клиентский сертификат (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Корневой сертификат для самоподписанного или недоверенного сертификата сервера (не требуется для 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"
      }
    }
  }
}

Инструменты операционного сервера

Инструменты записи (помеченные ✏️) не загружаются, пока включен режим только для чтения, который используется по умолчанию. Инструменты, помеченные 🖥️, доступны только для самостоятельно управляемых кластеров: они используют конечные точки административного REST API, которые Capella не предоставляет, либо (discover_tool_input_values) возвращают только справочные данные для инструмента, который их использует. Поэтому для них требуется самостоятельно управляемый Couchbase Server 7.6+, и они не регистрируются для подключений к Capella.

Настройка кластера и состояние

ИнструментОписание
get_server_configuration_statusСостояние и конфигурация сервера без подключения к кластеру: режим только для чтения, отключенные инструменты и инструменты, требующие подтверждения, OAuth, ведение журналов и счетчики аудита
test_cluster_connectionПроверка учетных данных кластера путем подключения к нему
get_cluster_health_and_servicesСостояние кластера и запущенные службы; при необходимости фильтрация с помощью service_types
get_client_connectivity_reportКэшированные диагностические данные подключения SDK без активной проверки сети
get_cluster_metrics 🖥️Статистика кластера за исторический период (конечная точка stats-range)
get_cluster_tasks 🖥️Текущие задачи — ребалансировка, компактизация, XDCR, построение индекса. Требуется ro_admin
get_cluster_health_snapshot 🖥️Состояние каждого узла: топология служб, членство, оркестратор и сводная оценка состояния. Требуется ro_admin
get_bucket_config 🖥️Конфигурация и текущее состояние одного или всех бакетов: квоты, вытеснение, реплики, долговечность, хранилище, компактизация. Требуется ro_admin
get_cluster_system_events 🖥️Системный журнал событий (изменения конфигурации, отказы, ребалансировки, перезапуски) за период, заданный с помощью since_time. Требуется Full Admin или Cluster Admin
discover_tool_input_values 🖥️Поиск точных входных значений, необходимых другим инструментам (например, всех имен метрик для get_cluster_metrics). Работает автономно

Обнаружение модели данных и схемы

ИнструментОписание
get_buckets_in_clusterСписок всех бакетов в кластере
get_scopes_in_bucketСписок всех областей в бакете
get_collections_in_scopeСписок всех коллекций в области (требуется служба Query)
get_scopes_and_collections_in_bucketСписок всех областей и коллекций в бакете
get_schema_for_collectionОпределение структуры коллекции
create_scope ✏️Создание области в бакете (Server 7.6+ и Capella)
create_collection ✏️Создание коллекции в существующей области (Server 7.6+ и Capella)
delete_scope ✏️Удаление области и всех ее коллекций — без возможности восстановления
delete_collection ✏️Удаление коллекции и всех ее документов — без возможности восстановления

Операции с документами (KV)

ИнструментОписание
get_document_by_idПолучение документа по идентификатору
lookup_subdocumentЧтение заданных путей, проверка существования или подсчет без загрузки всего документа
upsert_document_by_id ✏️Вставка или обновление документа по идентификатору
insert_document_by_id ✏️Вставка нового документа (завершится ошибкой, если документ уже существует)
replace_document_by_id ✏️Замена существующего документа (завершится ошибкой, если документ не существует)
delete_document_by_id ✏️Удаление документа по идентификатору
mutate_subdocument ✏️Изменение путей в существующем документе (вставка или обновление, вставка, замена, удаление, операции с массивами, счетчики)

Запросы и индексирование

ИнструментОписание
run_sql_plus_plus_queryВыполнение запроса SQL++ в пределах бакета и области — используйте имена коллекций напрямую (SELECT * FROM users). В режиме только для чтения операторы, изменяющие данные, блокируются
explain_sql_plus_plus_queryСоздание и оценка плана EXPLAIN: метаданные, извлеченный план и результаты анализа
get_index_advisor_recommendationsРекомендации Index Advisor для запроса SQL++
list_indexesСписок индексов с определениями, фильтруемый по бакету, области, коллекции или имени; отмечает векторные индексы (is_vector, vector_type)
get_index_stats 🖥️Размер каждого индекса, фрагментация, нагрузка сканирования и задержка по узлам — помогает выявить перегруженные и неиспользуемые индексы
create_query_index ✏️Создание скалярного индекса GSI, векторного индекса Hyperscale или составного векторного индекса (index_type). По умолчанию создание откладывается — затем выполните build_index
create_index ✏️Устарел — используйте create_query_index. Удален в версии 2.0
build_index ✏️Построение всех отложенных индексов коллекции
drop_index ✏️Удаление индекса GSI (скалярного или векторного)

Полнотекстовый поиск (FTS)

Требуются Couchbase Server 7.6+ и служба Search. Поддерживаются индексы на уровне области и кластера (устаревшие): для уровня области передайте вместе bucket_name и scope_name, либо не указывайте ни один из них.

ИнструментОписание
list_search_indexesСписок индексов Search — на уровне кластера, бакета или области
get_search_index_definitionПолное определение одного индекса Search (сопоставления, анализаторы, параметры плана)
run_searchВыполнение любого запроса FTS без векторов из исходного тела JSON; explain=true возвращает план выполнения
upsert_search_index ✏️Создание или обновление индекса Search, включая сопоставления векторных полей. Обновления запускают полную перестройку — передайте текущее значение uuid, чтобы избежать перезаписи параллельных изменений
drop_search_index ✏️Удаление индекса Search — без возможности восстановления

Векторный поиск

Оба инструмента создают векторные представления обычного текста запроса с помощью модели, настроенной в разделе Поставщики векторных представлений. Доступно в самостоятельно управляемом 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 (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Запросы, не использующие покрывающий индекс
get_queries_not_selectiveЗапросы, сканирование которых — вторичного индекса, первичного индекса или последовательное — возвращает намного больше документов, чем итоговый результат

Состояние службы Query 🖥️

Эти инструменты при каждом запросе обращаются к собственной административной REST API службы Query на каждом узле запросов.

ИнструментОписание
get_cluster_query_vitalsСостояние обработчика запросов: частота запросов, активные запросы и запросы в очереди, память, GC, время работы. Требуется ro_admin
get_active_queriesЗапросы, выполняющиеся прямо сейчас на всех узлах запросов. Требуется ro_admin
delete_active_query ✏️Отмена выполняющегося запроса по идентификатору запроса. Требуется Full Admin или Cluster Admin

Инструменты, автоматически отключаемые в Capella

Инструменты 🖥️ обращаются к Couchbase через административные REST-конечные точки, которые Capella не предоставляет (единственное исключение — discover_tool_input_values, оно не включается, поскольку обслуживает только инструмент, которому нужны эти конечные точки). Если все узлы в CB_CONNECTION_STRING заканчиваются на .cloud.couchbase.com, сервер не регистрирует эти инструменты и указывает их вместе с вашими собственными отключёнными инструментами в get_server_configuration_status и журнале запуска. Инструменты на основе SDK, такие как get_cluster_health_and_services и get_client_connectivity_report, остаются доступными.

ИнструментНеобходимая конечная точка
get_cluster_metricsREST API управления (/pools/default/stats/range)
get_cluster_tasksREST API управления (/pools/default/tasks)
get_bucket_configREST API управления (/pools/default/buckets[/<name>])
get_cluster_health_snapshotREST API управления, а также конечные точки отдельных узлов
get_cluster_system_eventsREST API управления (/events)
get_index_statsREST API службы Index (значение /api/v1/stats каждого индексатора)
get_cluster_query_vitalsREST API службы Query (/admin/vitals)
get_active_queriesREST API службы Query (/admin/active_requests)
delete_active_queryREST API службы Query (DELETE /admin/active_requests/{id})
discover_tool_input_valuesНе требуется (работает автономно), но обслуживает только get_cluster_metrics, которого нет в Capella

Поставщики векторных представлений

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-адрес вашего развёртывания (например, https://<id>.ai.couchbase.com) из раздела AI Data Plane > Models в Capella
openaiCB_MCP_EMBEDDING_MODEL_API_KEY, CB_MCP_EMBEDDING_MODELCB_MCP_EMBEDDING_MODEL_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Модели векторных представлений Amazon Titan (например, amazon.titan-embed-text-v2:0) — поставщик отправляет запрос в формате inputText для Titan, поэтому другие модели векторных представлений Bedrock, например Cohere Embed, пока не поддерживаются. Не указывайте учётные данные, чтобы использовать цепочку AWS по умолчанию. Требуется дополнительный параметр: 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, управление областями/коллекциями, индексами и индексами 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 при количестве рабочих процессов > 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Базовый путь для файлов журналов по уровням (используется только при включенном приемнике file)mcp_server.log
CB_MCP_LOG_ROTATION_MAX_SIZE_MB--log-rotation-max-size-mbГлобальный максимальный размер в МБ для каждого файла журнала до его ротации; применяется ко всем уровням, если не переопределен. 0 — или недопустимое значение, например отрицательное, nan или inf, — считается недопустимым, и используется значение по умолчанию с предупреждением при запуске1 (1 МБ)
CB_MCP_LOG_MAX_BYTES--log-max-bytesУстарело — используйте CB_MCP_LOG_ROTATION_MAX_SIZE_MB (МБ). Глобальный размер ротации в байтах; по-прежнему поддерживается для обратной совместимости и игнорируется, если также задано CB_MCP_LOG_ROTATION_MAX_SIZE_MBНе задано
CB_MCP_LOG_ERROR_ROTATION_MAX_SIZE_MB--log-error-rotation-max-size-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Размер ротации в МБ для файла журнала 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Размер ротации в МБ для файла журнала 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Размер ротации в МБ для файла журнала 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. Включает OAuth, если задана вместе с issuer и audience (см. Авторизация OAuth 2.1)Нет
CB_MCP_OAUTH_JWT_ISSUER--oauth-issuerОжидаемое утверждение JWT iss. Необходимо для включения OAuthНет
CB_MCP_OAUTH_JWT_AUDIENCE--oauth-audienceОжидаемое утверждение 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-urlОбщедоступный базовый URL этого сервера. Если задан, публикует метаданные защищенного ресурса RFC 9728, чтобы клиенты с поддержкой PRM могли обнаруживать IdPНет
CB_MCP_OAUTH_SCOPE_READ_LABEL--oauth-scope-read-labelПереопределить метку области OAuth, трактуемую как доступ «только для чтения» (публикуется в PRM и сопоставляется с утверждением scope/scp токена). Используйте, если ваш IdP не может выдавать каноническую формуcouchbase-mcp:read
CB_MCP_OAUTH_SCOPE_WRITE_LABEL--oauth-scope-write-labelПереопределить метку области OAuth, трактуемую как доступ «для записи»; семантика такая же, как у метки доступа только для чтенияcouchbase-mcp:write
CB_MCP_AUDIT_LOG_ENABLED--audit-log-enabledВключить журнал аудита — отдельный приемник, отличный от операционных журналов CB_MCP_LOG_*, со стабильной схемой и собственным сроком хранения (см. Аудит)false
CB_MCP_AUDIT_LOG_SINKS--audit-log-sinksРазделенные запятыми назначения аудита: console, file или оба варианта. console записывает в stderr — никогда не в stdout, где при использовании stdio передается протокол JSON-RPCconsole
CB_MCP_AUDIT_LOG_FILE_PATH--audit-log-file-pathПуть к файлу журнала аудита. Обязателен, если среди приемников указан file; имя хоста и идентификатор процесса вставляются перед расширением (audit.log → audit.<host>.<pid>.log)Нет
CB_MCP_AUDIT_LOG_ROTATION_MAX_SIZE_MB--audit-log-rotation-max-size-mbМаксимальный размер в МБ, которого может достичь активный файл аудита до ротации. 0 отключает ротацию по размеру10 (10 МБ)
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Поставщик эмбеддингов для run_vector_query / run_vector_search: один из capella, openai, cohere, voyage, bedrock. Если не задан, этап создания эмбеддингов для обоих инструментов отключен до настройки — см. Настройка поставщика эмбеддинговНет
CB_MCP_EMBEDDING_MODEL--embedding-modelИмя/идентификатор модели для настроенного поставщика эмбеддинговНет
CB_MCP_EMBEDDING_MODEL_API_KEY--embedding-model-api-keyКлюч API для настроенного поставщика. Не используется bedrock (вместо него используется цепочка учетных данных AWS / 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; только для поставщика bedrock. Не указывайте, чтобы использовать цепочку учетных данных AWS по умолчаниюНет
CB_MCP_EMBEDDING_MODEL_AWS_SECRET_ACCESS_KEY--embedding-model-aws-secret-access-keyСекретный ключ доступа AWS; только для поставщика bedrockНет
CB_MCP_EMBEDDING_MODEL_AWS_REGION--embedding-model-aws-regionРегион AWS; только для поставщика bedrock. Если не задан, используется механизм определения региона 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-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Тайм-аут в секундах для каждого асинхронного запроса: запуск запроса, проверка его состояния, получение результатов, удаление результатов и отмена. Для получения результатов он охватывает всю загрузку, поэтому чтение результата дольше этого времени завершится ошибкой. Увеличьте значение для больших результатов или медленных соединений. Положительное целое число, по умолчанию 30, максимум 600. Большие значения ограничиваются 600 с предупреждением; для любого другого недопустимого значения выводится предупреждение и используется 30

Применяются все общие настройки, но есть следующие отличия от операционного сервера:

  • Порт по умолчанию — 8001, а файл журнала по умолчанию — mcp_server_operational_insights.log, поэтому оба сервера могут работать одновременно.
  • Поддерживается только один рабочий процесс (CB_MCP_WORKERS=1), поскольку дескрипторы асинхронных запросов хранятся в памяти процесса.
  • У него нет параметров 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Список областей в базе данных
operational_insights_get_collections_in_scopeСписок коллекций (наборов данных) в области
operational_insights_get_schema_for_collectionВывод схемы JSON коллекции путем выборки данных

Запросы и индексы

ИнструментОписание
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Проверка состояния асинхронного запроса; возвращает строки (или место назначения экспорта), когда они готовы
operational_insights_discard_async_query_resultsОсвобождение результатов завершенного асинхронного запроса
operational_insights_cancel_async_queryОстановка выполняющегося асинхронного запроса (разрешена в режиме только для чтения)
operational_insights_create_index ✏️Создание вторичного индекса через CREATE INDEX

Асинхронные запросы выполняются по схеме «запуск → проверка состояния → удаление или отмена»: 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. ..."
}
  • Неполное место назначения отклоняется, а строки не возвращаются молча.
  • Синхронный инструмент ожидает завершения всей загрузки; для больших экспортов предпочтителен асинхронный инструмент.
  • Экспорт заблокирован в режиме только для чтения (он записывает данные во внешнее хранилище), поэтому для него требуется 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). Сервер отказывается запускаться при такой комбинации. При работе за балансировщиком нагрузки для подтверждения нужны привязанные сеансы — см. раздел Балансировщики нагрузки.

Транспорты

ТранспортДля чего используетсяКонечная точка
stdio (по умолчанию)Один локальный клиент, запускающий сервер как дочерний процесс—
httpНесколько клиентов, использующих общий сервер; поддерживает OAuth, проверки работоспособности и рабочие процессы на операционном сервереhttp://<host>:<port>/mcp

Задайте транспорт с помощью CB_MCP_TRANSPORT, адрес привязки — с помощью 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"
    }
  }
}

Несколько рабочих процессов

Один процесс использует не более примерно одного ядра ЦП. --workers N (CB_MCP_WORKERS) запускает N процессов на одном хосте и порту; хорошей отправной точкой будет число доступных ядер. Рабочие процессы поддерживаются только операционным сервером. При использовании более одного рабочего процесса:

  • Требуется транспорт http, а сервер работает в режиме HTTP без сохранения состояния, поскольку запросы клиента могут попадать к разным рабочим процессам. Также можно задать --stateless-http=true для одного рабочего процесса, например, за балансировщиком нагрузки без привязанных сеансов.
  • Инструменты, требующие подтверждения использовать нельзя.
  • Каждый процесс записывает собственные файлы журналов с именами, содержащими имя хоста и идентификатор процесса (mcp_server.<host>.<pid>.info.log) — один набор для супервизора и по одному для каждого рабочего процесса.

Балансировщики нагрузки

Можно запустить несколько экземпляров сервера за балансировщиком нагрузки. Каждый экземпляр хранит сеансы MCP в собственной памяти, поэтому настройки балансировщика определяют, что будет работать:

Балансировщик нагрузкиНастройка сервераИнструменты, требующие подтверждения
Привязанные сеансы, маршрутизация по заголовку запроса Mcp-Session-IdОдин рабочий процесс, с сохранением состояния (по умолчанию)Поддерживаются
Без привязанных сеансов--stateless-http=trueНе поддерживаются — сервер отказывается запускаться, если они настроены
  • Без привязанных сеансов экземпляр с сохранением состояния отклоняет каждый запрос, сеанс которого был создан на другом экземпляре. В этом случае используйте режим без сохранения состояния.
  • Выполняйте маршрутизацию по заголовку Mcp-Session-Id, а не по файлам cookie. Многие клиенты MCP не сохраняют файлы cookie.
  • При перезапуске или переключении экземпляра его сеансы и все ожидающие запросы на подтверждение теряются. Клиент должен начать новый сеанс.
  • Асинхронные запросы Operational Insights хранят свои query_handle в памяти экземпляра, запустившего запрос, в том числе в режиме без сохранения состояния. Проверка состояния, удаление результатов или отмена запроса на другом экземпляре возвращает Unknown query_handle. Используйте эти инструменты с одним экземпляром или с привязанными сеансами, чтобы все вызовы попадали на экземпляр, запустивший запрос. Режим без сохранения состояния не отправляет Mcp-Session-Id, поэтому для привязки требуется другой ключ, например IP-адрес клиента.

Проверка работоспособности

В режиме HTTP GET /health возвращает {"status": "ok", "server": "<server>"} на порту MCP. Это проверка активности: она не подключается к кластеру (поэтому сбой кластера не приводит к перезапуску исправных контейнеров), не требует аутентификации даже при включенном OAuth и обслуживается каждым рабочим процессом. Примеры проверок см. в разделе 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 дополнительно публикует метаданные защищенного ресурса RFC 9728, чтобы клиенты могли обнаружить сервер авторизации.
  • Доступ определяется двумя областями действия в утверждении токена 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>'

Инструкции по настройке IdP см. в документации OAuth для операционного сервера и сервера Operational Insights.

Ведение журналов

По умолчанию каждый сервер записывает журналы в 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 устарел.
  • Снимок конфигурации — при использовании приемника file при каждом запуске в mcp_server_config.log.json записывается 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 (пользователь ОС при использовании stdio) или anonymous (HTTP без OAuth; при запуске выводится предупреждение).
  • Корреляция — cid объединяет все записи одного запроса и передаётся как SQL++ client_context_id, поэтому его можно точно сопоставить с clientContextId Couchbase Server. Идентификатор сеанса намеренно не используется.
  • События — фиксированный нумерованный каталог (жизненный цикл, инициализация, отклонение токена, отказ в доступе к области, блокировка операции записи, отклонённое/пропущенное подтверждение, а также пара событий чтения/записи для каждой категории инструментов). Исключения — query и search: каждое из них записывается как одно событие, а не как пара чтения/записи, поскольку для поверхностей, управляемых операторами и поиском, надёжно определить это различие невозможно. Векторные операции входят в эти две категории. Полный каталог поставляется в составе пакета как descriptor.json. Операционный сервер использует блок 0xF000 (61440), Operational Insights — 0x10000 (65536), а для основных событий оба используют общий блок 0xE000 (57344).
  • Фильтрация — CB_MCP_AUDIT_LOG_DISABLED_EVENTS подавляет события чтения по числовому идентификатору (например, 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.
  • Файлы для каждого процесса — в имя добавляются имя хоста и pid (audit.log → audit.<host>.<pid>.log), поэтому параллельные процессы никогда не используют один файл.
  • Хранение для каждого файла — CB_MCP_AUDIT_LOG_RETENTION_MAX_BACKUPS (по умолчанию 10) ограничивает число резервных копий одного файла. Каждый новый процесс создаёт новый файл, а старые файлы не удаляются, поэтому предусмотрите достаточный объём хранилища или удаляйте старые файлы audit.*.log*.
  • Продолжение работы при сбоях — если файл невозможно записать, сервер продолжает обслуживать запросы и подсчитывает потерянные записи; 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 (см. документацию Cursor по MCP) или воспользуйтесь ссылкой для установки в один клик Install in 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 (см. документацию Windsurf по MCP).
  2. Нажмите Add Server > Add custom server, вставьте конфигурацию и сохраните её.
  3. Обновите список серверов и убедитесь, что couchbase включён.
VS Code

В VS Code вместо ключа верхнего уровня mcpServers используется servers. Для рабочей области поместите конфигурацию в .vscode/mcp.json или запустите MCP: Open User Configuration, чтобы применить её ко всем рабочим областям (см. документацию VS Code по MCP):

{
  "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. Настройте контейнер с теми же переменными окружения, что и выше. Сведения о тегах, томах и примеры проверок работоспособности см. на странице Docker Hub (DOCKER.md).

Запуск по HTTP — обратите внимание: сервер должен привязываться к 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 запущен на хост-компьютере, используйте couchbase://host.docker.internal в качестве строки подключения (см. сетевое взаимодействие Docker). Используйте --network=<your_network>, чтобы подключиться к сети другого контейнера.
  • Для запуска сервера Operational Insights (порт 8001) добавьте operational-insights вместо operational.
Сборка образа из исходного кода
docker build -t mcp/couchbase-src .

./build.sh [image-name] выполняет сборку с теми же аргументами, что и CI: задаёт аргументы сборки 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 убедитесь, что кластер разрешает подключения с компьютера, на котором запущен сервер.
  • Убедитесь, что пользователь базы данных имеет доступ хотя бы к одному бакету.
  • Если клиент не может найти uv/uvx, укажите абсолютный путь в command.
  • При запуске из исходного кода проверьте путь к репозиторию в конфигурации и выполните uv sync после получения обновлений.
  • Вызовите get_server_configuration_status, чтобы увидеть фактически разрешённую сервером конфигурацию, и проверьте журналы клиента (см. раздел Настройка клиента).

Часто задаваемые вопросы

Как подключить Claude Desktop к Couchbase? Добавьте конфигурацию из краткого руководства по запуску в claude_desktop_config.json и перезапустите Claude Desktop — см. раздел Настройка клиента.

Можно ли использовать это с Couchbase Capella? Да, с операционным сервером: одна и та же конфигурация подходит для Capella и кластеров под самостоятельным управлением, хотя некоторые инструменты администрирования доступны только в кластерах под самостоятельным управлением (см. раздел Инструменты). Сервер Operational Insights предназначен только для кластеров Operational Insights под самостоятельным управлением.

Безопасно ли разрешать ИИ-агенту записывать данные в мою базу данных? По умолчанию — нет: инструменты записи не загружаются, а изменяющие данные 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. См. Политику поддержки.

Участие в разработке

Мы приветствуем вклад в проект — исправления ошибок, новые функции и документацию. Чтобы сообщить об ошибке или попросить помощи, создайте issue на GitHub.

Сведения о настройке среды разработки, линтинге, тестировании, структуре проекта и рабочем процессе см. в CONTRIBUTING.md. Для начала:

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. Способ получения помощи зависит от того, как вы его используете:

  • Использование сообществом — сообщайте об ошибках, задавайте вопросы и запрашивайте новые функции, создавая issue на GitHub. Инженеры Couchbase следят за репозиторием и отвечают по мере возможности; гарантированные сроки ответа не предусмотрены. Портал поддержки Couchbase не оказывает помощь при использовании сообществом.
  • Корпоративная поддержка — доступна при приобретении лицензии на Couchbase AI Data Plane, которая также распространяется на Couchbase Agent Memory и Couchbase Agent Catalog. Лицензированные клиенты получают помощь через привычные каналы поддержки Couchbase.

Спасибо, что используете проект и вносите в него свой вклад!