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.couchbase.com/mcp-server
Содержание
- Зачем нужен MCP-сервер Couchbase
- Выбор сервера
- Операционный сервер
- Сервер Operational Insights
- Общие настройки
- Настройка клиента
- Docker
- Устранение неполадок
- Часто задаваемые вопросы
- Участие в разработке
- Данные об использовании, риски LLM и политика поддержки
Зачем нужен 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 по умолчанию | 8000 | 8001 |
| Файл журнала по умолчанию | mcp_server.log | mcp_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_metrics | REST API управления (/pools/default/stats/range) |
get_cluster_tasks | REST API управления (/pools/default/tasks) |
get_bucket_config | REST API управления (/pools/default/buckets[/<name>]) |
get_cluster_health_snapshot | REST API управления, а также конечные точки отдельных узлов |
get_cluster_system_events | REST API управления (/events) |
get_index_stats | REST API службы Index (значение /api/v1/stats каждого индексатора) |
get_cluster_query_vitals | REST API службы Query (/admin/vitals) |
get_active_queries | REST API службы Query (/admin/active_requests) |
delete_active_query | REST 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 | Обязательно | Необязательно | Примечания |
|---|---|---|---|
capella | CB_MCP_EMBEDDING_MODEL_API_KEY, CB_MCP_EMBEDDING_MODEL, CB_MCP_EMBEDDING_MODEL_ENDPOINT | — | Capella Model Service. CB_MCP_EMBEDDING_MODEL_ENDPOINT — это URL-адрес вашего развёртывания (например, https://<id>.ai.couchbase.com) из раздела AI Data Plane > Models в Capella |
openai | CB_MCP_EMBEDDING_MODEL_API_KEY, CB_MCP_EMBEDDING_MODEL | CB_MCP_EMBEDDING_MODEL_ENDPOINT | Укажите конечную точку, чтобы использовать локальный сервер, совместимый с OpenAI (Ollama, vLLM, LM Studio) |
cohere | CB_MCP_EMBEDDING_MODEL_API_KEY, CB_MCP_EMBEDDING_MODEL | CB_MCP_EMBEDDING_MODEL_ENDPOINT | |
voyage | CB_MCP_EMBEDDING_MODEL_API_KEY, CB_MCP_EMBEDDING_MODEL | CB_MCP_EMBEDDING_MODEL_ENDPOINT | |
bedrock | CB_MCP_EMBEDDING_MODEL | CB_MCP_EMBEDDING_MODEL_AWS_ACCESS_KEY_ID, CB_MCP_EMBEDDING_MODEL_AWS_SECRET_ACCESS_KEY, CB_MCP_EMBEDDING_MODEL_AWS_REGION | Модели векторных представлений 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, http | stdio |
CB_MCP_HOST | --host | Хост для режима транспорта HTTP | 127.0.0.1 |
CB_MCP_PORT | --port | Порт для режима транспорта HTTP | 8000 |
CB_MCP_WORKERS | --workers | Количество рабочих процессов сервера для транспорта http. Значения больше 1 запускают режим HTTP без состояния (см. Несколько рабочих процессов) | 1 |
CB_MCP_STATELESS_HTTP | --stateless-http | Обрабатывать каждый HTTP-запрос без состояния сеанса. Учитывается только с http; нельзя использовать вместе с инструментами, требующими подтверждения (см. Несколько рабочих процессов) | true при количестве рабочих процессов > 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/512 | RS256 |
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-RPC | console |
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-string | URL конечной точки (HTTP/HTTPS). Обязательно |
CB_OPERATIONAL_INSIGHTS_USERNAME | --username | Имя пользователя |
CB_OPERATIONAL_INSIGHTS_PASSWORD | --password | Пароль |
CB_OPERATIONAL_INSIGHTS_CA_CERT_PATH | --ca-cert-path | Корневой сертификат (PEM) для самоподписанного/недоверенного сертификата сервера |
CB_OPERATIONAL_INSIGHTS_CLIENT_CERT_PATH | --client-cert-path | Сертификат клиента для mTLS — PEM (с ключом) или пакет PKCS#12 (.p12/.pfx, без ключа). Требуется URL https://; переопределяет имя пользователя/пароль |
CB_OPERATIONAL_INSIGHTS_CLIENT_KEY_PATH | --client-key-path | Закрытый ключ (PEM) сертификата клиента. Не задавайте для PKCS#12 |
CB_OPERATIONAL_INSIGHTS_CLIENT_CERT_PASSWORD | --client-cert-password | Пароль для зашифрованного ключа или пакета PKCS#12 |
CB_MCP_OPERATIONAL_INSIGHTS_QUERY_RESULT_MAX_SIZE | --operational-insights-query-result-max-size | Максимальный размер результата запроса в байтах. Если не задан, ограничений нет. При заданном значении чтение останавливается по достижении лимита, а в ответе указывается truncated: true; строка, превышающая лимит, не возвращается. Значения выше 4 MiB (4194304) ограничиваются 4 MiB; при запуске в stderr выводится предупреждение |
CB_MCP_OPERATIONAL_INSIGHTS_ASYNC_QUERY_RESULT_TIMEOUT | --operational-insights-async-query-result-timeout | Тайм-аут в секундах для каждого асинхронного запроса: запуск запроса, проверка его состояния, получение результатов, удаление результатов и отмена. Для получения результатов он охватывает всю загрузку, поэтому чтение результата дольше этого времени завершится ошибкой. Увеличьте значение для больших результатов или медленных соединений. Положительное целое число, по умолчанию 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, поэтому его можно точно сопоставить сclientContextIdCouchbase 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
- Откройте файл конфигурации (см. краткое руководство по MCP):
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
- macOS:
- Добавьте сервер в раздел
mcpServersи перезапустите Claude Desktop.
Журналы: macOS ~/Library/Logs/Claude, Windows %APPDATA%\Claude\Logs. См. руководство по устранению неполадок MCP.
Cursor
- Перейдите в Cursor Settings > Tools & Integrations > MCP Tools (см. документацию Cursor по MCP) или воспользуйтесь ссылкой для установки в один клик Install in Cursor — затем замените строку подключения и учётные данные-заполнители.
- Добавьте конфигурацию в раздел
mcpServersи сохраните её. - Обновите список MCP-серверов и убедитесь, что
couchbaseвключён.
Журналы: на нижней панели откройте Output и выберите Cursor MCP.
Windsurf Editor
- Откройте Command Palette > Windsurf MCP Configuration Panel или Windsurf Settings > Advanced > Cascade > Model Context Protocol (MCP) Servers (см. документацию Windsurf по MCP).
- Нажмите Add Server > Add custom server, вставьте конфигурацию и сохраните её.
- Обновите список серверов и убедитесь, что
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
- Установите плагин AI Assistant или Junie.
- Перейдите в Settings > Tools > AI Assistant (or Junie) > MCP Server, нажмите +, добавьте конфигурацию и нажмите Apply.
- Наведите указатель на состояние сервера, чтобы увидеть его инструменты.
Журналы: Help > Show Log in Finder (Explorer) > mcp > couchbase.
Docker
Готовые образы публикуются на Docker Hub под именем couchbase/mcp-server; сервер также представлен в каталоге Docker MCP. Настройте контейнер с теми же переменными окружения, что и выше. Сведения о тегах, томах и примеры проверок работоспособности см. на странице 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.
Спасибо, что используете проект и вносите в него свой вклад!