--- title: Сервер MCP description: Подключайте AI (Claude, Cursor, VS Code) к API через встроенный MCP-эндпоинт /mcp: аутентификация, настройка клиентов, инструменты и правила безопасности. url: https://nexcmp.com/ru/docs/developers/mcp/ applies_to: NexCMP 1.6.1 updated: 2026-11-02 --- # Сервер MCP {#mcp-server} > **Где найти в портале:** в разделе API reference › Tools (`https:///apidoc`) представлены эндпоинт и примеры для клиентов; ключи создаются в API keys (`/api-keys`). В панели администратора настроек нет: эндпоинт встроен в панель. ## Назначение {#what-it-does} **Model Context Protocol (MCP)** позволяет AI-ассистенту вызывать инструменты. NexCMP предоставляет эндпоинт MCP по адресу `https:///mcp`. Каждая публичная операция API становится **инструментом** (`vm_list`, `vm_start`, `billing_wallet`, ...), поэтому клиент может спросить ассистента: «какие из моих VM запущены?» или «останови staging VM». Ассистент действует исключительно с собственным API-ключом и правами клиента. ::: tip Настройка самого NexCMP с помощью AI? На этой странице описан **клиентский** эндпоинт MCP (`/mcp`). Чтобы разрешить AI-ассистенту настраивать панель от имени администратора, см. [Configure with AI](https://nexcmp.com/ru/docs/configure-with-ai/mcp-admin/) (эндпоинт `/mcp/admin`, ключи администратора `ak_`). ::: ## Требования {#requirements} | Параметр | Требование | |---|---| | Сервер | Устанавливать ничего не нужно: эндпоинт обслуживается панелью и доступен везде, где доступна сама панель. Ваш обратный прокси должен перенаправлять `/mcp` на панель. | | Клиент | [API-ключ](https://nexcmp.com/ru/docs/developers/api-keys/) (`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. | ## Подготовка инфраструктуры {#prepare-the-infrastructure} Ничего, кроме проверки того, что `https:///mcp` не заблокирован межсетевым экраном или правилом прокси. Браузерный клиент MCP из другого источника (origin) отклоняется, если этот origin не разрешен; клиенты командной строки и десктопные клиенты не отправляют заголовок `Origin` и работают как есть. ## Подключение (со стороны клиента) {#connect-customer-side} 1. Создайте API-ключ в портале (**API keys › Create key**) только с теми областями видимости (scopes), которые требуются ассистенту, коротким сроком действия и, по возможности, ограничением по IP. 2. Добавьте сервер в свой клиент. Замените `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" } } } } ``` Укажите заголовок без пробела после двоеточия и поместите значение целиком в переменную окружения, как показано выше. 3. Перезапустите клиент и попросите его вывести список доступных инструментов. Проверка подключения без клиента: ```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"}' ``` ## Принцип работы {#how-it-works} | Параметр | Описание | |---|---| | 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 секунд. | ### Правила безопасности {#safety-rules} - **Тот же шлюз, что и для REST.** Каждый `tools/call` проходит через стандартный конвейер обработки запросов панели: применяются ограничения по scope, сайту, IP, rate limit, идемпотентность, проверка владения (404 для чужих ресурсов) и квоты. MCP не может предоставить права, которых нет у ключа. - **Подтверждение.** Инструменты, которые списывают средства, удаляют ресурсы или возвращают учетные данные (тикеты консоли, kubeconfig, секреты S3 или SSH, сброс паролей, новые ключи), требуют аргумент `confirm: true`. В описании инструмента ассистенту предписано передавать его только после одобрения пользователем, поэтому скрытая инструкция на веб-странице или в логе не сможет выполнить действие самостоятельно. - **Идемпотентность.** Платные инструменты принимают `idempotency_key`; если параметр не указан, постоянный ключ формируется на основе имени инструмента и его аргументов, поэтому повторный запрос с теми же данными не приведет к повторному списанию. - **Не предоставляются в виде инструментов:** потоковые эндпоинты (чат AI Agent), одноразовые WebSocket-тикеты для SSH или консоли, скачивание бинарных файлов и эндпоинты приложения VPN (`/v1/ext/*`). - **Исключено полностью:** API ни при каких условиях не позволяет пополнять баланс, изменять пароли, удалять аккаунт или создавать ключи, поэтому никакой ассистент не сможет выполнить эти действия. ### Лимиты {#limits} | Лимит | По умолчанию | |---|---| | Вызовов инструментов на ключ | 60 в минуту | | Запросов MCP на ключ | 240 в минуту | | Плюс стандартные лимиты ключа и аккаунта | См. [REST API](https://nexcmp.com/ru/docs/developers/api/#rate-limits) | При превышении лимита эндпоинт возвращает HTTP 429 с ошибкой JSON-RPC и `Retry-After`. ## Проверка {#verify} 1. Приведенная выше команда `curl` возвращает результат JSON-RPC со списком `tools`. Отображаются только инструменты, соответствующие scopes ключа. 2. В своем клиенте запросите «list my VMs»: ассистент вызовет `vm_list` и покажет результат. 3. В портале обновляется время **Last used** ключа, а вызовы на запись появляются в **Key usage log**. ## Ограничения и примечания {#limits-notes} - **Вход через браузер (OAuth).** На справочной странице также описан вход через браузер для клиентов с поддержкой MCP OAuth. В установленном экземпляре NexCMP поддерживаемым и протестированным методом является API-ключ (или `cmp login` для CLI). - **Сайты реселлеров** не отображают раздел MCP; их клиенты используют домен реселлера для работы с API. - **Принцип наименьших привилегий.** Создавайте для каждого ассистента отдельный ключ, сначала только с правами на чтение; добавляйте права на запись только при необходимости. - Отозовите ключ в **API keys**, чтобы мгновенно закрыть ассистенту доступ. ## Устранение неполадок {#troubleshooting} | Симптом | Причина | Решение | |---|---|---| | 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`. |