# 你的第一个有用调用

把 SocialToAI 接入 AI 客户端，或在试用额度内发出第一个 HTTP 请求。

规范地址: https://socialtoai.com/zh/docs/quickstart/

## 1. 完成连接

打开控制台，用邮箱或 Google 登录，设置每日 credit 上限。你唯一的有效连接器包含六个核心动作和免费的 capabilities 工具。

把 MCP 地址填入客户端的 Remote HTTP MCP 连接设置。这个地址包含你的 Key，请当作密钥保管。开始付费研究前，先验证 capabilities(platform=reddit)。

如果当前浏览器丢失了本地凭据，登录后轮换 Key 即可。轮换会吊销旧 Key，并保留每日消费策略。

```
https://mcp.socialtoai.com/mcp?key=YOUR_SOCIALTOAI_KEY
```

[打开控制台 →](https://socialtoai.com/console/)

## 连接偏好

可以添加 default_parameters，内容为按动作分组、经过 URL 编码的 JSON。search 接受 type、sort、time_range、content_type、scope 和 count（1–20）；trending 接受 category。显式的工具参数优先于这些默认值。沿用 cursor 翻页时请保持有效查询不变。

exclude_platforms 是逗号分隔的平台列表。显式选择任何被排除平台的调用会免费失败。platforms=all 的搜索会从 xiaohongshu,douyin,x,reddit,bilibili 中减去被排除的平台，不会补充替代平台。只剩一个平台时仍返回 fanout；一个都不剩则请求免费失败。

偏好只影响这条 MCP 连接，不改变 HTTP 请求、其他连接、Key 权限或每日上限。packs 只能选择 Key 已被授予的工具；修改 URL 无法解锁能力。

未知或重复的查询设置、无效默认值、未知或重复的 platforms/packs 都会返回 invalid_params。每个解码后的偏好限制在 4096 个 UTF-8 字节以内。查询词、平台、账号标识、cursor、凭据和预算不能通过默认值设置。连接后请检查该平台的 capabilities。

```
https://mcp.socialtoai.com/mcp?key=YOUR_SOCIALTOAI_KEY&default_parameters=%7B%22search%22%3A%7B%22count%22%3A5%2C%22sort%22%3A%22latest%22%7D%7D&exclude_platforms=x
```

## 2. 在预算内开始

先试一次 Reddit 搜索，0.2 credits。注册赠送 2 credits；完整的多步流程可能花费更多。先在控制台查看余额并设定任务预算，每次调用后读取 billing.balance。

推荐提示词：用 count=5 在 Reddit 搜索 AI 研究的痛点。只调用一次，检查 warnings，引用返回的来源，并报告实际花费和剩余余额。

## 在命令行客户端中安装

用从控制台复制的 Key 在终端环境里设置 SOCIALTOAI_API_KEY，然后只运行你所用客户端的那条命令。Claude Code 和 Gemini 会把提供的请求头保存到本地设置；Codex 在连接时从指定的环境变量读取令牌。

安装只是写入配置，不代表鉴权成功，也不会消耗 credits。重新打开客户端，检查 MCP 连接状态并运行 capabilities(platform=reddit)。编辑配置时保留已有的服务器条目。轮换 Key 后，记得在所有安装位置更新。

```
# Claude Code
claude mcp add --transport http socialtoai https://mcp.socialtoai.com/mcp --header "Authorization: Bearer $SOCIALTOAI_API_KEY"

# Codex
codex mcp add socialtoai --url https://mcp.socialtoai.com/mcp --bearer-token-env-var SOCIALTOAI_API_KEY

# Gemini CLI
gemini mcp add --transport http --header "Authorization: Bearer $SOCIALTOAI_API_KEY" socialtoai https://mcp.socialtoai.com/mcp
```

[Claude Code 官方说明 ↗](https://code.claude.com/docs/en/mcp)

[Codex 官方说明 ↗](https://learn.chatgpt.com/docs/extend/mcp?surface=cli)

[Gemini CLI 官方说明 ↗](https://geminicli.com/docs/tools/mcp-server/)

## 可选的研究方法

安装通用路由、接入向导或某个具体研究配方。私有词表请放在单独命名的本地副本里。

[安装、升级或移除 Skills →](https://socialtoai.com/zh/skills/)

## 在 Cursor 中安装

“Add to Cursor”按钮会以环境变量引用的方式安装服务器。请在启动 Cursor 的环境里设置 SOCIALTOAI_API_KEY。手动配置时，把这个服务器条目合并到 .cursor/mcp.json 的 mcpServers 下，不要覆盖其他服务器。

如果你的桌面客户端读不到该环境变量，可以改为在 MCP 设置里填入控制台提供的个人 Remote MCP 地址，并妥善保管这个包含凭据的地址。服务器使用 Streamable HTTP，这种 Key 连接不需要 OAuth 登录。

```
{
  "mcpServers": {
    "socialtoai": {
      "url": "https://mcp.socialtoai.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:SOCIALTOAI_API_KEY}"
      }
    }
  }
}
```

[Add to Cursor ↗](cursor://anysphere.cursor-deeplink/mcp/install?name=socialtoai&config=eyJ1cmwiOiJodHRwczovL21jcC5zb2NpYWx0b2FpLmNvbS9tY3AiLCJoZWFkZXJzIjp7IkF1dGhvcml6YXRpb24iOiJCZWFyZXIgJHtlbnY6U09DSUFMVE9BSV9BUElfS0VZfSJ9fQ%3D%3D)

[Cursor 官方说明 ↗](https://prod.cursor.com/docs/mcp/install-links)

## 3. 或者使用 HTTP

在本地导出 SOCIALTOAI_API_KEY，把示例中的幂等值换成唯一 ID。这些代码只发一次请求，没有自动重试。

```
curl --request POST 'https://api.socialtoai.com/v1/search' \
  --header "X-API-Key: $SOCIALTOAI_API_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: REPLACE_WITH_A_UNIQUE_REQUEST_ID' \
  --data '{"platform":"reddit","query":"AI research","count":5}'
```

## 导入 n8n

下载工作流后，在 n8n 中使用 Import from File。在“Search Reddit once”节点里创建或选择一个 Header Auth 凭据，名称填 X-API-Key，值填你的 Key。工作流文件不含任何凭据；它手动触发，只搜索一次，没有翻页和自动重试。“Search succeeded”会放行 ok 和空结果，其他状态会终止工作流。把你的下一步连接到它的 true 输出。

执行前先查看余额，至少预留 0.2 credits 用于当前的 Reddit 搜索（空结果同样计费）。修改查询后运行一次，检查输出中的 status、applied_params、warnings 和 billing。重新执行可能再次计费；不要盲目重跑结果不明确的超时。

[下载 n8n 工作流（.json）→](https://socialtoai.com/examples/n8n-reddit-search.json)

[n8n HTTP Request 文档 ↗](https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.httprequest/)

## 构建一个有边界的 Agent 工具

把 Node.js 模块下载到脚本旁边。它从公开的 OpenAPI 推导出一个窄范围的搜索工具结构，提供 definition 和 execute。把 definition 交给模型的工具接口，再把模型解析出的参数传给 execute。示例只允许一次 Reddit 调用，拒绝模型自行选择端点或平台，并在发出前检查你报出的预算。

请使用价格页上的当前价格和你的实际余额。本地报价只是估算，不是服务端锁价；连接器的每日上限才是服务端强制执行的消费控制。该模块不会替你选择模型，也不会自动循环研究。

```
import { createResearchTool } from "./openapi-agent.mjs";
const spec = await fetch("https://socialtoai.com/openapi.json").then(r => r.json());
const tool = createResearchTool(spec, {
  apiKey: process.env.SOCIALTOAI_API_KEY,
  apiOrigin: "https://api.socialtoai.com",
  budgetCredits: Number(process.env.SOCIALTOAI_TASK_BUDGET),
  balanceCredits: Number(process.env.SOCIALTOAI_BALANCE),
  quotedCredits: 0.2, // Verify the current price before running.
});
console.log(tool.definition);
// After reviewing the model's arguments, one paid call:
const result = await tool.execute({ query: "AI research pain points", count: 5 });
console.log(result);
```

[下载 Agent 模块（.mjs）→](https://socialtoai.com/examples/openapi-agent.mjs)

[公开 OpenAPI →](https://socialtoai.com/openapi.json)

## Python

只使用 Python 标准库。

```
import json, os, uuid
from urllib.request import Request, build_opener, HTTPRedirectHandler

class NoRedirect(HTTPRedirectHandler):
    def redirect_request(self, req, fp, code, msg, headers, newurl):
        return None

request = Request(
    "https://api.socialtoai.com/v1/search",
    data=json.dumps({"platform":"reddit","query":"AI research","count":5}).encode(),
    headers={"X-API-Key": os.environ["SOCIALTOAI_API_KEY"],
             "Content-Type": "application/json",
             "Idempotency-Key": str(uuid.uuid4())},
    method="POST",
)
with build_opener(NoRedirect).open(request, timeout=30) as response:
    print(json.load(response))
```

## JavaScript

在 Node.js 中运行，Key 放在环境变量里。不要把产品凭据放进公开的浏览器代码。

```
const response = await fetch("https://api.socialtoai.com/v1/search", {
  method: "POST", redirect: "error",
  headers: { "X-API-Key": process.env.SOCIALTOAI_API_KEY,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID() },
  body: JSON.stringify({"platform":"reddit","query":"AI research","count":5}),
  signal: AbortSignal.timeout(30_000),
});
console.log(await response.json());
```

## 4. 先读结果，再做决定

检查 status、applied_params、warnings、billing.cost 和 billing.balance，并打开返回的来源链接。只有在还有任务预算时，才用返回的 cursor 翻页。

用“用量”页追踪 request_id，用“余额”页查看扣费。从支付页返回控制台不代表已经到账，请等待钱包更新。

[用量 →](https://socialtoai.com/console/usage/)

[余额 →](https://socialtoai.com/console/balance/)