Instruções: Integrar o Spy.House via MCP

Este guia é dedicado à configuração e uso da integração do serviço de análise de criativos publicitários Spy.House com clientes de IA e ambientes de desenvolvimento por meio do protocolo Model Context Protocol (MCP).

O material detalha os pré-requisitos para conexão (existência de assinatura paga e autorização OAuth sem necessidade de chaves de API), o algoritmo básico de três etapas para iniciar a integração, além de instruções passo a passo para configurar aplicações específicas: Claude (Desktop, Web, Code), Codex, Cursor, VS Code e ChatGPT.

Informações importantes antes de conectar

• URL do conector (Connector URL): [https://spy.house/mcp]. Esta URL deve ser inserida no seu cliente MCP.

• Requisitos: É necessária uma assinatura paga ativa. A versão de teste (trial) não pode ser conectada.

• Autorização: Realizada via OAuth — seu cliente abre o navegador e você faz login com a sua conta do Spy.House. Não é necessária chave de API.

3 etapas para conexão

1. Adicione o servidor (Add the server): Aponte seu cliente MCP para a URL do conector - trata-se de uma linha de configuração ou comando (veja abaixo).

2. Faça login com o Spy.House (Sign in with): Seu cliente abrirá o navegador para a autorização OAuth.

3. Pergunte ao seu agente (Ask your agent): Escreva um comando, por exemplo: “Find up to 12 Black Friday FB creatives for the USA”. O agente invocará a ferramenta necessária e responderá.

Configuração para clientes específicos

Nota para clientes CLI (Claude Code, Codex): Após adicionar o servidor, é necessário reiniciar o cliente, pois a sessão em execução não o carregará. Em seguida, faça o login: para o Claude Code usando o comando /mcp e para o Codex com o comando codex mcp login spy-house (do bloco abaixo).

1. Claude

As versões Desktop e Web utilizam o Client ID indicado abaixo. O Claude Code utiliza um comando CLI com seu próprio Client ID.

Desktop / Web:

1. Acesse Settings (Configurações) → Connectors (Conectores) → Add custom connector (Adicionar conector personalizado).

2. Cole a URL de endpoint.

3. Clique em Connect & authorize (Conectar e autorizar).

Claude Code (CLI): Execute o 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

Adicione o servidor remoto com um único comando e, em seguida, faça login no sistema.

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

Execute o comando abaixo ou adicione o servidor ao arquivo ~/.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

Execute o comando abaixo ou adicione o servidor ao arquivo mcp.json de usuário ou mcp.json do espaço de trabalho (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. Abra o Claude → Customize → Connectors → Add custom connector.

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

3. Em Advanced OAuth settings, informe o Client ID spy-mcp-claude-desktop; deixe o Client Secret em branco.

4. Clique em Add / Connect.

6. ChatGPT

1. No ChatGPT web, ative Settings → Security and login → Developer mode.

2. Adicione o aplicativo remoto (remote MCP app) em Plugins: URL [https://spy.house/mcp], Client ID spy-mcp-chatgpt, Streamable HTTP, sem Client Secret (no Client Secret).

3. Clique em Connect / Authenticate, faça login no Spy.House e confirme o acesso. Não são necessários chave de API nem Client Secret.

4. Execute esta consulta: > Find up to 12 Black Friday FB creatives for the US.

Verificação por consulta (Verification by request)

Após conectar, execute estas consultas no seu cliente. Os resultados esperados são uma lista de verificação (checklist), e não uma busca em tempo real.

• search_creatives

  • Consulta de verificação: Find up to 12 Black Friday Facebook ad creatives for the US.

  • Resultado esperado: Até 12 criativos, incluindo os dados e a cota de pesquisa restante. Uma rede por chamada: push, inpage, facebook, tiktok ou native. Cada pesquisa não vazia consome uma unidade da cota.

• get_filter_options

  • Consulta de verificação: List the available Facebook search filters.

  • Resultado esperado: Catálogo de filtros do Facebook sem conteúdo adulto (non-adult) e valores exatos para search_creatives. Os filtros de conteúdo adulto ficam ocultos.

• get_creative_media

  • Consulta de verificação: Show me the images of the creatives you just found.

  • Resultado esperado: Mídia de até três creative_ref desta busca. A cota de pesquisa não é deduzida. O vídeo completo não é retornado e o chat pode não exibir a pré-visualização incorporada.

• render_creatives_gallery

  • Consulta de verificação: Show these creatives as a gallery.

  • Resultado esperado: Galeria incorporada de 1 a 12 creative_ref da mesma pesquisa em clientes compatíveis com MCP Apps. Os demais clientes ignoram esta ferramenta e utilizam texto ou get_creative_media.

Perguntas Frequentes (FAQ)

Como desconectar o Spy.House do cliente de IA?

Remova ou desative o servidor Spy.House no cliente de IA. O acesso também é encerrado quando a assinatura paga expirar. Contas de teste não podem se conectar.

Como entrar em contato com o suporte?

• E-mail: [email protected]

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

• Horário de atendimento do suporte: Seg–Sex, 10:00–18:00 (UTC+3)

Em caso de erro, por favor envie: nome do cliente de IA, horário, texto do erro e uma captura de tela.

A integração do Spy.House por meio do protocolo MCP transforma assistentes de IA populares e ambientes de desenvolvimento em uma ferramenta eficaz de inteligência competitiva. Graças à autorização OAuth sem complicações e ao conector único, os usuários ganham a capacidade de pesquisar criativos publicitários, analisar filtros disponíveis e visualizar arquivos de mídia diretamente da interface do seu cliente habitual, reduzindo o processo de busca a simples comandos em linguagem natural.