---
title: Подключение AI-клиента (MCP)
description: Подключите Claude Code, Codex CLI, Cursor, ChatGPT и другие клиенты к админскому MCP-эндпоинту панели со всем набором инструментов.
url: https://nexcmp.com/ru/docs/configure-with-ai/mcp-admin/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# Подключение AI-клиента (MCP) {#connect-an-ai-client-mcp}

> **В панели управления:** System › Settings › API & AI agents (`/agent/keys`); на вкладке **Connect an AI** указан URL эндпоинта и готовые сниппеты с только что созданным ключом.

## Назначение {#what-it-does}

Протокол **Model Context Protocol (MCP)** позволяет AI-клиентам вызывать инструменты. Панель предоставляет административный MCP-сервер по адресу `https://cloud.example.com/mcp/admin`. Подключите к нему AI-инструмент и управляйте инфраструктурой на обычном языке: «что осталось настроить?», «добавь кластер Proxmox», «создай тарифы с маржой 40%». Клиент вызывает админские инструменты; панель проверяет права доступа, запрашивает подтверждение перед опасными операциями и логирует каждый вызов.

::: info Два MCP-эндпоинта
`/mcp` — **клиентский** эндпоинт (клиентские API-ключи, `vk_`; см. [MCP server](https://nexcmp.com/ru/docs/developers/mcp/)). `/mcp/admin` — описанный здесь **административный** эндпоинт (админские ключи `ak_` или OAuth). Они полностью разделены: админские инструменты недоступны на `/mcp`, а `/mcp/admin` принимает только админские ключи.
:::

## Требования {#requirements}

| Параметр | Требование |
|---|---|
| Endpoint | `https://cloud.example.com/mcp/admin` на собственном домене вашей панели. Скопируйте точный URL на вкладке **Connect an AI**. На этой же странице указан локальный URL (`http://127.0.0.1:<port>/mcp/admin`) для инструментов, работающих на самом сервере. |
| Учетные данные | [Административный API-ключ](https://nexcmp.com/ru/docs/configure-with-ai/admin-api-keys/) (`ak_...`) с нужными правами доступа **или** вход через OAuth для веб-коннекторов ([OAuth connectors](https://nexcmp.com/ru/docs/configure-with-ai/oauth-connectors/)). |
| Клиент | Любой MCP-клиент с поддержкой транспорта **Streamable HTTP** и кастомного заголовка `Authorization`. Версии протокола: 2025-11-25, 2025-06-18 и 2025-03-26. |
| Сеть | Если перед панелью используется собственный reverse proxy, он должен проксировать `/mcp/admin`. Веб-коннекторы (claude.ai, ChatGPT) подключаются с серверов провайдера, поэтому URL должен быть доступен из интернета. |

## Подготовка инфраструктуры {#prepare-the-infrastructure}

На сервере ничего устанавливать не нужно. Если вы настроили ограничение ключа по IP, убедитесь, что адрес клиента входит в разрешенный диапазон. Сначала проверьте доступность:

```bash
curl -i -X POST https://cloud.example.com/mcp/admin
```

Ответ `401` с заголовком `WWW-Authenticate: Bearer ... resource_metadata=...` означает, что эндпоинт работает и ожидает учетные данные.

## Подключение в NexCMP {#connect-in-nexcmp}

1. Создайте ключ: **System › Settings › API & AI agents › API keys › New key**. Для первого теста выберите только `admin:read`; права на запись можно добавить позже при необходимости. См. [Admin API keys](https://nexcmp.com/ru/docs/configure-with-ai/admin-api-keys/).
2. Перейдите на вкладку **Connect an AI**. Пока открыто окно с новым ключом, сниппеты ниже уже содержат ваш реальный ключ. В противном случае отображается плейсхолдер `ak_YOUR_KEY`.
3. Скопируйте сниппет для вашего клиента и запустите или вставьте его, как описано далее.

![Вкладка Connect an AI с MCP URL и карточками с кнопкой копирования для каждого клиента](https://nexcmp.com/ru/docs/images/configure-with-ai/mcp-admin-01-connect.webp)

### Claude Code {#claude-code}

```bash
claude mcp add --transport http nexcmp https://cloud.example.com/mcp/admin \
  --header "Authorization: Bearer ak_XXXX"
```

Затем запустите `claude` и введите запрос: «list the tools from nexcmp» или «what is left to set up?».

Проверено 30/10/2026 с Claude Code 2.1: `claude mcp add --transport http …` записывает сервер (добавьте `-s project`, чтобы сохранить его в `.mcp.json` проекта — Claude Code запрашивает подтверждение серверов проекта при первом запуске). Для скриптов `claude -p "…" --mcp-config .mcp.json --strict-mcp-config --allowedTools "mcp__nexcmp__*"` выполняется без запроса подтверждения и позволяет Claude использовать только инструменты панели.

### Claude Desktop {#claude-desktop}

Требуется Node.js 18 или новее. Добавьте следующий фрагмент в `claude_desktop_config.json` (используется мост `mcp-remote`) и перезапустите Claude Desktop:

```json
{
  "mcpServers": {
    "nexcmp": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://cloud.example.com/mcp/admin", "--header", "Authorization:Bearer ak_XXXX"]
    }
  }
}
```

Если система некорректно обрабатывает пробел в аргументе заголовка, передайте все значение через переменную окружения (аналогично клиентскому эндпоинту): `"args": [..., "--header", "Authorization:${NEXCMP_AUTH_HEADER}"]` с `"env": { "NEXCMP_AUTH_HEADER": "Bearer ak_XXXX" }`.

### claude.ai (custom connector) {#claude-ai-custom-connector}

Ключ не требуется: авторизация выполняется через OAuth. В claude.ai откройте настройки коннекторов, добавьте custom connector, вставьте `https://cloud.example.com/mcp/admin`, войдите под учетной записью администратора NexCMP и выберите разрешения на экране подтверждения. Подробнее: [OAuth connectors](https://nexcmp.com/ru/docs/configure-with-ai/oauth-connectors/).

### ChatGPT (developer mode) {#chatgpt-developer-mode}

Ключ не требуется. В ChatGPT включите developer mode, добавьте MCP-коннектор с URL `https://cloud.example.com/mcp/admin`, выберите OAuth и войдите под учетной записью администратора NexCMP. Подробнее: [OAuth connectors](https://nexcmp.com/ru/docs/configure-with-ai/oauth-connectors/).

### Codex CLI {#codex-cli}

Добавьте в `~/.codex/config.toml`:

```toml
[mcp_servers.nexcmp]
url = "https://cloud.example.com/mcp/admin"
bearer_token_env_var = "NEXCMP_KEY"
```

Затем экспортируйте ключ в командной оболочке, запускающей Codex:

```bash
export NEXCMP_KEY=ak_XXXX
codex
codex mcp list   # shows nexcmp with "Bearer token" auth
```

::: tip Неинтерактивный `codex exec`
В `codex exec` (скрипты, CI) Codex не запрашивает подтверждение перед вызовом инструментов и пропускает инструменты, изменяющие данные. Добавьте `default_tools_approval_mode = "approve"` в `[mcp_servers.nexcmp]`, чтобы разрешить их вызов; панель по-прежнему возвращает предпросмотр и запрашивает подтверждение для финансовых операций, действий безопасности и удаления. Проверено на Codex CLI 0.166 от 30/10/2026.
:::

### Gemini CLI {#gemini-cli}

Добавьте в `~/.gemini/settings.json`:

```json
{
  "mcpServers": {
    "nexcmp": {
      "httpUrl": "https://cloud.example.com/mcp/admin",
      "headers": { "Authorization": "Bearer ak_XXXX" }
    }
  }
}
```

Gemini CLI отключает серверы MCP в папках, которым он не доверяет. Запустите его в доверенной папке (или подтвердите доверие при запросе), затем проверьте командой `gemini mcp list` — отобразится `nexcmp … Connected`. Вы можете не хранить ключ в файле с помощью `"Authorization": "Bearer $NEXCMP_KEY"`. Проверено на Gemini CLI 0.66 от 30/10/2026.

### Cursor {#cursor}

Добавьте в `~/.cursor/mcp.json` (или `.cursor/mcp.json` в проекте):

```json
{
  "mcpServers": {
    "nexcmp": {
      "url": "https://cloud.example.com/mcp/admin",
      "headers": { "Authorization": "Bearer ak_XXXX" }
    }
  }
}
```

::: tip Хранение ключа вне конфигурационных файлов
Если клиент это поддерживает, считывайте ключ из переменной окружения, а не записывайте его в файл: Codex делает это по умолчанию (`bearer_token_env_var`), а Cursor принимает `"Bearer ${env:NEXCMP_KEY}"`. Никогда не фиксируйте в коммитах файлы, содержащие ключ.
:::

### OpenAI Agents SDK (Python) {#openai-agents-sdk-python}

```python
from agents.mcp import MCPServerStreamableHttp

nexcmp = MCPServerStreamableHttp(
    params={"url": "https://cloud.example.com/mcp/admin",
            "headers": {"Authorization": "Bearer ak_XXXX"}},
    name="nexcmp",
)
```

Полный цикл выполнения (проверено на `openai-agents` 0.24 от 30/10/2026 — инструмент чтения, затем изменение баланса, вернувшее предпросмотр для подтверждения и примененное при повторном вызове с `confirm_token`):

```python
import asyncio
from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp

async def main():
    async with MCPServerStreamableHttp(params={"url": "https://cloud.example.com/mcp/admin",
            "headers": {"Authorization": "Bearer ak_XXXX"}}, name="nexcmp") as nexcmp:
        agent = Agent(name="admin", model="gpt-5", mcp_servers=[nexcmp],
                      instructions="You operate a hosting panel through the nexcmp tools. Ask me before confirming money actions.")
        result = await Runner.run(agent, "Run system_health and summarise it in one line.")
        print(result.final_output)

asyncio.run(main())
```

### OpenAI Responses API {#openai-responses-api}

Передайте сервер как инструмент с типом `mcp`. Оставьте `require_approval` в `always`, чтобы программа запрашивала подтверждение перед каждым вызовом:

```json
{
  "type": "mcp",
  "server_label": "nexcmp",
  "server_url": "https://cloud.example.com/mcp/admin",
  "headers": { "Authorization": "Bearer ak_XXXX" },
  "require_approval": "always"
}
```

### Другие варианты (обычный HTTP) {#anything-else-plain-http}

Клиент без поддержки MCP может вызывать те же инструменты по HTTP. `GET /v1/admin/agent/tools` выводит их список, `POST /v1/admin/agent/tools/<name>` выполняет инструмент с аргументами в теле JSON, а `GET /v1/admin/openapi.json` возвращает спецификацию OpenAPI 3.1 (каждый инструмент — это отдельная операция). Для всех требуется `Authorization: Bearer ak_...`.

## Проверка {#verify}

1. Список инструментов без клиента:

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

   В ответе придет результат JSON-RPC со списком инструментов, разрешенных вашими scopes.
2. В клиенте запросите «run system_health». Инструмент возвращает предупреждения, состояние подключенной инфраструктуры, платежей, почты, AI и статус лицензии.
3. Откройте **API & AI agents › Activity**: отобразится список вызовов с именем клиента и `mcp`.
4. На сервере команда `sudo nexcmp status` выведет строку «MCP admin» со статусом `ready`, если эндпоинт отвечает (HTTP 401 без ключа является нормальным состоянием).

## Инструменты {#tools}

Сервер предоставляет 58 инструментов. Клиент видит только те инструменты, которые разрешены областями видимости (scopes) его ключа: для инструментов чтения требуется `admin:read`, для инструментов записи — соответствующий им scope. Инструменты записи также принимают опциональный аргумент `confirm_token` (см. [Confirmation](#confirmation-confirm-token)). Аргументы проверяются по схеме каждого инструмента: неизвестные или некорректно указанные аргументы отклоняются с сообщением об ошибке.

Цены указываются в USD: стоимость тарифов — в долларах в час (`hourly_usd`), баланс — в центах. Секретные значения можно устанавливать, но они никогда не возвращаются в ответе.

### Обзор и журналы {#overview-and-logs}

| Инструмент | Назначение | Скоуп | Изменяет данные | Требует подтверждения |
|---|---|---|---|---|
| `system_health` | Оповещения, требующие внимания, состояние инфраструктуры, платежей, почты, AI, статус лицензии и обновлений. | `admin:read` | Нет | Нет |
| `setup_checklist` | Что настроено и что осталось настроить: лицензия, инфраструктура, зона, шаблоны ОС, тарифы, платежи, почта, брендинг, юридические документы, тестовый заказ. | `admin:read` | Нет | Нет |
| `license_status` | Статус лицензии и наличие более новой версии NexCMP. | `admin:read` | Нет | Нет |
| `audit_search` | Поиск по журналу аудита администратора и журналу API-ключей. | `admin:read` | Нет | Нет |

### Настройки, брендинг, юридические документы, модули {#settings-branding-legal-modules}

| Инструмент | Назначение | Скоуп | Изменяет данные | Требует подтверждения |
|---|---|---|---|---|
| `settings_get` | Чтение общих настроек (`keys` фильтрует параметры; символ `*` на конце означает поиск по префиксу). | `admin:read` | Нет | Нет |
| `settings_update` | Изменение общих настроек из плоского объекта `values`. Принимаются только ключи, возвращаемые `settings_get`. | `settings:write` | Да | Если ключ затрагивает платежи, безопасность входа, глобальные переключатели или цены |
| `branding_get` | Название бренда, цвет, валюта отображения, наименование продавца, URL логотипа и favicon. | `admin:read` | Нет | Нет |
| `branding_update` | Установка названия бренда (до 60 символов), цвета (`#rrggbb`), валюты отображения (`usd` или `vnd`) и наименования продавца. | `settings:write` | Да | Нет |
| `branding_logo_set` | Загрузка светлого или тёмного логотипа либо favicon по HTTPS URL или base64 (PNG, JPEG, WEBP, ICO или SVG, до 512 КБ). | `settings:write` | Да | Нет |
| `legal_get` | Условия обслуживания и политика конфиденциальности (на английском и вьетнамском языках), а также нейтральные значения по умолчанию. | `admin:read` | Нет | Нет |
| `legal_update` | Настройка текста условий и политики (простой markdown, без HTML, до 50 КБ каждый). Пустая строка возвращает значение по умолчанию. | `settings:write` | Да | Нет |
| `modules_get` | Список включённых опциональных модулей и тех, которые можно переключать. | `admin:read` | Нет | Нет |
| `module_set` | Включение или отключение опционального модуля (`key` должен быть одним из `settable`). | `settings:write` | Да | Нет |

### Электронная почта и оповещения {#email-and-alerts}

| Инструмент | Назначение | Скоуп | Изменяет данные | Требует подтверждения |
|---|---|---|---|---|
| `smtp_get` | Настройки исходящей почты (пароль скрыт) и состояние очереди. | `admin:read` | Нет | Нет |
| `smtp_configure` | Настройка сервера SMTP. При смене хоста, порта или параметров безопасности требуется повторный ввод пароля. | `settings:write` (+ `secrets:write` для пароля) | Да | Нет |
| `smtp_test` | Отправка реального тестового письма с сохранёнными настройками. | `settings:write` | Отправляет письмо | Нет |
| `telegram_get` | Каналы уведомлений администратора (ID чатов; токены ботов никогда не возвращаются). | `admin:read` | Нет | Нет |
| `telegram_configure` | Добавление или обновление канала оповещений Telegram (токен бота и ID чата) и переключение оповещений администратора. | `settings:write` (+ `secrets:write` для токена) | Да | Нет |
| `telegram_test` | Отправка тестового сообщения в канал Telegram. | `settings:write` | Отправляет сообщение | Нет |

### Платежи и валюта {#payments-and-currency}

| Инструмент | Назначение | Скоуп | Изменяет данные | Требует подтверждения |
|---|---|---|---|---|
| `payments_get` | Статус Stripe, PayPal, криптовалюты (USDT) и банковского перевода, а также включённые каналы и комиссии. | `admin:read` | Нет | Нет |
| `payment_configure` | Настройка учётных данных одного шлюза (`stripe`, `paypal`, `crypto` или `bank`). | `billing:write` (+ `secrets:write`) | Да | Всегда |
| `payment_test` | Проверка сохранённых учётных данных шлюза на стороне провайдера. | `billing:write` | Нет | Нет |
| `currency_get` | Отображаемая валюта и курс USD к VND (автоматический или фиксированный). | `admin:read` | Нет | Нет |
| `currency_set` | Настройка отображаемой валюты и/или фиксированного курса (0 — автоматический, иначе от 15000 до 50000). | `billing:write` | Да | При изменении фиксированного курса |

### Инфраструктура и зоны {#infrastructure-and-zones}

| Инструмент | Назначение | Скоуп | Изменяет данные | Требует подтверждения |
|---|---|---|---|---|
| `cloudstack_get` | Сохранённая точка подключения к CloudStack, идентификаторы зон и сетей (ключи скрыты). | `admin:read` | Нет | Нет |
| `cloudstack_test` | Тестирование точки подключения с ключом и секретом API без сохранения; выводит список зон. | `infra:write` (+ `secrets:write`, так как передаются ключи) | Нет | Нет |
| `cloudstack_connect` | Сохранение подключения к CloudStack. | `infra:write` (+ `secrets:write`) | Да | Всегда |
| `proxmox_list` | Кластеры Proxmox VE, добавленные в качестве источников, с их статусом работоспособности. | `admin:read` | Нет | Нет |
| `proxmox_add` | Добавление кластера Proxmox VE с токеном API (`user@realm!tokenid`) и его секретом. | `infra:write` (+ `secrets:write`) | Да | Нет |
| `proxmox_test` | Подключение к кластеру по ID; при первом успешном соединении привязывается его TLS-сертификат. | `infra:write` | Да | Нет |
| `proxmox_attach_zone` | Продажа кластера Proxmox в существующей зоне, опционально с узлом в качестве региона. | `infra:write` | Да | Нет |
| `zones_list` | Зоны (локации), доступные для выбора клиентам. | `admin:read` | Нет | Нет |
| `zone_create` | Создание зоны. | `infra:write` | Да | Нет |

### Каталог и тарифные планы {#catalog-and-plans}

| Инструмент | Назначение | Скоуп | Изменяет данные | Требует подтверждения |
|---|---|---|---|---|
| `templates_list` | Шаблоны ОС, доступные клиентам для установки. | `admin:read` | Нет | Нет |
| `templates_sync` | Импорт шаблонов ОС из CloudStack. | `catalog:write` | Да | Нет |
| `template_update` | Включение или скрытие шаблона, переименование, настройка пользователя по умолчанию или порядка сортировки. | `catalog:write` | Да | Нет |
| `offerings_list` | Сервисные предложения CloudStack (CPU, память, корневой диск) для формирования тарифов. | `admin:read` | Нет | Нет |
| `plans_list` | Тарифные планы с ценой за час и за месяц, конфигурацией, зоной и количеством использующих их серверов. | `admin:read` | Нет | Нет |
| `plan_create` | Создание тарифного плана. Цена указывается в `hourly_usd`. Для тарифов CloudStack требуется `cs_offering_id`; для Proxmox — `backend_id`. | `catalog:write` | Да | Нет |
| `plan_update` | Переименование, отображение или скрытие, включение или отключение, а также изменение цен тарифа. Изменение конфигурации активного тарифа требует создания копии. | `catalog:write` | Да | При изменении цены |
| `plans_from_offerings` | Сформировать начальную таблицу тарифов из offerings (или конфигураций Proxmox) на основе вашей себестоимости и процента наценки. Возвращает предпросмотр; вызовите повторно с `apply=true`, чтобы создать тарифы. | `catalog:write` | С `apply=true` | Всегда при применении |
| `quota_defaults_get` | Лимиты клиентов по умолчанию. | `admin:read` | Нет | Нет |
| `quota_defaults_set` | Изменить настройки `quota_*`. | `catalog:write` | Да | Нет |
| `coupons_list` | Пакеты скидочных кодов и подарочных сертификатов. | `admin:read` | Нет | Нет |
| `coupon_create` | Создать пакет кодов: тип `money` (номинал в центах USD) или `percent` (от 1 до 100, с максимальной скидкой). | `catalog:write` | Да | Всегда |

### Клиенты и реселлеры {#customers-and-resellers}

| Инструмент | Назначение | Скоуп | Изменяет данные | Требует подтверждения |
|---|---|---|---|---|
| `customers_search` | Поиск клиентов по e-mail, имени или IP. | `admin:read` | Нет | Нет |
| `customer_get` | Аккаунт, баланс, серверы и недавние списания конкретного клиента. | `admin:read` | Нет | Нет |
| `customer_adjust_balance` | Начислить (положительное значение) или списать (отрицательное значение) средства в центах USD. Обязательно указать причину. | `billing:write` | Да | Всегда |
| `customer_block` | Заблокировать клиента с возможностью остановки его серверов. Обязательно указать причину. | `customers:write` | Да | Всегда |
| `customer_unblock` | Разблокировать клиента. | `customers:write` | Да | Нет |
| `resellers_list` | Реселлеры с балансом и статусом. | `admin:read` | Нет | Нет |
| `reseller_get` | Сайт, баланс, пользователи и платежные шлюзы конкретного реселлера. | `admin:read` | Нет | Нет |

### Провайдер ИИ {#ai-provider}

| Инструмент | Назначение | Скоуп | Изменяет данные | Требует подтверждения |
|---|---|---|---|---|
| `ai_provider_get` | OpenAI-совместимый провайдер, используемый клиентскими функциями AI Chat и AI Agent (ключ скрыт). | `admin:read` | Нет | Нет |
| `ai_provider_set` | Настроить провайдера: base URL, модель, API-ключ, резервные модели, reasoning effort, активность. | `ai:write` (+ `secrets:write` для ключа) | Да | Нет |
| `ai_provider_test` | Задать сохраненному провайдеру один вопрос для проверки его работоспособности. | `ai:write` | Нет | Нет |

### Файлы конфигурации {#configuration-files}

| Инструмент | Назначение | Скоуп | Изменяет данные | Требует подтверждения |
|---|---|---|---|---|
| `config_export` | Экспортировать конфигурацию в формате YAML (секреты заменяются ссылками `secret://`). | `admin:read` | Нет | Нет |
| `config_plan` | Сравнить YAML-конфигурацию с текущей панелью и показать список планируемых изменений. | `admin:read` | Нет | Нет |
| `config_apply` | Применить YAML-конфигурацию раздел за разделом. Каждое изменение подчиняется стандартным правилам разрешений и подтверждения. | `admin:read` + разрешения каждого изменения | Да | Для каждого изменения |

Формат файла описан в разделе [Конфигурация как код](https://nexcmp.com/ru/docs/configure-with-ai/config-as-code/).

## Промпты {#prompts}

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

| Промпт | Параметр | Что требуется сделать AI |
|---|---|---|
| `initial-setup` | нет | Вызвать `setup_checklist`, объяснить каждый оставшийся шаг в одном предложении, запросить необходимые данные, выполнить шаг подходящим инструментом, показать предпросмотр финансовых изменений и настроек безопасности, после чего завершить через `system_health`. |
| `add-proxmox` | `endpoint` (необязательно, `https://host:8006`) | Запросить токен API, затем вызвать `proxmox_add`, `proxmox_test`, инструменты зон и `proxmox_attach_zone`; после чего предложить тарифы с помощью `plans_from_offerings` и ожидать подтверждения. |
| `launch-pricing` | `margin_pct` (необязательно, по умолчанию 40) | Запросить вашу ежемесячную себестоимость vCPU, ГБ RAM и ГБ диска, показать таблицу предпросмотра с себестоимостью, ценой в месяц и ценой в час, а затем создать тарифы после вашего подтверждения. |

## Подтверждение (`confirm_token`) {#confirmation-confirm-token}

Действия, связанные с переводом средств, удалением данных, изменением платежных реквизитов или настроек авторизации, выполняются в два шага:

1. Первый вызов ничего не меняет. Ответ инструмента начинается со строки «CONFIRMATION REQUIRED» и содержит **предпросмотр** (что будет вызвано, почему операция чувствительна, новые и текущие значения) и `confirm_token`.
2. Клиент обязан показать вам предпросмотр. Только после вашего одобрения он повторно вызывает тот же инструмент с теми же параметрами и передает `confirm_token`.
3. Токен действует однократно, только для этого конкретного запроса и сгорает через 5 минут.

Инструкции сервера предписывают ИИ воспринимать результаты инструментов как данные, а не как инструкции, и ни в коем случае не повторять вызов с токеном, который вы не подтвердили. Главная защита — это вы: читайте предпросмотр.

::: warning Не одобряйте автоматически
Некоторые клиенты могут автоматически одобрять каждый вызов инструмента. Для инструментов записи оставьте подтверждение каждого вызова включенным или используйте ключ только для чтения, чтобы ошибочный план ИИ не был применен в панели незамеченным.
:::

## Принцип работы {#how-it-works}

| Параметр | Описание |
|---|---|
| Транспорт | `POST /mcp/admin` с сообщением JSON-RPC 2.0; ответ — `application/json`. До 20 сообщений в пакете. `GET /mcp/admin` возвращает 405 (нет серверного потока); `DELETE /mcp/admin` завершает сессию. |
| Аутентификация | `Authorization: Bearer ak_...` (созданный вручную ключ или токен доступа OAuth). При отсутствии или неверных учетных данных возвращается 401 с `WWW-Authenticate: Bearer ... resource_metadata=...`, что позволяет OAuth-клиентам самостоятельно запускать вход. |
| Сессии | `Mcp-Session-Id` выдается через `initialize`, привязан к этому ключу и действует 24 часа. |
| Возможности | Инструменты и промпты. Без ресурсов. |
| Размер | Тело запроса до 1 МБ; результат работы инструмента усекается примерно после 100 КБ. |
| Origin | Запрос с заголовком `Origin` от другого сайта отклоняется (`origin_not_allowed`). Клиенты командной строки и десктопные клиенты его не отправляют. |
| Тот же шлюз, что и для REST | Каждый вызов инструмента повторно отправляется через собственный конвейер запросов панели с вашим ключом, поэтому области видимости, диапазоны IP, лимит запросов, подтверждение и журнал активности применяются в точности так же, как и для прямых вызовов API. |

## Ограничения и примечания {#limits-notes}

- Если инструмент вам не виден, значит, для него не была предоставлена область видимости. Добавьте эту область видимости в новый ключ.
- Установка пароля или ключа API через ИИ-клиент означает, что секретные данные проходят через этот ИИ. При желании оставьте `secrets:write` отключенным и вводите секреты самостоятельно в панели администратора либо используйте поле **Secret** в AI Chat ([AI Chat в панели администратора](https://nexcmp.com/ru/docs/configure-with-ai/ai-chat-in-admin/#secrets)) или ссылки `secret://` ([Конфигурация как код](https://nexcmp.com/ru/docs/configure-with-ai/config-as-code/#secrets)).
- Клиенты не используют общие сессии: каждое подключение начинается с `initialize`.
- Отозовите ключ в **API & AI agents**, чтобы немедленно отключить ИИ-клиент.

## Устранение неполадок {#troubleshooting}

| Симптом | Причина | Решение |
|---|---|---|
| 401 `invalid_key` | Неверный, усеченный ключ или ключ без прав администратора (например, ключ `vk_`) | Используйте ключ `ak_`. |
| 401 `key_expired` или `key_revoked` | Срок действия ключа истек или он был отозван | Создайте новый ключ. |
| 403 `ip_not_allowed` | Ваш IP находится вне разрешенных для ключа диапазонов IP | Подключитесь с разрешенного IP. |
| 403 `origin_not_allowed` | Страница браузера с другого origin обратилась к эндпоинту | Используйте десктопный клиент или CLI. |
| 404 при запросе с `Mcp-Session-Id` | Сессия принадлежит другому ключу или истекла | Отправьте `initialize` повторно. |
| 400 unsupported `MCP-Protocol-Version` | Клиент использует версию, неизвестную серверу | Обновите клиент; поддерживаются: 2025-11-25, 2025-06-18, 2025-03-26. |
| Список инструментов неполный | Области видимости ключа | Создайте ключ с более широкими областями видимости. |
| `insufficient_scope` при вызове | Инструменту требуется вторая область видимости, например `secrets:write` | Добавьте область видимости в новый ключ. |
| 429 `rate_limited` | Количество вызовов в минуту превышает лимит ключа | Дождитесь `Retry-After` или увеличьте лимит в новом ключе. |
| claude.ai или ChatGPT не могут подключиться | URL недоступен из интернета, либо прокси блокирует `/mcp/admin` или `/oauth-admin/` | Проверьте DNS, TLS и обратный прокси. |

Все коды ошибок приведены в разделе [Ключи API администратора](https://nexcmp.com/ru/docs/configure-with-ai/admin-api-keys/#errors).