SocQ MCP 使用指南：在 Cursor、Claude 和 Codex 中接入社媒数据

大模型与 AI 客户端在分析社交网络时往往缺乏直接调用外部接口的能力，但这本质上是工具路由（Routing）的问题，并不需要为 AI 专门维护第二套完全割裂的数据体系。SocQ MCP 服务直接将生产级 REST API 暴露给 AI Agent：同一个托管服务地址、三种可选的工具作用域（Tool Scope），以及完全通用的异步任务处理模型。

本指南将详细介绍如何将 Codex、Claude Desktop、Cursor 以及 VS Code 快速接入 SocQ MCP，指导你根据场景选择最佳工具范围、发起采集任务并完成结果轮询。最新配置代码建议直接在 SocQ MCP 页面 复制生成，避免手动拼写字段发生错误。

核心摘要： 直接连接托管的 Streamable HTTP 服务地址 https://api.socq.ai/mcp。端点发现无需鉴权，发起采集任务需配置 SOCQ_API_KEY。在精简（Compact）模式下，遵循 socq_search_endpoints → socq_describe_endpoint → socq_execute 链路执行，并基于返回的 task_id 推进任务。切勿将 execute 调用误认为是一次性同步返回所有全量数据的接口。

平台官方开发者 API 还是公开数据 MCP？

当用户需要进行内容发布、发送私信、投放广告或查看私有账号的商业分析洞察时，各平台官方的开放平台依然是合规的唯一入口。MCP 协议本身不会凭空增加这些写权限。

SocQ MCP 是通往全网公开社交数据的入口。AI Agent 只能调用 SocQ API 官方目录 中已明确声明的读取能力：不能代发内容、不能访问私密账号，也不能凭空编造不存在的接口。底层 REST API、MCP 服务 与 CLI 命令行工具 执行的是完全相同的任务底座；Agent Skill 技能插件 则专注于辅助模型理解参数规格与预估积分消耗，二者并非独立服务。若现有业务已支持标准 HTTP 请求，直接使用 REST API 即可；若操作位于终端自动化或 CI 流程中，选用 CLI；若属于 IDE 内嵌智能体或对话式 Agent，则推荐使用 MCP。

精准选择工具范围，避免模型“盲猜”参数

MCP 客户端在建立连接时仅能感知当前连接暴露出的工具列表。建议在 /mcp 页面根据业务场景选择合适的作用域并复制生成的配置：

请注意：platforms 与 tools 参数互相排斥，不可组合使用。修改连接参数后，务必在客户端中重启服务以强制刷新 tools/list，否则客户端会长期持有陈旧的本地工具缓存。

在具体开发中，推荐以下默认选型策略：

• 当用户提问可能频繁跨平台（如同时对比 YouTube 视频与 TikTok 带货数据）时，优先采用 Compact 模式。
• 当 Agent 专属负责某一特定场景（如竞品社媒监控专属针对 YouTube 和 TikTok）时，切换为 Platforms 模式。
• 当生产环境需要固化流程进行确定性评测时，选用 Exact tools 模式。

快速接入主流客户端并安全管理密钥

接入仅需简单三步即可完成：

1. 确定所需的作用域类型（Compact、Platforms 或 Exact tools）。
2. 选择目标客户端类型（Codex、Claude Desktop、Cursor 或 VS Code）。
3. 复制生成的标准配置并重启客户端。

各客户端适配规范如下：

请妥善保管 SOCQ_API_KEY，将其配置于系统环境变量或客户端受保护的凭证管理器中，严禁将包含真实私钥的配置文件提交至公共代码仓库。

以通用 Streamable HTTP 为例：

{
  "mcpServers": {
    "socq": {
      "url": "https://api.socq.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${SOCQ_API_KEY}"
      }
    }
  }
}

Codex 支持直接与该托管 URL 通信；Claude Desktop、Cursor 和 VS Code 则推荐通过官方发布的 NPM 桥接包运行。

统一的底层接口能力映射

在 SocQ 体系中，每个采集能力都同时映射为一个 REST 路径、一个端点 ID 和一个强类型工具名称：

POST /v1/tiktok/profiles
  = 端点 ID: tiktok-profiles
  = 强类型工具: tiktok_profiles

协议形式的切换绝不会改变计费规则、流控限制或任务封装。端点探索工具本身不会消耗配额也不会产生采集任务，而在底层 REST 中会被校验拦截的非法参数，通过 MCP 发起时同样会严谨拦截。

发起采集与异步任务的标准化推进

在 Compact 模式下，AI Agent 的典型调度链路如下：

用户自然语言输入
  → 调用 socq_search_endpoints (搜索匹配的端点)
  → 调用 socq_describe_endpoint (获取该端点的精确入参 Schema)
  → 调用 socq_execute(endpoint, input) (提交采集参数并创建异步任务)
  → 获取返回的 task_id
  → 轮询调用 socq_get_task (跟踪任务执行状态)
  → 任务完成后读取 results.items (解析结构化结果)

socq_execute 会对入参进行严格校验并创建异步任务。该调用可能会轻微等待片刻并返回当前状态。若任务状态仍为 queued（排队中）或 running（进行中），Agent 应当依据返回的 task_id 继续调用 socq_get_task 轮询，客户端超时绝不会中断云端的正常采集进程。

当任务进入 succeeded 终态后读取数据内容；若 has_more 为 true，携带 next_cursor 继续分页获取，切勿因首页数量有限而重复发起相同的初始任务。

针对系统提示词（Prompt），推荐引导 Agent 遵循以下清晰逻辑：

采集 @tiktok 账号的公开 TikTok 资料：
1. 先通过 describe 获取 tiktok/profiles 的入参规范；
2. 发起 execute 执行并轮询等待任务完成；
3. 提取用户名、昵称、公开互动指标与采集时间戳并返回标准结果。

Agent 应当准确汇报任务执行的上下文与数据，而不应谎称“在单个同步步骤中瞬间返回了全网数据”。

严格遵守输入规范

MCP 不会放宽任何校验规则：

• Compact 模式下的 input 参数对象必须与对应端点的 Schema 严格契约匹配。
• 规范化用户名与链接：主页链接需先提炼出规范用户名，切勿将视频链接传递给用户名字段。
• 正确理解限制：results_limit 属于单次最大拉取上限设定，并不等同于全网全量归档。
• 平台限定：若所需调用的平台未包含在当前连接的作用域中，需调整参数后重新连接，而非强行让 Agent 进行无权限盲调。

提取结构化数据，避免模型自由发挥

采集成功的记录均遵循统一的标准化实体结构：id、platform、resource、type、url、author、metrics、created_at 以及 collected_at。

请在系统设计中要求 Agent 保持真实的数据呈现：

• 缺失的值应严格保留为 null，不能强行脑补为 0。
• 媒体链接仅为源站资源引用，需注意其有效生命周期。
• 结构化问答中的字段必须能够准确溯源至 results.items 实体，防止大模型发生幻觉。

刷新策略与常见排错指南

Agent 提示“找不到指定的平台或端点”？

通常是因为当前 MCP 连接设置了限制性的作用域，或者本地客户端缓存了陈旧的工具清单。请访问 /mcp 重新配置并重启客户端。

接口报错提示未授权？

端点发现与 Schema 读取不需要秘钥，但执行采集任务必须提供有效凭据。请检查环境变量或系统凭据中的 SOCQ_API_KEY 是否有效。

首次工具调用返回后看不到数据条目？

任务采用全异步架构，首个调用主要用于确认任务创建并返回 task_id。必须继续推进轮询任务接口直至终态。

Agent 试图调用“发布内容”或“读取私密主页”的能力？

SocQ 纯粹专注于公开数据的只读采集，目录中不存在任何写操作。相关需求必须引导用户接入各平台官方的 OAuth 授权应用。

常见问题 (FAQ)

SocQ MCP 是独立于 REST 的另一套服务吗？

不是。MCP 是连接底层统一数据目录的另一种交互协议，其计费与任务模型与 REST 完全共通。

没有配置 API Key 可以使用吗？

可以进行平台查询、端点搜索与入参 Schema 查看。但若要真正发起数据采集任务，必须提供有效的 API Key。

为什么 Compact 模式不把所有 API 平铺暴露？

整套目录拥有上百个专注端点，全量平铺会严重占用大语言模型的上下文窗口。Compact 模式通过按需检索和描述端点，最大化节省上下文并提高工具选择准确度。

Agent 支持在 X 上自动发推或读取私密 Instagram 吗？

不支持。SocQ 仅服务于公开合法数据的只读采集，不支持任何破坏访问控制的写操作或侵入性行为。