1. Что это такое
DirectAlert MCP позволяет AI-агенту читать документацию и работать с данными Яндекс Директа в рамках прав пользователя и выбранного Workspace.
Публичный каталог теперь source-based: текущие инструменты — documentation_get и direct. Будущие Bitrix и Метрика добавляются отдельными source tools, когда для них есть handlers, docs и проверки.
2. Подключение в Codex
Codex хранит MCP-настройки в config.toml. Для пользовательского подключения DirectAlert добавьте сервер в ~/.codex/config.toml:
[mcp_servers.DirectAlert]
url = "https://direct-alert.ru/mcp"После этого запустите вход:
codex mcp login DirectAlertНе отправляйте агенту пароли, токены и другие секретные данные. Вход выполняется через браузер.
3. Workflow агента
- Discover tools: агент должен увидеть только documentation_get и direct.
- Если action неизвестен, агент вызывает documentation_get с source=direct и mode=index.
- Для точных параметров агент вызывает documentation_get с source=direct и action=<action>.
- Сначала агент вызывает direct action session.context.
- Затем агент выбирает Workspace и вызывает direct action accounts.list.
- Дальше агент вызывает direct с action, common scope fields и args.
direct({
"action": "campaigns.list",
"workspace_id": 2,
"account_id": 1,
"provider_mode": "auto",
"args": {
"limit": 3,
"view": "summary"
}
})Старый bootstrap с get_ready, созданием AGENTS.md, русских папок и audit-doc больше не является публичным MCP-контрактом.
4. Public tools
| Tool | Назначение |
|---|---|
| documentation_get | Читает file-backed source/action документацию. |
| direct | Выполняет documented Direct source actions через action + args. |
5. Direct actions
Полный список actions агент получает через documentation_get({source:"direct", mode:"index"}). Ниже ключевые actions, которые чаще всего нужны для проверки подключения и анализа.
| Action | Назначение |
|---|---|
| session.context | Получить пользователя и доступные Workspace. |
| accounts.list | Получить аккаунты в выбранном Workspace. |
| campaigns.list | Получить список кампаний. |
| campaign.get | Получить одну кампанию по campaign_id. |
| reports.capabilities | Получить поля и правила Direct Reports. |
| reports.submit | Проверить или поставить offline-отчёт; для безопасной проверки используйте dry_run. |
| reports.get | Получить статус и страницу результата отчёта. |
| budgets.get | Получить бюджеты Direct. |
| changes.check | Проверить изменения Direct через read-only Changes methods. |
| snapshots.list | Найти доступные JSON-снапшоты аккаунта. |
| snapshots.links.get | Получить временные ссылки на ready-снапшоты. |
| snapshots.request | Поставить или дедуплицировать запрос на сбор снапшота. |
| raw.get | Экспертный read-only запрос к Direct API по allowlist. |
6. Документация
MCP-документация хранится файлами Markdown с TOML frontmatter внутри backend_v2. documentation_get возвращает index, section, action-card или lexical search candidates.
Default output компактный: index отдаёт refs, а не весь manual. Примеры и schema запрашиваются отдельно.
7. Безопасность
- Workspace/account scope проверяется на каждом action.
- account_id — внутренний идентификатор DirectAlert из accounts.list.
- Не передавайте OAuth/access/refresh tokens, cookies, Authorization headers, API keys, private keys и passwords.
- raw.get ограничен read-only allowlist Direct API.
- snapshots.request и reports.submit используют idempotent/request-flow; для отчётов безопасная проверка выполняется через dry_run.
8. Частые проблемы
Агент не видит инструменты
Проверьте, что MCP-сервер DirectAlert добавлен, вход выполнен, а клиент MCP обновил список инструментов. Актуальный каталог должен показывать documentation_get и direct.
Нет аккаунтов
Проверьте, что аккаунты добавлены в DirectAlert и выбран правильный Workspace. Агент должен сначала вызвать session.context, затем accounts.list.