Інструкція: Інтеграція Spy.House через MCP

Цей посібник присвячено налаштуванню та використанню інтеграції сервісу аналітики рекламних креативів Spy.House з ШІ-клієнтами та середовищами розробки через протокол Model Context Protocol (MCP).

У матеріалі детально розглядаються попередні вимоги для підключення (наявність платної передплати та OAuth-авторизація без застосування API-ключів), базовий алгоритм із трьох кроків для запуска зв'язки, а також покрокові інструкції з налаштування конкретних застосунків: Claude (Desktop, Web, Code), Codex, Cursor, VS Code та ChatGPT.

Важлива інформація перед підключенням

• URL коннектора (Connector URL): [https://spy.house/mcp]. Цей URL необхідно вставити у ваш MCP-клієнт.

• Вимоги: Потрібна активна платна передплата. Пробна версія (trial) не може бути підключена.

• Авторизація: Виконується через OAuth — ваш клієнт відкриває браузер, і ви входите з обліковим записом Spy.House. API-ключ не потрібен.

3 кроки для підключення

1. Додайте сервер (Add the server): Спрямуйте ваш MCP-клієнт на URL коннектора — це один рядок конфігурації або команда (див. нижче).

2. Увійдіть за допомогою Spy.House (Sign in with Spy.House): Ваш клієнт відкриє браузер для OAuth-авторизації.

3. Запитайте вашого агента (Ask your agent): Напишіть запит, наприклад: «Find up to 12 Black Friday FB creatives for the USA». Агент викличе потрібний інструмент і відповість.

Налаштування для конкретних клієнтів

Примітка для CLI-клієнтів (Claude Code, Codex): Після додавання сервера необхідно перезапустити клієнт, оскільки запущена сесія його не завантажить. Потім виконайте вхід: для Claude Code за допомогою команди /mcp, для Codex — командою codex mcp login spy-house (із блоку нижче).

1. Claude

Десктопна та вебверсія використовують Client ID, вказаний нижче. Claude Code використовує CLI-команду зі своїм власним Client ID.

• Desktop / Web:

  1. Перейдіть у Settings (Налаштування) → Connectors (Коннектори) → Add custom connector (Додати користувацький коннектор).

  2. Вставте endpoint URL.

  3. Натисніть Connect & authorize (Підключити та авторизувати).

• Claude Code (CLI): Виконайте команду:

  Bash
  
  

  claude mcp add --transport http --client-id spy-mcp-claude-code \
  --callback-port 8787 spy-house https://spy.house/mcp
  

  
  
  
  

• Client ID для Desktop/Web: spy-mcp-claude-desktop

2. Codex

Додайте віддалений сервер за допомогою однієї команди, потім увійдіть у систему.

Bash

codex mcp add spy-house --url https://spy.house/mcp \
--oauth-client-id spy-mcp-codex

codex mcp login spy-house

• Client ID: spy-mcp-codex

3. Cursor

Виконайте команду нижче або додайте сервер у файл ~/.cursor/mcp.json або .cursor/mcp.json.

Bash

cursor --add-mcp '{"name":"spy-house","url":"https://spy.house/mcp","auth":{"CLIENT_ID":"spy-mcp-cursor","scopes":["mcp:search"]}}'

• Client ID: spy-mcp-cursor

4. VS Code

Виконайте команду нижче або додайте сервер у користувацький mcp.json або mcp.json робочої області (workspace).

Bash

code --add-mcp '{"name":"spy-house","type":"http","url":"https://spy.house/mcp","oauth":{"clientId":"spy-mcp-vscode"}}'

• Client ID: spy-mcp-vscode

5. Claude Web

1. Відкрийте Claude → Customize → Connectors → Add custom connector.

2. Укажіть: Name — Spy.House, URL — [https://spy.house/mcp].

3. В Advanced OAuth settings укажіть Client ID spy-mcp-claude-desktop; залиште Client Secret порожнім.

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

6. ChatGPT

1. У ChatGPT web увімкніть Settings → Security and login → Developer mode.

2. Додайте віддалений застосунок (remote MCP app) у Plugins: URL [https://spy.house/mcp], Client ID spy-mcp-chatgpt, Streamable HTTP, без Client Secret (no Client Secret).

3. Натисніть Connect / Authenticate, увійдіть у Spy.House та підтвердіть доступ. API-ключ і Client Secret не потрібні.

4. Виконайте цей запит: > Find up to 12 Black Friday FB creatives for the US.

Перевірка за запитом (Verification by request)

Після підключення виконайте ці запити у вашому клієнті. Очікувані результати — це контрольний список, а не живий пошук.

• search_creatives

  • Запит для перевірки: Find up to 12 Black Friday Facebook ad creatives for the US.

  • Очікуваний результат: До 12 креативів, включаючи дані та залишок квоти на пошук. Одна мережа на виклик: push, inpage, facebook, tiktok або native. Кожен непорожній пошук споживає одну одиницю квоти.

• get_filter_options

  • Запит для перевірки: List the available Facebook search filters.

  • Очікуваний результат: Каталог фільтрів Facebook без контенту для дорослих (non-adult) та точні значення для search_creatives. Фільтри для дорослих приховані.

• get_creative_media

  • Запит для перевірки: Show me the images of the creatives you just found.

  • Очікуваний результат: Медіа до трьох creative_ref з цього пошуку. Квота пошуку не списується. Повне відео не повертається, і чат може не відображати вбудоване прев'ю.

• render_creatives_gallery

  • Запит для перевірки: Show these creatives as a gallery.

  • Очікуваний результат: Вбудована галерея з 1–12 creative_ref з того ж пошуку в клієнтах, які підтримують MCP Apps. Інші клієнти пропускають цей інструмент і використовують текст або get_creative_media.

Часті запитання (FAQ)

Як відключити Spy.House від AI-клієнта?

Видаліть або вимкніть сервер Spy.House в AI-клієнті. Доступ також припиняється після закінчення терміну платної передплати. Пробні облікові записи не можуть підключатися.

Як зв'язатися зі службою підтримки?

• Email: [email protected]

• Telegram: https://telegram.me/Spy_House

• Години роботи підтримки: Пн–Пт, 10:00–18:00 (UTC+3)

У разі виникнення помилки, будь ласка, надішліть: назву ШІ-клієнта, час, текст помилки та скріншот.

Інтеграція Spy.House через протокол MCP перетворює популярні ШІ-асистенти та середовища розробки на ефективний інструмент конкурентної розвідки. Завдяки безшовній OAuth-авторизації та єдиному коннектору користувачі отримують можливість шукати рекламні креативи, аналізувати доступні фільтри й переглядати медіафайлы безпосередньо з інтерфейсу своего звичного клієнта, скорочуючи процес пошуку до простих запитів природною мовою.