Instrucciones: Integración de Spy.House mediante MCP

Esta guía está dedicada a la configuración y uso de la integración del servicio de analítica de creativos publicitarios Spy.House con clientes de IA y entornos de desarrollo a través del protocolo Model Context Protocol (MCP).

En el material se detallan los requisitos previos para la conexión (tener una suscripción de pago activa y autorización OAuth sin uso de claves API), el algoritmo básico de tres pasos para iniciar la integración, así como instrucciones paso a paso para configurar aplicaciones específicas: Claude (Desktop, Web, Code), Codex, Cursor, VS Code y ChatGPT.

Información importante antes de la conexión

• URL del conector (Connector URL): [https://spy.house/mcp]. Esta URL debe insertarse en su cliente MCP.

• Requisitos: Se requiere una suscripción de pago activa. La versión de prueba (trial) no se puede conectar.

• Autorización: Se realiza mediante OAuth: su cliente abre el navegador y usted inicia sesión con su cuenta de Spy.House. No se requiere clave API.

3 pasos para la conexión

1. Añada el servidor (Add the server): Apunte su cliente MCP a la URL del conector; es una sola línea de configuración o comando (ver abajo).

2. Inicie sesión con Spy.House (Sign in with Spy.House): Su cliente abrirá el navegador para la autorización OAuth.

3. Pregunte a su agente (Ask your agent): Escriba una solicitud, por ejemplo: «Find up to 12 Black Friday FB creatives for the USA». El agente invocará la herramienta adecuada y responderá.

Configuración para clientes específicos

Nota para clientes CLI (Claude Code, Codex): Tras añadir el servidor, es necesario reiniciar el cliente, ya que la sesión en ejecución no lo cargará. A continuación, inicie sesión: para Claude Code con el comando /mcp, para Codex con el comando codex mcp login spy-house (del bloque de abajo).

1. Claude

Las versiones de escritorio y web utilizan el Client ID indicado abajo. Claude Code utiliza un comando CLI con su propio Client ID.

Desktop / Web:

• Vaya a Settings (Configuración) → Connectors (Conectores) → Add custom connector (Añadir conector personalizado).

• Inserte la URL del endpoint.

• Haga clic en Connect & authorize (Conectar y autorizar).

Claude Code (CLI): Ejecute el comando:

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

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

2. Codex

Añada el servidor remoto con un solo comando y, a continuación, inicie sesión:

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

Ejecute el siguiente comando o añada el servidor al archivo ~/.cursor/mcp.json o .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

Ejecute el siguiente comando o añada el servidor al mcp.json del usuario o al mcp.json del área de trabajo (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

• Abra Claude → Customize → Connectors → Add custom connector.

• Especifique: Name — Spy.House, URL - [https://spy.house/mcp].

• En Advanced OAuth settings, especifique el Client ID spy-mcp-claude-desktop; deje Client Secret en blanco.

• Haga clic en Add / Connect.

6. ChatGPT

• En ChatGPT web, active Settings → Security and login → Developer mode.

• Añada la aplicación remota (remote MCP app) en Plugins: URL [https://spy.house/mcp], Client ID spy-mcp-chatgpt, Streamable HTTP, sin Client Secret (no Client Secret).

• Haga clic en Connect / Authenticate, inicie sesión en Spy.House y confirme el acceso. No se requieren clave API ni Client Secret.

• Ejecute la siguiente consulta: > Find up to 12 Black Friday FB creatives for the US.

Verificación mediante solicitudes (Verification by request)

Tras la conexión, ejecute estas consultas en su cliente. Los resultados esperados son una lista de comprobación, no una búsqueda en vivo.

• search_creatives

  • Consulta de prueba: Find up to 12 Black Friday Facebook ad creatives for the US.

  • Resultado esperado: Hasta 12 creativos, incluyendo datos y la cuota de búsqueda restante. Una red por llamada: push, inpage, facebook, tiktok o native. Cada búsqueda no vacía consume una unidad de cuota.

• get_filter_options

  • Consulta de prueba: List the available Facebook search filters.

  • Resultado esperado: Catálogo de filtros de Facebook sin contenido para adultos (non-adult) y valores exactos para search_creatives. Los filtros para adultos permanecen ocultos.

• get_creative_media

  • Consulta de prueba: Show me the images of the creatives you just found.

  • Resultado esperado: Archivos multimedia de hasta tres creative_ref de esa búsqueda. No se descuenta cuota de búsqueda. No se devuelven vídeos completos y es posible que el chat no muestre una vista previa integrada.

• render_creatives_gallery

  • Consulta de prueba: Show these creatives as a gallery.

  • Resultado esperado: Galería integrada de 1 a 12 creative_ref de la misma búsqueda en clientes compatibles con MCP Apps. El resto de clientes omiten esta herramienta y utilizan texto o get_creative_media.

Preguntas frecuentes (FAQ)

¿Cómo desconectar Spy.House de un cliente de IA?

Elimine o desactive el servidor de Spy.House en su cliente de IA. El acceso también se revoca al expirar la suscripción de pago. Las cuentas de prueba no pueden conectarse.

¿Cómo contactar con el soporte técnico?

• Email: [email protected]

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

• Horario de atención: Lu–Vi, 10:00–18:00 (UTC+3)

En caso de error, por favor envíe: nombre del cliente de IA, hora, texto del error y una captura de pantalla.

La integración de Spy.House a través del protocolo MCP transforma los asistentes de IA y entornos de desarrollo más populares en una eficaz herramienta de inteligencia competitiva. Gracias a la autorización fluida mediante OAuth y a un conector único, los usuarios pueden buscar creativos publicitarios, analizar los filtros disponibles y visualizar archivos multimedia directamente desde la interfaz de su cliente habitual, reduciendo el proceso de búsqueda a simples consultas en lenguaje natural.