# Подключение ИИ-ассистентов через MCP

Источник: https://key-core.ru/help/getting-started/agents-mcp/

MCP позволяет внешнему ИИ-ассистенту обращаться к вашим проектам KeyCore: читать данные,
вносить разрешённые изменения и запускать операции. Изменения сохраняются в том же
аккаунте и видны в кабинете.

> MCP доступен на активных платных тарифах с подтверждённой почтой, без отдельной
> заявки на тестирование. Сквозная проверка всех клиентов продолжается; приведённые
> настройки не являются гарантией совместимости каждой версии приложения.

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

Откройте **Настройки → ИИ-ассистенты** в кабинете KeyCore. Для подключения нужны
подтверждённая почта и активный платный тариф. Если показано ограничение доступа,
смена настроек внешнего клиента его не снимет — обратитесь в поддержку.

Адрес сервера: `https://key-core.ru/mcp`. Тип подключения — **Streamable HTTP**.
Не используйте адрес страницы настроек и не добавляйте `/api` перед `/mcp`.
Этот адрес нужно вставить в настройки MCP вашего ассистента, **не открывать как
страницу в браузере**. Ответ 405 при открытии адресной строкой ожидаем: сервер
принимает запросы MCP-клиента. Для OAuth браузер откроет сам клиент — на странице
входа и согласия, а не на `/mcp`.
Если сервер отвечает 404, проверка подключения пока невозможна: сначала уточните
у поддержки, включён ли MCP. Самостоятельно менять пароль или выпускать новые ключи
из-за такого ответа не нужно.

## Выберите способ входа

**Рекомендуем начать с OAuth**, если приложение его поддерживает: вручную
создавать API-ключ и настраивать секрет не нужно. Добавьте HTTP-сервер по адресу
выше, оставив собственный заголовок `Authorization` незаданным. Клиент открывает
страницу входа и согласия KeyCore в браузере.
Проверьте адрес сайта, аккаунт, название клиента, права и лимит. Пароль KeyCore
вводится только на сайте KeyCore, не в чате с агентом. После согласия вернитесь
в приложение. Для первого подключения оставьте только чтение.

**API-ключ — отдельный альтернативный способ**, например если клиент не умеет OAuth.
В кабинете KeyCore нажмите **Создать ключ**, задайте понятное название, например
«Cursor — тест чтения», и оставьте только право чтения. Сохраните ключ сразу:
повторно показать его нельзя. Для разных приложений создавайте отдельные подключения.
Не отправляйте ключ в чат, репозиторий, скриншоты или обращение в поддержку.
Не смешивайте способы в одной записи сервера: для OAuth не нужен заголовок
`Authorization: Bearer …` из примера с ключом. При переходе на OAuth удалите
такой заголовок именно у KeyCore и пройдите вход заново. Другие серверы не меняйте.

### Cursor

В настройках MCP добавьте удалённый сервер с адресом `https://key-core.ru/mcp`.
Для OAuth используйте подключение без собственного заголовка Authorization и
пройдите предложенный вход. Для API-ключа возьмите конфигурацию на вкладке **Cursor**
в кабинете KeyCore: она содержит ссылку `${env:KEYCORE_API_KEY}`, а не сам секрет.
Переменная должна быть доступна процессу Cursor при запуске. После изменения
окружения полностью перезапустите редактор; переменные терминала не обязательно
видны приложению, запущенному через значок.

Не настраивайте API-ключ и OAuth одновременно для одной тестовой записи:
проверяйте способы по очереди. Названия кнопок зависят от версии Cursor.

### Claude Code

Для OAuth зарегистрируйте HTTP-сервер:

```bash
claude mcp add --transport http keycore https://key-core.ru/mcp
```

Затем запустите Claude Code, откройте `/mcp`, выберите KeyCore и пройдите вход.
Для API-ключа используйте вместо OAuth запись в `.mcp.json` вашего проекта:

```json
{
  "mcpServers": {
    "keycore": {
      "type": "http",
      "url": "https://key-core.ru/mcp",
      "headers": { "Authorization": "Bearer ${KEYCORE_API_KEY}" }
    }
  }
}
```

Добавьте запись к существующему `mcpServers`, не затирая другие подключения.
`${KEYCORE_API_KEY}` оставьте буквально: клиент прочитает переменную окружения
при запуске. Не заменяйте её ключом и не передавайте раскрытый секрет в команду
`claude mcp add --header`: такая команда может сохранить сам ключ в конфигурации.
Задайте переменную безопасным способом на своём компьютере и запустите Claude Code
из окружения, где она доступна. После запуска проверьте `/mcp`.
Формат описан в [документации Claude Code](https://code.claude.com/docs/en/mcp).

### WorkAI

Ниже — документированный формат, сверенный 17 сентября 2026 года.
Сквозная проверка подключения WorkAI к KeyCore ещё не выполнена: работа входа
и инструментов на реальном подключении пока не подтверждена.

#### OAuth — начните с этого способа

1. Откройте **Настройки → MCP** (либо «MCP-серверы» в настройках агента).
2. Добавьте свой сервер через мастер, выберите **HTTP**, а не команду или пакет.
3. Вставьте `https://key-core.ru/mcp`, задайте имя `keycore` и выберите область:
   текущий проект или все проекты. Собственный `Authorization` не добавляйте.
4. Подключите сервер и пройдите предложенный вход в браузере. На сайте KeyCore
   проверьте аккаунт и разрешите для первой проверки только чтение.
5. Вернитесь в WorkAI и выполните безопасную проверку из раздела ниже.

Если вход не предлагается, проверьте, не осталась ли у KeyCore настройка API-ключа.
Не вставляйте URL сервера в адресную строку браузера вместо мастера. Работа OAuth,
обновления токена и отзыва с KeyCore пока не подтверждена живым прогоном.

#### API-ключ — альтернативная настройка

Используйте поддерживаемый WorkAI **формат VS Code**: файл
`.vscode/mcp.json` в проекте или профильный `mcp.json`, открытый через настройки MCP.
Пример ниже — целый файл только для случая, когда конфигурации ещё нет:

```json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "keycore-api-key",
      "description": "API-ключ KeyCore",
      "password": true
    }
  ],
  "servers": {
    "keycore": {
      "type": "http",
      "url": "https://key-core.ru/mcp",
      "headers": { "Authorization": "Bearer ${input:keycore-api-key}" }
    }
  }
}
```

Если файл уже существует, не заменяйте его этим примером. В существующий объект
`servers` добавьте только свойство `keycore`, а в существующий массив `inputs` —
один объект с `id: "keycore-api-key"`. Если `inputs` отсутствует, создайте его
на верхнем уровне рядом с `servers`. Остальные свойства и записи сохраните.
Если имя сервера или input ID уже занято, проверьте существующую запись:
не создавайте повторяющиеся ключи. При выборе другого input ID замените его
и в `${input:…}` заголовка KeyCore.

Оставьте `${input:keycore-api-key}` буквально. При подключении введите ключ в
защищённое поле WorkAI, не в JSON и не в чат. По документации приложения парольный
ввод хранится зашифрованно. **Не переносите этот пример в `~/.workai/mcp.json` или
`.workai/mcp.json`:** там другой формат (`mcpServers`), подстановки не работают,
а значения ключей сохраняются открытым текстом.

Источник форматов, хранения секретов и OAuth — [документация WorkAI](https://workai.su/docs/mcp).

### Другие приложения

Проверьте поддержку Streamable HTTP и нужного способа авторизации в документации
конкретного клиента. Не копируйте конфигурацию другого редактора без проверки
формата. При проблеме сообщите поддержке название и версию приложения, но не секреты.

## Безопасная первая проверка

1. Попросите агента: «Вызови `keycore_ping`, затем `keycore_list_projects`.
   Ничего не изменяй и не запускай платные операции».
2. Убедитесь, что подключение относится к вашему аккаунту и возвращает ваши проекты.
   Пустой список допустим, если проектов ещё нет.
3. Перезапустите клиента и повторите запрос. Для OAuth клиент может обновить вход
   автоматически или попросить авторизацию ещё раз.
4. В кабинете отзовите тестовое подключение. Следующий запрос через него должен
   завершиться отказом. Клиент может ещё показывать старый список инструментов;
   проверяйте именно новый вызов.

Для проверки записи создайте отдельный тестовый проект и отдельное подключение
с правом записи. Сверьте результат в кабинете. Не начинайте приёмку с удаления
рабочих данных или выгрузки кампании в рекламный кабинет.

## Права, расходы и безопасность

| Право | Что разрешает |
|---|---|
| Чтение (`keycore:read`) | Просматривать доступные данные аккаунта |
| Запись (`keycore:write`) | Выполнять разрешённые операции изменения |
| Платные операции (`keycore:spend`) | Запускать операции, расходующие баланс |

Выдавайте минимальные права. Суточный лимит подключения не пополняет баланс и
не заменяет оплату операции. Актуальные доступные лимиты смотрите в кабинете,
стоимость — перед запуском и в [справке по тарифам](/help/getting-started/pricing/).
Обрыв соединения или закрытие приложения не гарантируют отмену уже запущенной операции.
Сначала проверьте её статус, прежде чем повторять запуск.

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

Агент может переименовать проект, но не удаляет его навсегда: на просьбу удалить он убирает
проект в архив. Фразы, группы и объявления при этом сохраняются. Убрать проект в архив можно и
самому — пункт **В архив** в меню карточки проекта. Архив — внизу страницы **Проекты**: там проект
можно восстановить или удалить окончательно. Проект с идущей
операцией агент в архив не уберёт — сначала дождитесь её завершения или остановите её.

## Если не подключается

| Симптом | Что проверить |
|---|---|
| 405 при открытии `/mcp` в браузере | Это адрес протокола, а не страница: добавьте его в настройках MCP клиента |
| 404 на `/mcp` | Правильный адрес и включение MCP на сервере |
| 401 | Ключ, переменную окружения, истечение или отзыв доступа; для OAuth повторите вход |
| 403 или отказ внутри результата инструмента | Права подключения, подтверждение почты, активный тариф и доступ к проекту |
| 429 | Лимит запросов: подождите указанное время, не запускайте цикл повторов |
| Отклонён платный вызов | Право платных операций, баланс и оставшийся лимит подключения |
| После изменения переменной осталась ошибка | Перезапуск клиента из правильного окружения |

В поддержку передайте время, версию клиента, способ подключения и код ошибки.
Уберите из сообщения Authorization, ключи, коды входа, токены и содержимое проектов.