說明：透過 MCP 整合 Spy.House

本指南旨在介绍如何通过 Model Context Protocol (MCP) 协议将广告素材分析服务 Spy.House 与 AI 客户端及开发环境进行集成与配置使用。

本文将详细讲解连接的前置要求（需具备付费订阅，且采用无需 API 密钥的 OAuth 授权）、快速启用的 3 步基本流程，以及针对具体应用（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. 询问您的 Agent（Ask your agent）：发送提示词，例如：“Find up to 12 Black Friday FB creatives for the USA”。Agent 将调用所需工具并给出答复。

具体客户端配置指南

CLI 客户端说明（Claude Code、Codex）：添加服务器后必须重启客户端，否则当前运行的会话无法加载该服务器。重启后执行登录：Claude Code 使用 /mcp 命令，Codex 使用命令 codex mcp login spy-house。

1. Claude

Desktop 和 Web 版本使用下方指定的 Client ID。Claude Code 则使用带有独立 Client ID 的 CLI 命令。

Desktop / Web：

1. 前往 Settings（设置）→ Connectors（连接器）→ Add custom connector（添加自定义连接器）。

2. 粘贴 Endpoint URL：[https://spy.house/mcp]。

3. 点击 Connect & authorize（连接并授权）。

Claude Code (CLI)： 执行以下命令：

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

• Desktop/Web Client ID：spy-mcp-claude-desktop

2. Codex

通过单条命令添加远程服务器，然后登录系统：

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 文件中：

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 或工作区（Workspace）的 mcp.json 中：

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 网页端开启 Settings → Security and login → Developer mode。

2. 在 Plugins 中添加远程应用（remote MCP app）：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。每次非空搜索将消耗 1 单位配额。

• 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.

  • 预期结果：展示本次搜索中最多 3 个 creative_ref 的媒体文件。不扣除搜索配额。不返回完整视频，且聊天界面可能不会显示嵌入预览。

• render_creatives_gallery

  • 验证指令：Show these creatives as a gallery.

  • 预期结果：在支持 MCP Apps 的客户端中，将同一次搜索中的 1–12 个 creative_ref 以嵌入式画廊呈现。其他客户端将跳过此工具并使用文本或 get_creative_media。

常见问题解答（FAQ）

如何从 AI 客户端断开 Spy.House 连接？

在 AI 客户端中删除或禁用 Spy.House 服务器即可。付费订阅到期后访问权限也会随之终止。试用账号无法连接。

如何联系技术支持？

• Email：[email protected]

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

• 工作时间：周一至周五，10:00–18:00 (UTC+3)

• 如遇到错误，请附带发送：AI 客户端名称、发生时间、错误文本和相关截图。

通过 MCP 协议集成 Spy.House，可以将主流的 AI 助手和开发环境转化为高效的竞品情报分析工具。借助无缝的 OAuth 授权和统一的连接器，用户能够直接在熟悉的客户端界面中搜索广告素材、分析可用筛选选项并查看媒体文件，将繁琐的搜索流程简化为简单的自然语言指令。