> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nudgen.net/llms.txt
> Use this file to discover all available pages before exploring further.
# Сервер MCP
> Подключите ИИ-ассистента к Nudgen через OAuth, ищите потенциальных клиентов на карте и подтверждайте запуск кампаний в браузере
## Обзор
Nudgen размещает сервер MCP по конечной точке `/mcp` на домене вашего приложения. Он поддерживает MCP `2026-07-28` через Streamable HTTP и требует OAuth 2.1. Подключите клиент, который поддерживает этот транспорт. Войдите в Nudgen в браузере, выберите рабочее пространство и подтвердите разрешения, запрашиваемые клиентом. Подключение останется привязанным к этому рабочему пространству, даже если позже вы переключитесь на другое в дашборде.
## Почему это важно
Ваш ассистент может просматривать контакты и кампании, находить компании поблизости, создавать черновики контента и подготавливать кампанию к запуску без доступа к сессии дашборда или токену личного доступа. Перед фактической отправкой или планированием вы подтверждаете действие в браузере.
## Подключение клиента
Рабочая конечная точка:
```text theme={null}
https://app.nudgen.net/mcp
```
Добавьте ее в клиент с поддержкой OAuth как **удаленный HTTP-сервер MCP**. Клиент обнаружит сервер авторизации Nudgen через эту конечную точку и откроет в браузере процесс входа и предоставления согласия. Выберите рабочее пространство, к которому клиент должен получить доступ, и подтвердите только необходимые области доступа.
Документы обнаружения:
| Документ | URL |
| - | - |
| Метаданные защищенного ресурса | `https://app.nudgen.net/.well-known/oauth-protected-resource/mcp` |
| Сервер авторизации | `https://app.nudgen.net/mcp-oauth` |
| Карточка сервера | `https://app.nudgen.net/.well-known/mcp/server-card.json` |
Сервер авторизации использует код авторизации с PKCE S256, привязку к ресурсу и ротацию токенов обновления. Он поддерживает документы метаданных Client ID и динамическую регистрацию клиентов.
Для Codex CLI используйте:
```bash theme={null}
codex mcp add nudgen --url "https://app.nudgen.net/mcp" --oauth-resource "https://app.nudgen.net/mcp"
codex mcp login nudgen --scopes campaigns:read,campaigns:write,campaigns:send
```
Если клиент с именем `nudgen` уже настроен, обновите его запись, указав URL `/mcp`.
| Область доступа | Что она разрешает |
| - | - |
| `campaigns:read` | Просматривать рабочее пространство, контакты, кампании и настройки бренда, а также искать потенциальных клиентов на карте. |
| `campaigns:write` | Создавать контакты и черновики кампаний, обновлять настройки бренда, генерировать черновики с помощью ИИ и импортировать потенциальных клиентов с карты. |
| `campaigns:send` | Запрашивать и завершать запуск. Сама по себе эта область доступа никогда не отправляет письма. |
Если вам нужно только просматривать данные, запросите `campaigns:read`. Добавьте `campaigns:write`, если клиент должен изменять контакты, черновики, настройки бренда или импортированных потенциальных клиентов. Добавляйте `campaigns:send`, только если клиенту требуется запрашивать подтверждение запуска.
Токены личного доступа используются для аутентификации в [API разработчика](/ru/agents/api), но не подходят для `/mcp`. Клиент MCP должен пройти вход через OAuth.
## Доступные инструменты
| Задача | Инструменты | Область доступа |
| - | - | - |
| Просмотр рабочего пространства | `get_current_user`, `list_contacts`, `list_campaigns`, `get_campaign`, `get_campaign_stats`, `get_brand_settings` | `campaigns:read` |
| Поиск компаний поблизости | `search_map_leads` | `campaigns:read` |
| Создание и редактирование | `create_contact`, `create_campaign`, `update_brand_settings`, `generate_email_draft`, `import_map_leads` | `campaigns:write` |
| Запрос и завершение запуска | `prepare_campaign_launch`, `launch_campaign` | `campaigns:send` |
`create_campaign` сохраняет **черновик разовой кампании**. Этот инструмент не может напрямую отправить или запланировать кампанию. С помощью `get_campaign` можно проверить тему, содержимое, ссылку, аудиторию и отправителя перед запуском.
Сервер также предоставляет ресурсы только для чтения в области доступа `campaigns:read`:
| Ресурс | Содержимое |
| - | - |
| `nudgen://api-catalog` | Названия и описания доступных инструментов. |
| `nudgen://team/brand` | Настройки бренда подключенного рабочего пространства. |
| `nudgen://campaigns/{id}/summary` | Статистика доставки одной кампании. Замените `{id}` идентификатором кампании. |
### Поиск и импорт потенциальных клиентов с карты
1. Попросите ассистента вызвать `search_map_leads`, указав местоположение и ключевые слова для поиска компаний, например город и `marketing agency`.
2. Дополнительные фильтры: `radiusKm` (1–100), `lat`, `lng` и `emailOnly`, чтобы оставить только компании с опубликованным email-адресом.
3. Если результат содержит `nextPageToken`, передайте его как `pageToken`, чтобы загрузить следующую страницу.
4. Попросите ассистента вызвать `import_map_leads` с теми же местоположением и ключевыми словами, а также объектами потенциальных клиентов, которые нужно сохранить. Один вызов принимает до 200 потенциальных клиентов.
При импорте контакты записываются в подключенное рабочее пространство. Потенциальные клиенты без email-адреса пропускаются. Если такой потенциальный клиент уже существует, его данные обновляются.
### Подтверждение запуска кампании
1. Попросите ассистента проверить черновик с помощью `get_campaign`.
2. Попросите его вызвать `prepare_campaign_launch`, передав идентификатор кампании и точное время немедленной или запланированной отправки. Инструмент вернет одноразовый URL подтверждения; на этом этапе письма еще не отправляются.
3. Откройте URL, проверьте рабочее пространство, расчетное количество получателей, содержимое, отправителя и время, затем нажмите **Подтвердить запуск**.
4. Вернитесь в клиент, чтобы он вызвал `launch_campaign` с теми же идентификатором кампании, временем и `approvalId`.
Подтверждение действует **10 минут** и может быть использовано один раз. Если кампания или отправитель изменились, запросите новое подтверждение. При запуске Nudgen повторно проверяет готовность отправителя, подходящих получателей, подписку, квоту и доступность очереди. Доставка начнется только после того, как обработчик кампаний обработает запуск.
Подтверждение и завершение `launch_campaign` могут привести к отправке реальных писем. Перед подтверждением отправки реальной аудитории используйте функцию тестовой отправки в дашборде, чтобы проверить письмо во входящих.
## Управление доступом
Откройте **Настройки** → **Ключи API** → **Подключенные приложения MCP**, чтобы просмотреть рабочее пространство и области доступа каждого подключенного клиента. Отзовите подключение, если доступ больше не нужен. При отзыве отключаются его токены и ожидающие подтверждения запуска. Позже можно снова подключиться через OAuth.
Разрешения OAuth действуют не более 90 дней. Если вы потеряете доступ к рабочему пространству, клиент также не сможет использовать подключение к нему.
## Устранение неполадок
| Симптом | Что делать |
| - | - |
| Вход не начинается | Убедитесь, что клиент поддерживает удаленный MCP через Streamable HTTP с OAuth и использует `https://app.nudgen.net/mcp`. |
| Инструменту нужны дополнительные разрешения | Подключитесь заново и подтвердите нужную область доступа для этого рабочего пространства. |
| Поиск контактов просит сузить результаты | Поиск сопоставляет имена и email-адреса и проверяет не более 5 000 контактов после фильтрации по тегам и статусу. Сузьте фильтры. |
| При импорте с карты компания пропускается | Сохраняются только потенциальные клиенты с email-адресом. Повторите поиск с `emailOnly: true` или выберите записи, в которых уже есть email-адрес. |
| Срок подтверждения запуска истек или кампания изменилась | Запросите новое подтверждение и еще раз проверьте текущую кампанию и отправителя. |
| Запуск заблокирован | Проверьте статус черновика кампании, готовность отправителя, подходящие контакты, квоту тарифного плана и [домен отправителя](/ru/settings/sending-domains). |
Для сценариев, использующих bearer-токены и прямые конечные точки REST, см. [API разработчика](/ru/agents/api).