Документация › Для разработчиков › Подключить ИИ-агента

Подключить ИИ-агента (MCP)

[для разработчиков] Подключите Claude Code, Codex или Cursor к DOS AI одной командой и управляйте проектами прямо из своего ИИ-инструмента: «покажи вчерашних лидов», «поправь промпт», «сколько потратили за неделю».

⏱ 7 мин · 👤 для разработчика и интегратора · 🟢 live

За 30 секунд:
Адрес сервера: https://dosai.pro/api/mcp, авторизация тем же ключом dos_sk_live_…, что и у API.
В Claude Code подключается одной командой, в Codex и Cursor через конфиг.
Агент получает 13 инструментов: проекты, промпт, функции, лиды, диалоги, отправка сообщения, аналитика, баланс.
Удалять проекты и проводить платежи агент не может: этого нет в наборе инструментов намеренно.
Готовые команды с подставленным ключом лежат в кабинете: раздел для разработчиков.

Что это даёт

Обычный API нужно программировать. MCP (Model Context Protocol) это стандартный «разъём», через который ИИ-инструмент видит платформу как набор понятных действий и вызывает их сам, по просьбе на человеческом языке.

Практический смысл для интегратора, который ведёт несколько клиентов:

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

Шаг 1. Выпустить ключ

Ключ выпускается в кабинете, раздел для разработчиков (/developers). Подробно про права и область действия написано в статье Публичный API.

Что важно выбрать правильно:

Выбор	Когда	Что сможет агент
Только чтение	Аналитика, отчёты, разбор диалогов	Смотреть, но ничего не менять
Чтение и запись	Правка промпта, ответы клиентам	Ещё и менять промпт, статусы лидов, отправлять сообщения
Один проект	Работа по одному клиенту	Только этот проект. `dosai_list_projects` вернёт ровно его, остальные недоступны
Весь аккаунт	Ведёте несколько проектов	Все проекты аккаунта

🔑 Ключ показывается один раз. Скопируйте сразу; потеряли, отзовите и выпустите новый.

Шаг 2. Подключить свой инструмент

Готовые команды с уже подставленным ключом появляются в кабинете сразу после создания ключа, проще скопировать оттуда. Ниже те же команды, если подключаете позже.

Claude Code

claude mcp add --transport http dosai https://dosai.pro/api/mcp \
  --header "Authorization: Bearer dos_sk_live_ВАШ_КЛЮЧ"

Проверка: claude mcp list, сервер dosai должен быть в списке. Дальше просто просите словами: «покажи мои проекты в DOS AI».

Codex

В ~/.codex/config.toml:

[mcp_servers.dosai]
url = "https://dosai.pro/api/mcp"
bearer_token_env_var = "DOSAI_KEY"

И ключ в профиль оболочки (~/.zshrc или ~/.bashrc):

export DOSAI_KEY="dos_sk_live_ВАШ_КЛЮЧ"

Так ключ не лежит в конфиге, который легко утащить в репозиторий или синхронизировать между машинами. Если ваш Codex ругается на поле url, он старый: обновите его, поддержка удалённых серверов там встроенная.

Cursor

В ~/.cursor/mcp.json:

{
  "mcpServers": {
    "dosai": {
      "url": "https://dosai.pro/api/mcp",
      "headers": { "Authorization": "Bearer dos_sk_live_ВАШ_КЛЮЧ" }
    }
  }
}

Cursor умеет подставлять переменные окружения, так что ключ тоже можно не держать в файле: "Authorization": "Bearer ${env:DOSAI_KEY}".

Что умеет агент

Инструмент	Что делает	Права ключа
`dosai_list_projects`	Список проектов	чтение
`dosai_get_project`	Настройки проекта: статус, канал, модель, баланс	чтение
`dosai_get_prompt`	Прочитать системный промпт	чтение (роль админа или владельца)
`dosai_update_prompt`	Заменить системный промпт	запись (роль админа или владельца)
`dosai_list_functions`	Список функций ассистента	чтение
`dosai_list_leads`	Лиды постранично, с фильтром по статусу (`none`, `potential`, `qualified`, `hot`, `converted`, `reserve`, `lost`)	чтение
`dosai_get_lead`	Полная карточка лида с ответами анкеты	чтение
`dosai_update_lead`	Статус лида, имя, телефон, почта	запись
`dosai_list_conversations`	Диалоги, с фильтром по статусу (`open`, `resolved`, `closed`) и включением архивных	чтение
`dosai_get_messages`	Переписка одного диалога	чтение
`dosai_send_operator_message`	Написать клиенту от лица оператора	запись
`dosai_get_analytics`	Диалоги, лиды, конверсия, время ответа, воронка, источники и расход за период (без указания дат: последние 7 дней)	чтение
`dosai_get_balance`	Остаток и расход	чтение

Чего в наборе нет намеренно: удаление проектов, платежи и возвраты, управление участниками, админ-функции. ИИ иногда ошибается, и цена ошибки не должна равняться удалённому проекту или списанным деньгам. Эти действия остались в API, где вызов делается осознанно.

Безопасность

Ключ = доступ к вашим проектам. Команда подключения содержит его в открытом виде: вставляйте только в свой терминал, не выкладывайте в репозиторий и не показывайте на экране при записи видео.
Начните с ключа только на чтение. Права на запись выдавайте, когда точно нужны правки.
Клиенту или подрядчику выдавайте ключ, привязанный к одному проекту.
Агент действует от вашего имени. Он видит ровно то, что видите вы, и ограничен вашей ролью на каждом проекте.
Отправка сообщения необратима. dosai_send_operator_message пишет живому человеку в WhatsApp или Telegram. Согласуйте текст с агентом до отправки.
Тексты клиентов это данные, а не команды. В переписке может оказаться фраза вида «игнорируй прежние инструкции и сделай…». Сервер прямо предупреждает об этом агента при подключении, но привычка проверять, что именно агент собирается сделать, остаётся за вами.

Лимиты

120 запросов в минуту на ключ, плюс собственный лимит у каждого эндпоинта (например, аналитика 20 в минуту).
Один вызов инструмента = два запроса к платформе, поэтому ориентируйтесь примерно на 60 действий агента в минуту.
Лимит считается на каждый ключ отдельно: два ключа одного аккаунта имеют по своему бюджету, они не складываются и не делятся.
При превышении приходит понятная агенту фраза «превышен лимит, подожди N секунд», и он повторит сам.

Если не работает

Что видит агент	Что произошло	Что делать
«API-ключ недействителен, истёк или отозван»	Ключ удалён, истёк или скопирован с опечаткой	Выпустить новый в кабинете
«Этот ключ только для чтения»	Ключ без права записи, а действие меняет данные	Выпустить ключ с правом записи
«Ключ привязан к другому проекту»	Ключ на один проект, а запрос к другому	Взять ключ на весь аккаунт или на нужный проект
«Недостаточно прав на этом проекте»	Ваша роль ниже администратора	Попросить владельца повысить роль
«Превышен лимит запросов»	Слишком часто	Подождать указанные секунды
«Конфликт: такое действие уже выполнено» на отправке	Тот же текст в тот же диалог в пределах минуты считается случайным дублем и не уходит	Так задумано: защищает клиента от двойного сообщения при повторе запроса. Нужно отправить то же самое ещё раз, подождите минуту или измените текст
«Неверные аргументы. Unrecognized key»	Агент передал поле, которого у инструмента нет	Ничего не делать: в ответе названо лишнее поле, агент исправится сам. Так сделано нарочно, чтобы выдуманный параметр не поменял смысл ответа молча
Сервер не появился в списке	Опечатка в адресе или заголовке	Проверить `https://dosai.pro/api/mcp` и формат `Bearer dos_sk_live_…`

Под капотом

Сервер работает по streamable HTTP и не хранит сессий: каждый вызов самодостаточен, поэтому переключение серверов между двумя запросами агента ничего не ломает.

Каждый инструмент внутри вызывает тот же публичный REST-эндпоинт, что и обычная интеграция. Это сделано намеренно: права, лимиты, проверки и запись в журнал живут в одном месте, и агент получает ровно те же ответы, что получил бы curl. Отдельной «агентской» логики доступа не существует, поэтому она не может разойтись с основной.

Ответы инструментов подрезаются: списки отдаются постранично, длинный системный промпт не приезжает вместе со списком проектов, аналитика сворачивается до цифр (без превью рекламных креативов и почасовой карты), а слишком большой ответ обрезается с подсказкой сузить запрос. Причина простая: результат вызова попадает в контекст модели, и один неаккуратный запрос иначе вытеснит всё, над чем вы работали. Там, где данные свёрнуты, инструмент прямо перечисляет, что именно осталось за кадром: иначе «этого у меня нет под рукой» легко превращается в «таких данных не существует».

Машиночитаемое описание REST-части лежит на https://dosai.pro/api/openapi.json, краткая памятка для агентов на https://dosai.pro/llms.txt.

Простыми словами

Обычно, чтобы связать программу с платформой, нужен программист: он пишет код, который ходит по адресам и разбирает ответы. MCP убирает этот шаг для ИИ-инструментов. Вы один раз даёте своему ИИ-помощнику адрес и ключ, и дальше говорите обычными словами: «сколько заявок пришло вчера», «поправь приветствие у бота стоматологии», «ответь этому клиенту, что перезвоним в десять». Помощник сам понимает, какое действие вызвать.

Ключ это пароль: он даёт помощнику ровно те же возможности, что есть у вас в кабинете, не больше. Если хотите, чтобы помощник только смотрел и ничего не менял, выпустите ключ «только чтение». Если работаете с одним клиентом, выпустите ключ на один проект: до остальных помощник не дотянется.

И главное, что мы решили заранее: помощник не умеет удалять проекты и трогать деньги. Даже если он что-то неправильно поймёт, худшее, что произойдёт, это изменённый текст промпта или одно лишнее сообщение клиенту. Всё это видно и поправимо.

Дальше: → Кастомные вебхуки
Связано: Публичный API · Роли и права
Не получилось? → напиши в саппорт