Сервер MCP

Где найти в портале: в разделе API reference › Tools (https://<your-domain>/apidoc) представлены эндпоинт и примеры для клиентов; ключи создаются в API keys (/api-keys). В панели администратора настроек нет: эндпоинт встроен в панель.

Назначение

Model Context Protocol (MCP) позволяет AI-ассистенту вызывать инструменты. NexCMP предоставляет эндпоинт MCP по адресу https://<your-domain>/mcp. Каждая публичная операция API становится инструментом (vm_list, vm_start, billing_wallet, ...), поэтому клиент может спросить ассистента: «какие из моих VM запущены?» или «останови staging VM». Ассистент действует исключительно с собственным API-ключом и правами клиента.

Настройка самого NexCMP с помощью AI?

На этой странице описан клиентский эндпоинт MCP (/mcp). Чтобы разрешить AI-ассистенту настраивать панель от имени администратора, см. Configure with AI (эндпоинт /mcp/admin, ключи администратора ak_).

Требования

Параметр	Требование
Сервер	Устанавливать ничего не нужно: эндпоинт обслуживается панелью и доступен везде, где доступна сама панель. Ваш обратный прокси должен перенаправлять `/mcp` на панель.
Клиент	API-ключ (`vk_...`) с областями видимости (scopes), необходимыми ассистенту.
Клиент	Клиент MCP с поддержкой транспорта Streamable HTTP и пользовательского заголовка `Authorization`: Claude Code, Claude Desktop (через мост `mcp-remote`), Cursor, VS Code с режимом Copilot agent mode и аналогичные.
Версии протокола	2025-11-25, 2025-06-18 и 2025-03-26.

Подготовка инфраструктуры

Ничего, кроме проверки того, что https://<your-domain>/mcp не заблокирован межсетевым экраном или правилом прокси. Браузерный клиент MCP из другого источника (origin) отклоняется, если этот origin не разрешен; клиенты командной строки и десктопные клиенты не отправляют заголовок Origin и работают как есть.

Подключение (со стороны клиента)

Создайте API-ключ в портале (API keys › Create key) только с теми областями видимости (scopes), которые требуются ассистенту, коротким сроком действия и, по возможности, ограничением по IP.

Добавьте сервер в свой клиент. Замените cloud.example.com и ключ.

Claude Code

bash

claude mcp add --transport http cloud https://cloud.example.com/mcp \
  --header "Authorization: Bearer vk_XXXX"

Cursor (~/.cursor/mcp.json или .cursor/mcp.json; задайте CLOUD_API_KEY в окружении, из которого запускается Cursor):

json

{
  "mcpServers": {
    "cloud": {
      "url": "https://cloud.example.com/mcp",
      "headers": { "Authorization": "Bearer ${env:CLOUD_API_KEY}" }
    }
  }
}

Claude Desktop (требуется Node.js 18+; claude_desktop_config.json), через мост mcp-remote:

json

{
  "mcpServers": {
    "cloud": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://cloud.example.com/mcp", "--header", "Authorization:${CLOUD_AUTH_HEADER}"],
      "env": { "CLOUD_AUTH_HEADER": "Bearer vk_XXXX" }
    }
  }
}

Укажите заголовок без пробела после двоеточия и поместите значение целиком в переменную окружения, как показано выше.

Перезапустите клиент и попросите его вывести список доступных инструментов.

Проверка подключения без клиента:

bash

curl -s https://cloud.example.com/mcp \
  -H "Authorization: Bearer vk_XXXX" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Принцип работы

Параметр	Описание
Endpoint	`POST /mcp` с сообщением JSON-RPC 2.0; ответ — `application/json`. `GET /mcp` возвращает 405 (нет потока от сервера к клиенту); `DELETE /mcp` завершает сессию.
Аутентификация	Только `Authorization: Bearer vk_...` (токены сессий, cookies и ключи администратора отклоняются с кодом 401 и заголовком `WWW-Authenticate: Bearer`).
Сессия	`Mcp-Session-Id` выдается `initialize`, привязан к этому ключу, действует 24 часа; не более 16 сессий на ключ.
Инструменты	Один на каждую публичную операцию API, доступную ключу. Имя инструмента — это команда CLI с `_` вместо пробелов и дефисов (`vm firewall add` превращается в `vm_firewall_add`) и совпадает с OpenAPI `operationId`. Инструмент отображается в списке только при наличии соответствующего scope у ключа и включенном модуле.
Возможности	Только инструменты (без resources и prompts).
Размер	Тело запроса до 1 МБ; текст результата инструмента примерно до 100 КБ (остальное усекается с примечанием); вызов длится не более 55 секунд.

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

Тот же шлюз, что и для REST. Каждый tools/call проходит через стандартный конвейер обработки запросов панели: применяются ограничения по scope, сайту, IP, rate limit, идемпотентность, проверка владения (404 для чужих ресурсов) и квоты. MCP не может предоставить права, которых нет у ключа.
Подтверждение. Инструменты, которые списывают средства, удаляют ресурсы или возвращают учетные данные (тикеты консоли, kubeconfig, секреты S3 или SSH, сброс паролей, новые ключи), требуют аргумент confirm: true. В описании инструмента ассистенту предписано передавать его только после одобрения пользователем, поэтому скрытая инструкция на веб-странице или в логе не сможет выполнить действие самостоятельно.
Идемпотентность. Платные инструменты принимают idempotency_key; если параметр не указан, постоянный ключ формируется на основе имени инструмента и его аргументов, поэтому повторный запрос с теми же данными не приведет к повторному списанию.
Не предоставляются в виде инструментов: потоковые эндпоинты (чат AI Agent), одноразовые WebSocket-тикеты для SSH или консоли, скачивание бинарных файлов и эндпоинты приложения VPN (/v1/ext/*).
Исключено полностью: API ни при каких условиях не позволяет пополнять баланс, изменять пароли, удалять аккаунт или создавать ключи, поэтому никакой ассистент не сможет выполнить эти действия.

Лимиты

Лимит	По умолчанию
Вызовов инструментов на ключ	60 в минуту
Запросов MCP на ключ	240 в минуту
Плюс стандартные лимиты ключа и аккаунта	См. REST API

При превышении лимита эндпоинт возвращает HTTP 429 с ошибкой JSON-RPC и Retry-After.

Проверка

Приведенная выше команда curl возвращает результат JSON-RPC со списком tools. Отображаются только инструменты, соответствующие scopes ключа.
В своем клиенте запросите «list my VMs»: ассистент вызовет vm_list и покажет результат.
В портале обновляется время Last used ключа, а вызовы на запись появляются в Key usage log.

Ограничения и примечания

Вход через браузер (OAuth). На справочной странице также описан вход через браузер для клиентов с поддержкой MCP OAuth. В установленном экземпляре NexCMP поддерживаемым и протестированным методом является API-ключ (или cmp login для CLI).
Сайты реселлеров не отображают раздел MCP; их клиенты используют домен реселлера для работы с API.
Принцип наименьших привилегий. Создавайте для каждого ассистента отдельный ключ, сначала только с правами на чтение; добавляйте права на запись только при необходимости.
Отозовите ключ в API keys, чтобы мгновенно закрыть ассистенту доступ.

Устранение неполадок

Симптом	Причина	Решение
401 с `WWW-Authenticate: Bearer`	Ключ отсутствует, указан неверно или передан токен сессии	Передайте `Authorization: Bearer vk_...`.
403 с ошибкой `Origin`	Страница браузера с другого origin	Используйте десктопный клиент или CLI либо попросите администратора разрешить origin (`mcp_allowed_origins`).
404 при запросе с `Mcp-Session-Id`	Сессия принадлежит другому ключу или истекла	Выполните `initialize` повторно.
405 при `GET /mcp`	Ожидаемое поведение: на сервере нет потока событий	Используйте только POST (клиенты делают это автоматически).
Список инструментов неполный	Scopes ключа или отключенные модули	Добавьте scopes к ключу; включите модуль.
Инструмент сообщает, что требуется `confirm: true`	Платный инструмент, операция удаления или конфиденциальные данные	Ассистент должен передать `confirm` после вашего подтверждения.
429	Rate limit для MCP или ключа	Подождите `Retry-After`.
Клиент не может подключиться с заголовком	Клиент без поддержки пользовательских заголовков	Используйте мост `mcp-remote`.

Сервер MCP ​

Назначение ​

Требования ​

Подготовка инфраструктуры ​

Подключение (со стороны клиента) ​

Принцип работы ​

Правила безопасности ​

Лимиты ​

Проверка ​

Ограничения и примечания ​

Устранение неполадок ​