Подключение MCP-клиента к кластеру OpenSearch

Статья создана

Обновлена 27 мая 2026 г.

Необходимые платные ресурсы
Перед началом работы
Включите MCP-сервер
Зарегистрируйте инструменты
Сформируйте Basic-токен
Добавьте MCP-сервер в конфигурацию клиента
Проверьте подключение
Удалите созданные ресурсы

В этом практическом руководстве вы настроите подключение MCP-клиента к кластеру OpenSearch: включите встроенный MCP-сервер, зарегистрируете инструменты и добавите сервер в конфигурацию клиента.

Примечание

MCP-сервер в OpenSearch доступен начиная с версии 3.0.

Чтобы настроить подключение:

Если созданные ресурсы вам больше не нужны, удалите их.

Необходимые платные ресурсы

В стоимость поддержки описываемого решения входят:

Кластер Managed Service for OpenSearch: использование вычислительных ресурсов, объем хранилища и резервных копий (см. тарифы Managed Service for OpenSearch).
Публичные IP-адреса, если для хостов кластера включен публичный доступ (см. тарифы Yandex Virtual Private Cloud).

Перед началом работы

Подготовьте инфраструктуру:
Вручную

С помощью Terraform
1. Создайте кластер Managed Service for OpenSearch нужной вам конфигурации с публичным доступом к любой группе хостов.
  
  Примечание
  
  Публичный доступ к хостам кластера нужен, если вы планируете подключаться к кластеру через интернет. Этот вариант подключения более простой, и его рекомендуется использовать для прохождения руководства. К хостам без публичного доступа тоже можно подключиться, но только с виртуальных машин Yandex Cloud, расположенных в той же облачной сети, что и кластер.
2. Если вы используете группы безопасности в кластере, убедитесь, что они настроены правильно и допускают подключение к кластеру Managed Service for OpenSearch.
1. Если у вас еще нет Terraform, установите его.
2. Получите данные для аутентификации. Вы можете добавить их в переменные окружения или указать далее в файле с настройками провайдера.
3. Настройте и инициализируйте провайдер. Чтобы не создавать конфигурационный файл с настройками провайдера вручную, скачайте его.
4. Поместите конфигурационный файл в отдельную рабочую директорию и укажите значения параметров. Если данные для аутентификации не были добавлены в переменные окружения, укажите их в конфигурационном файле.
5. Скачайте в ту же рабочую директорию файл конфигурации opensearch-mcp.tf. В файле описаны:
  - сеть;
  - подсеть;
  - группа безопасности и правила, необходимые для подключения к кластеру Managed Service for OpenSearch;
  - кластер Managed Service for OpenSearch.
6. Укажите в файле opensearch-mcp.tf переменные:
  - version — версия OpenSearch.
  - admin_password — пароль администратора OpenSearch.
7. Проверьте корректность файлов конфигурации Terraform с помощью команды:
  terraform validate
  Если в файлах конфигурации есть ошибки, Terraform на них укажет.
8. Создайте необходимую инфраструктуру:
  1. Выполните команду для просмотра планируемых изменений:
    
    terraform plan
    
    Если конфигурации ресурсов описаны верно, в терминале отобразится список изменяемых ресурсов и их параметров. Это проверочный этап: ресурсы не будут изменены.
  2. Если вас устраивают планируемые изменения, внесите их:
    
    Выполните команду:
    
    terraform apply
    
    Подтвердите изменение ресурсов.
    
    Дождитесь завершения операции.
  В указанном каталоге будут созданы все требуемые ресурсы. Проверить появление ресурсов и их настройки можно в консоли управления.
Установите SSL-сертификат.

Проверьте подключение к кластеру с помощью утилиты cURL:

curl \
    --user admin:<пароль> \
    --cacert ~/.opensearch/root.crt \
    --request GET 'https://<FQDN_хоста_OpenSearch_с_публичным_доступом>:9200/'

FQDN хоста можно получить со списком хостов в кластере.

При успешном подключении будет выведено сообщение вида:

{
  "name" : "....mdb.yandexcloud.net",
  "cluster_name" : "...",
  "cluster_uuid" : "...",
  "version" : {
  "distribution" : "opensearch",
  ...
  },
  "tagline" : "The OpenSearch Project: https://opensearch.org/"
}

Создайте отдельного пользователя для MCP-клиента.

Внутреннего пользователя можно создать либо через OpenSearch Dashboards, либо через Security REST API.
OpenSearch Dashboards

REST API
1. Подключитесь к OpenSearch Dashboards от имени admin.
2. В меню слева выберите OpenSearch Plugins → Security.
3. На панели слева выберите Internal users и нажмите Create internal user.
4. Укажите имя пользователя и пароль, например mcp-client.
5. Нажмите Submit.
6. Назначьте пользователю роль ml_full_access:
  1. На панели слева выберите Roles.
  2. Откройте роль ml_full_access и перейдите на вкладку Mapped users.
  3. Нажмите Manage mapping, добавьте пользователя mcp-client и нажмите Map.
Создайте внутреннего пользователя и назначьте ему роль ml_full_access, в данном примере создается пользователь mcp-client:
```
curl \
  --cacert ~/.opensearch/root.crt \
  --user admin:<пароль> \
  --request PUT \
  --header "Content-Type: application/json" \
  "https://<адрес_хоста_OpenSearch_с_публичным_доступом>:9200/_plugins/_security/api/internalusers/mcp-client" \
  --data '{
    "password": "<пароль_пользователя>",
    "opendistro_security_roles": [
      "ml_full_access"
    ]
  }'
```
При необходимости проверьте, что пользователь создан:
```
curl \
  --cacert ~/.opensearch/root.crt \
  --user admin:<пароль> \
  --request GET \
  "https://<адрес_хоста_OpenSearch_с_публичным_доступом>:9200/_plugins/_security/api/internalusers/mcp-client"
```
Примечание

Если вы планируете регистрировать другие инструменты, создайте роль с нужными правами. Подробнее о настройке прав в документации OpenSearch по пользователям и ролям и списке поддерживаемых инструментов.
Для шагов, где изменяются настройки кластера, создаются роли и пользователи или регистрируются инструменты, используйте учетную запись admin или другого пользователя с достаточными административными правами. Для подключения MCP-клиента и формирования Basic-токена используйте учетные данные пользователя mcp-client.

Важно

MCP-клиент получает те же права, что и пользователь, чьи учетные данные передаются в заголовке Authorization. Не используйте в конфигурации клиента учетную запись admin, если достаточно отдельного пользователя с ограниченным набором прав.

Включите MCP-сервер

Выполните запрос к API кластера:

curl \
  --cacert ~/.opensearch/root.crt \
  --user admin:<пароль> \
  --request PUT \
  --header "Content-Type: application/json" \
  "https://<адрес_хоста_OpenSearch_с_публичным_доступом>:9200/_cluster/settings" \
  --data '{
    "persistent": {
      "plugins.ml_commons.mcp_server_enabled": true
    }
  }'

Зарегистрируйте инструменты

После включения MCP-сервера зарегистрируйте инструменты, которые будут доступны MCP-клиенту.

Полный список встроенных инструментов приведен в документации OpenSearch.

Формат запроса на регистрацию описан в документации OpenSearch.

Например, можно зарегистрировать базовый набор инструментов для просмотра индексов, схемы и поиска:

curl \
  --cacert ~/.opensearch/root.crt \
  --user mcp-client:<пароль> \
  --request POST \
  --header "Content-Type: application/json" \
  "https://<адрес_хоста_OpenSearch_с_публичным_доступом>:9200/_plugins/_ml/mcp/tools/_register" \
  --data '{
    "tools": [
      {
        "name": "ListIndexTool",
        "type": "ListIndexTool",
        "description": "Возвращает список индексов кластера",
        "attributes": {
          "input_schema": {
            "type": "object",
            "properties": {
              "indices": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Список индексов. Укажите [] для всех индексов кластера"
              }
            },
            "additionalProperties": false
          }
        }
      },
      {
        "name": "IndexMappingTool",
        "type": "IndexMappingTool",
        "description": "Возвращает mappings и settings для указанного индекса",
        "attributes": {
          "input_schema": {
            "type": "object",
            "properties": {
              "index": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Список индексов"
              }
            },
            "required": [
              "index"
            ],
            "additionalProperties": false
          }
        }
      },
      {
        "name": "SearchIndexTool",
        "type": "SearchIndexTool",
        "description": "Выполняет поиск по индексу с помощью OpenSearch DSL",
        "attributes": {
          "input_schema": {
            "type": "object",
            "properties": {
              "index": {
                "type": "string"
              },
              "query": {
                "type": "string"
              }
            },
            "required": [
              "index",
              "query"
            ],
            "additionalProperties": false
          }
        }
      }
    ]
  }'

Чтобы проверить, что инструменты зарегистрированы, выполните запрос:

curl \
  --cacert ~/.opensearch/root.crt \
  --user mcp-client:<пароль> \
  --request GET \
  "https://<адрес_хоста_OpenSearch_с_публичным_доступом>:9200/_plugins/_ml/mcp/tools/_list"

Если регистрация прошла успешно, в ответе вернется массив tools.

Сформируйте Basic-токен

Если MCP-клиент передает Basic-аутентификацию в заголовке, сформируйте токен из имени и пароля созданного пользователя:

echo -n 'mcp-client:<пароль>' | base64

Используйте полученное значение как <base64-basic-token>.

Добавьте MCP-сервер в конфигурацию клиента

Во всех примерах ниже используется адрес:

https://<адрес_хоста_OpenSearch_с_публичным_доступом>:9200/_plugins/_ml/mcp

Если клиент не позволяет отдельно указать путь к CA-сертификату, заранее установите SSL-сертификат в системное хранилище сертификатов.

OpenCode

Claude Code

FastMCP

VS Code

Добавьте сервер в конфигурацию OpenCode:

{
  "opensearch": {
    "enabled": true,
    "type": "remote",
    "url": "https://<адрес_хоста_OpenSearch_с_публичным_доступом>:9200/_plugins/_ml/mcp",
    "headers": {
      "Authorization": "Basic <base64-basic-token>"
    }
  }
}

Добавьте MCP-сервер командой:

claude mcp add --transport http opensearch \
  "https://<адрес_хоста_OpenSearch_с_публичным_доступом>:9200/_plugins/_ml/mcp" \
  --header "Authorization: Basic <base64-basic-token>"

Установите пакет:

pip3 install fastmcp

Пример подключения:

import asyncio

import httpx
from fastmcp import Client

auth = httpx.BasicAuth(
    username="mcp-client",
    password="<пароль>",
)


async def main():
    async with Client(
        "https://<адрес_хоста_OpenSearch_с_публичным_доступом>:9200/_plugins/_ml/mcp",
        auth=auth,
        verify="/path/to/root.crt",
    ) as client:
        for tool in await client.list_tools():
            print(tool.name)

        result = await client.call_tool("ListIndexTool", {})
        print(result)


asyncio.run(main())

На данный момент (до версии OpenSearch 3.7) наблюдаются проблемы с подключением к MCP-серверу напрямую из VS Code. Вы можете самостоятельно настроить MCP Proxy для подключения к MCP-серверу из VS Code.

После сохранения конфигурации перезапустите MCP-клиент или обновите его настройки, если это требуется в вашем приложении.

Проверьте подключение

Убедитесь, что клиент подключился к MCP-серверу без ошибок авторизации и TLS.
Проверьте, что клиент распознает зарегистрированные инструменты, например ListIndexTool, IndexMappingTool и SearchIndexTool.
Выполните тестовый вызов ListIndexTool и убедитесь, что в ответе возвращается список индексов кластера.

Например, для FastMCP достаточно запустить скрипт из предыдущего шага. Если подключение настроено правильно, скрипт:

выведет список доступных инструментов;
выполнит вызов ListIndexTool;
вернет информацию об индексах кластера.

Если вы используете IDE или локальный агент, откройте список MCP-серверов или инструментов в интерфейсе клиента и убедитесь, что сервер opensearch активен.

Удалите созданные ресурсы

Некоторые ресурсы платные. Чтобы за них не списывалась плата, удалите ресурсы, которые вы больше не будете использовать:

Вручную

С помощью Terraform

Удалите кластер Managed Service for OpenSearch.

В терминале перейдите в директорию с планом инфраструктуры.

Важно

Убедитесь, что в директории нет Terraform-манифестов с ресурсами, которые вы хотите сохранить. Terraform удаляет все ресурсы, которые были созданы с помощью манифестов в текущей директории.
Удалите ресурсы:
1. Выполните команду:
```
terraform destroy
```
2. Подтвердите удаление ресурсов и дождитесь завершения операции.
Все ресурсы, которые были описаны в Terraform-манифестах, будут удалены.

Подключение MCP-клиента к кластеру OpenSearch

Необходимые платные ресурсыНеобходимые платные ресурсы

Перед началом работыПеред началом работы

Включите MCP-серверВключите MCP-сервер

Зарегистрируйте инструментыЗарегистрируйте инструменты

Сформируйте Basic-токенСформируйте Basic-токен

Добавьте MCP-сервер в конфигурацию клиентаДобавьте MCP-сервер в конфигурацию клиента

Проверьте подключениеПроверьте подключение

Удалите созданные ресурсыУдалите созданные ресурсы

Была ли статья полезна?