> For the complete documentation index, see [llms.txt](https://docs.umg.team/main/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.umg.team/main/udsp.io/udsp-mcp.md).

# uDSP MCP

Документация для пользователей, которые подключают ИИ-агентов к рекламной платформе uDSP через протокол Model Context Protocol (MCP).

### Что это такое

uDSP MCP — сервер по протоколу [Model Context Protocol](https://modelcontextprotocol.io), который дает ИИ-агенту (Claude, ChatGPT, Gemini и любому другому MCP-совместимому клиенту) прямой доступ к данным и операциям платформы uDSP: кампании, таргетинг, статистика, инвентарь, финансы.

Вместо работы через веб-кабинет или интеграции с REST API вы формулируете задачу на естественном языке, а агент сам выбирает нужные инструменты сервера и выполняет запрос. Часть инструментов только читает данные, часть — создает и изменяет кампании напрямую на платформе.

**Адрес сервера:** `https://mcp.udsp.io/mcp`

### Подключение

1. В настройках MCP-коннекторов вашего клиента (Claude, ChatGPT и другие) добавьте новый сервер по адресу `https://mcp.udsp.io/mcp`.
2. Пройдите авторизацию — вход по учетным данным аккаунта uDSP через OAuth.
3. Убедитесь, что коннектор включен для того чата или агента, в котором собираетесь работать.
4. Сформулируйте задачу на естественном языке, например: «покажи активные кампании рекламодателя за последнюю неделю» или «почему кампания 12345 не откручивается».

Если агент сообщает, что инструменты uDSP недоступны, хотя раньше подключение работало,  скорее всего истекла или была отозвана авторизация. В этом случае нужно заново пройти авторизацию (шаг 2).

### Уровни доступа

Набор видимых данных зависит от типа токена:

| Тип токена                                | Что видно                                                                                           |
| ----------------------------------------- | --------------------------------------------------------------------------------------------------- |
| Advertiser                                | Только кампании и финансы своего рекламодателя                                                      |
| Staff (сотрудник платформы или агентства) | Кампании всех доступных клиентов; можно сузить выборку параметрами `client_user_id` или `agency_id` |

### Справочник инструментов

#### Кампании

| Инструмент             | Назначение                                                                                                                                     |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `list_campaigns`       | Список кампаний с фильтрами по статусу, паузе, рекламодателю, агентству, группе кампаний; базовые метрики (потрачено, показы, клики, CTR, CPC) |
| `get_campaign`         | Полная карточка одной кампании: бюджет, стратегия ставки, таргетинг, минус-таргетинг                                                           |
| `get_campaign_history` | История изменений кампании с возможностью восстановить конфигурацию на любой момент времени                                                    |

#### Таргетинг

| Инструмент                | Назначение                                                                                      |
| ------------------------- | ----------------------------------------------------------------------------------------------- |
| `get_campaigns_targeting` | Таргетинг сразу по нескольким кампаниям одним запросом, с человекочитаемыми названиями регионов |
| `update_targeting` ⚠️     | Изменяет таргетинг и минус-таргетинг действующей кампании                                       |

#### Статистика и аналитика

| Инструмент                  | Назначение                                                                                          |
| --------------------------- | --------------------------------------------------------------------------------------------------- |
| `get_campaign_stats`        | Отчет по кампании: всего / по дням / по регионам / по месяцам, с опциональной финансовой раскладкой |
| `get_campaign_period_stats` | График по кампании за период от 10 минут до 31 дня: показы, клики, траты, CTR, CPC, CPM             |
| `get_creative_stats`        | Статистика по креативам внутри кампании с разбивкой по дням                                         |

#### Ставки и диагностика доставки

| Инструмент                   | Назначение                                                                                                                                                  |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `get_campaign_bidstat`       | Статистика по ставкам и причинам отказа на уровне RTB-аукциона за 5 минут, час или сутки                                                                    |
| `diagnose_campaign_delivery` | Сводная диагностика: почему кампания не откручивается или откручивается плохо — баланс, лимиты показов, доставка по площадкам, история изменений таргетинга |

#### Инвентарь и размещения

| Инструмент                         | Назначение                                                                                                                                                             |
| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `get_campaign_placement_delivery`  | Где кампания реально показывалась: площадки и домены, с фильтрами по гео и устройству                                                                                  |
| `get_campaign_placement_inventory` | Доступный объем и цена инвентаря по площадкам, на которые таргетирована кампания                                                                                       |
| `list_inventory_placements`        | Инвентарь всей платформы с группировкой до двух измерений: SSP, домен, web/app, видео/баннер, устройство, страна, регион, день, месяц, приложение, тип видеоразмещения |

#### Финансы

| Инструмент           | Назначение                                                   |
| -------------------- | ------------------------------------------------------------ |
| `get_client_balance` | Баланс рекламодателя: начисленный бюджет, потрачено, остаток |

#### Управление кампаниями

Эти инструменты не читают, а меняют данные на платформе — действие применяется сразу, без дополнительного подтверждения в интерфейсе.

| Инструмент            | Назначение                                      |
| --------------------- | ----------------------------------------------- |
| `create_campaign` ⚠️  | Создает новую кампанию по заданной конфигурации |
| `pause_campaign` ⚠️   | Ставит кампанию на паузу                        |
| `resume_campaign` ⚠️  | Возобновляет показ кампании                     |
| `archive_campaign` ⚠️ | Архивирует кампанию                             |

### Пример использования

Запрос агенту:

> Проверь, почему кампания 12345 не откручивается последние два дня, и покажи баланс рекламодателя

Агент вызовет `diagnose_campaign_delivery` и `get_client_balance`, сопоставит причины отказа ставок, лимиты показов и остаток бюджета и вернет ответ на естественном языке с указанием конкретной причины, а не просто нулевые показатели.

### Ограничения

* Отчеты по статистике и инвентарю ограничены периодом 31 день и 500 строками на один запрос; для более длинных периодов или широких разрезов запрос нужно разбивать на части.
* Гео принимает ISO2-код страны, название страны или макро-регион СНГ; страна и макро-регион в одном запросе одновременно не принимаются.
* В группировке инвентаря и размещений нельзя сочетать `host` и `domain`, `app_name` и `domain`, а также указывать больше двух измерений одновременно.
* Данные о доступном инвентаре (`get_campaign_placement_inventory`, `list_inventory_placements`) и данные о фактической доставке (`get_campaign_placement_delivery`) — разные отчеты: первые показывают потенциал площадки, вторые — что было показано в реальности.

### Поддержка

По вопросам подключения и работы uDSP MCP обращайтесь в службу поддержки UMG.team.