MCP-сервіс Adset

Платформа Adset.Pro надає публічний MCP-сервіс (Model Context Protocol), який дозволяє мовним моделям (ChatGPT, Claude та сумісним клієнтам) безпосередньо запитувати вашу статистику з Adset.Pro.

Доступні інструменти (tools):

Базовий URL MCP-сервера: https://app.adset.pro/mcp

Підтримуються два способи аутентифікації:

• OAuth 2.0 (PKCE) — для ChatGPT та інших клієнтів, які самі проводять користувача через consent-екран. Підходить для підключення через UI ChatGPT.

• Особистий API-ключ (mcp_…) — для Claude Desktop, Cursor, Claude Code та будь-яких клієнтів з фіксованим Bearer-токеном.

Нижче — покрокові інструкції для обох сценаріїв.

---

Підключення до ChatGPT (OAuth)

ChatGPT встановлює з'єднання з MCP-сервером самостійно через OAuth 2.0 з PKCE. Ніяких токенів вручну копіювати не потрібно — користувач авторизується на adset.pro через стандартний consent-екран.

Крок 1. Увімкніть режим розробника

Цей крок обов'язковий — без режиму розробника пункт «Додати додаток» в налаштуваннях ChatGPT не з'являється.

1. Відкрийте ChatGPT → Налаштування (Settings).

   

2. Перейдіть у розділ Додатки (Apps & Connectors).

   

3. Відкрийте Додаткові налаштування (Advanced settings).

   

4. Увімкніть перемикач Режим розробника (Developer mode).

Крок 2. Додайте додаток AdSet

1. Поверніться в Налаштування → Додатки.

2. Натисніть Додати додаток (Add app / Create).

   

3. Заповніть поля:

   • Name: AdSet

   • Description: AdSet statistics connector

   • MCP server URL: https://app.adset.pro/mcp

   • Authentication: OAuth

4. Натисніть Connect / Add.

Крок 3. Авторизація та згода

ChatGPT відкриє popup-вікно з екраном https://adset.pro/oauth/authorize:

1. Якщо ви ще не увійшли — введіть email та пароль вашого акаунта Adset.Pro.

2. На екрані згоди ви побачите ім'я вашого акаунта та список запитуваних скоупів:

   • stats:query — читання агрегованої статистики

   • stats:meta — читання метаданих (метрики/групи/фільтри)

   • stats:export — експорт CSV

3. Натисніть Approve / Дозволити.

Після схвалення вікно закриється автоматично. Додаток в налаштуваннях ChatGPT перейде в статус Connected.

Крок 4. Використання

Відкрийте новий чат і попросіть ChatGPT скористатися інструментом, наприклад:

«Покажи статистику по кампаніям за останні 7 днів через AdSet — кліки, витрати, ROI».

ChatGPT автоматично викличе query_stats з правильними параметрами і відобразить таблицю.

Відкликання доступу

Щоб відкликати токен у ChatGPT:

• В ChatGPT: Налаштування → Додатки → AdSet → Disconnect.

• На стороні AdSet: Налаштування профілю → MCP Keys — виданий OAuth-клієнт буде відображатися в списку (розділ OAuth clients з'являється тільки якщо у вас є такі підключення).

---

Підключення до Claude (особистий API-токен)

Claude Desktop, Claude Code та Cursor підключаються до MCP-сервера по фіксованому Bearer-токену. Цей токен ви випускаєте самостійно в налаштуваннях профілю AdSet.

Повний токен показується тільки один раз — відразу після створення. Збережіть його в надійному місці (менеджер паролів). Відновити його не можна — тільки перевипустити (rotate).

Крок 1. Випуск API-ключа в Adset.Pro

1. Увійдіть в кабінет AdSet: https://adset.pro.

2. У правому верхньому куті натисніть на аватар → Налаштування (Settings).

   

3. Відкрийте вкладку Ключі MCP.

   

4. Натисніть кнопку Створити API ключ.

5. Заповніть форму:

   • Name — довільне ім'я ключа, наприклад Claude Desktop.

   • Scopes — залиште всі три (Query Stats, Get Metadata, Export CSV) або обмежте за необхідності.

   • Expires in — термін дії в днях. Залиште порожнім для безстрокового ключа.

6. Натисніть Create.

   

7. З'явиться діалог з одноразовим показом токена в форматі:

   mcp_a1b2c3d4e5f6...
   

   Скопіюйте його кнопкою Copy і закрийте діалог.

Крок 2. Підключення в Claude Desktop

Claude Desktop читає MCP-сервери з конфігураційного файлу:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

Відкрийте файл (створіть, якщо його немає) і додайте секцію mcpServers:

{
  "mcpServers": {
    "adset": {
      "type": "http",
      "url": "https://app.adset.pro/mcp",
      "headers": {
        "Authorization": "Bearer mcp_ВАШ_ТОКЕН_ТУТ"
      }
    }
  }
}

Збережіть файл і повністю перезапустіть Claude Desktop (Quit, не просто закрити вікно).

Після запуску внизу вікна чату повинна з'явитися іконка інструментів AdSet (query_stats, get_metadata, export_csv).

Крок 3. Підключення в Claude Code (CLI)

claude mcp add adset \
  --transport http \
  --url https://app.adset.pro/mcp \
  --header "Authorization: Bearer mcp_ВАШ_ТОКЕН_ТУТ"

Перевірка:

claude mcp list

У списку повинен з'явитися запис adset зі статусом connected.

Крок 4. Підключення в Cursor

1. Cursor → Settings → MCP → Add new MCP server.

2. Введіть:

   • Name: adset

   • Type: http

   • URL: https://app.adset.pro/mcp

   • Headers:

     • Key: Authorization

     • Value: Bearer mcp_ВАШ_ТОКЕН_ТУТ

3. Збережіть і перезапустіть Cursor.

Крок 5. Перевірка з'єднання через curl

Якщо щось не працює, швидка перевірка з терміналу:

curl -i https://app.adset.pro/mcp \
  -H "Authorization: Bearer mcp_ВАШ_ТОКЕН"

Очікувана відповідь — 200 OK або 400 Bad Request (без тіла MCP-запиту). Відповідь 401 Unauthorized означає, що токен неправильний, відкликаний або прострочений.

Управління ключами

В розділі Налаштування профілю → MCP Keys доступні:

• Створення нових ключів (Create API Key).

• Перевипуск (rotate, іконка ↻) — старий токен одразу відкликається, видається новий.

• Відкликання (Delete, іконка кошика) — токен негайно перестає працювати.

• Перегляд імені, префікса, скоупів, статусу, часу останнього використання та терміну дії.

---

Скоупи та обмеження

Будь-який запит автоматично застосовує фільтри безпеки по teamId та ролі користувача — клієнт отримує тільки ті дані, до яких у нього є доступ в кабінеті.

Ліміти:

• query_stats.limit — максимум 1000 рядків за запит; для великих вибірок використовуйте export_csv.

• export_csv — м'який ліміт 100 000 рядків (можна розширити під окремі тарифи).

---

Часті помилки

---

Корисні посилання

• Публічна OpenAPI-специфікація: https://app.adset.pro/openapi.json

• OAuth Authorization Server Metadata: https://app.adset.pro/.well-known/oauth-authorization-server

• OAuth Protected Resource Metadata: https://app.adset.pro/.well-known/oauth-protected-resource