Instructions : Intégration de Spy.House via MCP

Ce guide est consacré à la configuration et à l'utilisation de l'intégration du service d'analyse de créatives publicitaires Spy.House avec les clients IA et les environnements de développement via le protocole Model Context Protocol (MCP).

Ce document détaille les prérequis de connexion (abonnement payant actif et autorisation OAuth sans clé API), l'algorithme de base en trois étapes pour lancer l'intégration, ainsi que des instructions pas à pas pour configurer des applications spécifiques : Claude (Desktop, Web, Code), Codex, Cursor, VS Code et ChatGPT.

Informations importantes avant la connexion

• URL du connecteur (Connector URL) : [https://spy.house/mcp]. Cet URL doit être inséré dans votre client MCP.

• Exigences : Un abonnement payant actif est requis. La version d'essai (trial) ne peut pas être connectée.

• Autorisation : S'effectue via OAuth — votre client ouvre un navigateur et vous vous connectez avec votre compte Spy.House. Aucune clé API n'est requise.

3 étapes pour se connecter

1. Ajoutez le serveur (Add the server) : Orientez votre client MCP vers l'URL du connecteur - il s'agit d'une seule ligne de configuration ou commande (voir ci-dessous).

2. Connectez-vous avec Spy.House (Sign in with Spy.House) : Votre client ouvrira un navigateur pour l'autorisation OAuth.

3. Interrogez votre agent (Ask your agent) : Rédigez une requête, par exemple : « Find up to 12 Black Friday FB creatives for the USA ». L'agent appellera l'outil nécessaire et répondra.

Configuration pour des clients spécifiques

Remarque pour les clients CLI (Claude Code, Codex) : Après avoir ajouté le serveur, vous devez redémarrer le client, car la session en cours ne le chargera pas. Effectuez ensuite la connexion : pour Claude Code à l'aide de la commande /mcp, pour Codex avec la commande codex mcp login spy-house (issue du bloc ci-dessous).

1. Claude

Les versions desktop et web utilisent le Client ID indiqué ci-dessous. Claude Code использует une commande CLI avec son propre Client ID.

Desktop / Web :

1. Accédez à Settings (Paramètres) → Connectors (Connecteurs) → Add custom connector (Ajouter un connecteur personnalisé).

2. Insérez l'URL du point de terminaison (endpoint URL).

3. Cliquez sur Connect & authorize (Connecter et autoriser).

Claude Code (CLI) : Exécutez la commande :

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

Client ID pour Desktop/Web : spy-mcp-claude-desktop

2. Codex

Ajoutez le serveur distant à l'aide d'une seule commande, puis connectez-vous au système.

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

Exécutez la commande ci-dessous ou ajoutez le serveur dans le fichier ~/.cursor/mcp.json ou .cursor/mcp.json.

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

Exécutez la commande ci-dessous ou ajoutez le serveur dans le fichier mcp.json utilisateur ou mcp.json de votre espace de travail (workspace).

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. Ouvrez Claude → Customize → Connectors → Add custom connector.

2. Indiquez : Name — Spy.House, URL — [https://spy.house/mcp].

3. Dans Advanced OAuth settings, indiquez le Client ID spy-mcp-claude-desktop ; laissez Client Secret vide.

4. Cliquez sur Add / Connect.

6. ChatGPT

1. Dans ChatGPT web, activez Settings → Security and login → Developer mode.

2. Ajoutez une application MCP distante (remote MCP app) dans Plugins : URL [https://spy.house/mcp], Client ID spy-mcp-chatgpt, Streamable HTTP, sans Client Secret (no Client Secret).

3. Cliquez sur Connect / Authenticate, connectez-vous à Spy.House et confirmez l'accès. Aucune clé API ni Client Secret ne sont requis.

4. Exécutez cette requête : > Find up to 12 Black Friday FB creatives for the US.

Vérification par requête (Verification by request)

Après vous être connecté, exécutez ces requêtes dans votre client. Les résultats attendus constituent une liste de contrôle et non une recherche en direct.

• search_creatives

  • Requête de vérification : Find up to 12 Black Friday Facebook ad creatives for the US.

  • Résultat attendu : Jusqu'à 12 créatives, incluant les données et le quota de recherche restant. Le réseau est limité à un seul par appel : push, inpage, facebook, tiktok ou native. Chaque recherche non vide consomme une unité de quota.

• get_filter_options

  • Requête de vérification : List the available Facebook search filters.

  • Résultat attendu : Catalogue de filtres Facebook hors contenu pour adultes (non-adult) et valeurs exactes pour search_creatives. Les filtres pour adultes sont masqués.

• get_creative_media

  • Requête de vérification : Show me the images of the creatives you just found.

  • Résultat attendu : Médias pour jusqu'à trois creative_ref issus de cette recherche. Le quota de recherche n'est pas débité. La vidéo complète n'est pas renvoyée et le chat peut ne pas afficher d'aperçu intégré.

• render_creatives_gallery

  • Requête de vérification : Show these creatives as a gallery.

  • Résultat attendu : Galerie intégrée de 1 à 12 creative_ref provenant de la même recherche dans les clients prenant en charge les MCP Apps. Les autres clients ignorent cet outil et utilisent du texte ou get_creative_media.

Foire aux questions (FAQ)

Comment déconnecter Spy.House de votre client IA ?

Supprimez ou désactivez le serveur Spy.House dans votre client IA. L'accès prend également fin à l'expiration de votre abonnement payant. Les comptes d'essai ne peuvent pas se connecter.

Comment contacter le service client ?

• Email : [email protected]

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

• Horaires du support : Du lundi au vendredi, de 10h00 à 18h00 (UTC+3)

En cas d'erreur, veuillez envoyer : le nom du client IA, l'heure, le texte de l'erreur et une capture d'écran.

L'intégration de Spy.House via le protocole MCP transforme les assistants IA et les environnements de développement populaires en un outil performant de veille concurrentielle. Grâce à une autorisation OAuth transparente et à un connecteur unique, les utilisateurs peuvent rechercher des créatives publicitaires, analyser les filtres disponibles et consulter des fichiers médias directement depuis l'interface de leur client habituel, réduisant le processus de recherche à de simples requêtes en langage naturel.