QUICKSTART
Your first useful call
Connect SocialToAI to an AI client or make a first HTTP request within the trial budget.
1. Get connected
Open Access, sign in with email or Google, and choose your daily credit limit. Your one active Connector grants the six core verbs and the free capabilities tool.
Copy the MCP URL into your client's Remote HTTP MCP connection settings. Treat the URL as a secret because it contains your Key. Verify capabilities(platform=reddit) before starting paid research.
If this browser loses the local credential, sign in and rotate the Key. Rotation revokes the old Key and preserves the daily spend policy.
https://mcp.socialtoai.com/mcp?key=YOUR_SOCIALTOAI_KEYConnection preferences
Optionally add default_parameters as URL-encoded JSON grouped by verb. search accepts type, sort, time_range, content_type, scope and count (1–20); trending accepts category. Explicit tool arguments override these defaults. Keep the same effective query when following a cursor.
exclude_platforms is a comma-separated platform list. A call explicitly selecting any excluded platform fails free. search with platforms=all subtracts exclusions from xiaohongshu,douyin,x,reddit,bilibili; it never adds substitute platforms. One remaining platform still returns fanout. If none remain, the request fails free.
Preferences affect this MCP connection. They do not change HTTP requests, other connections, Key permissions or daily limits. packs only selects tools already granted to the Key; changing a URL cannot unlock a capability.
Unknown or repeated query settings, invalid defaults, and unknown or repeated platforms/packs return invalid_params. Each decoded preference is limited to 4096 UTF-8 bytes. Query, platform, account identifiers, cursors, credentials and budgets cannot be set through defaults. Check capabilities for the platform after connecting.
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=x2. Start inside your budget
Try a single Reddit search at 0.2 credits. Registration gives 2 credits; a complete multi-step workflow can cost more. Check your balance in the console and set a task budget first. After each call, read billing.balance.
Suggested prompt: Search Reddit for AI research pain points with count=5. Make one call, inspect warnings, cite the returned sources, and report the actual cost and remaining balance.
Install in a CLI client
Set SOCIALTOAI_API_KEY in your terminal environment using the Key copied from Access. Run only the command for your client. Claude Code and Gemini store the supplied header in local settings; Codex reads its token from the named environment variable when connecting.
Installation writes configuration; it does not prove authentication or spend credits. Reopen your client, inspect its MCP connection status and run capabilities(platform=reddit). Keep existing server entries when editing configuration. After rotation, update the Key wherever you installed it.
# 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/mcpOptional research methods
Install the general router, setup guide or a specific research recipe. Keep private vocabulary in a separately named local fork.
Install in Cursor
The Add to Cursor button installs the server using an environment variable reference. Set SOCIALTOAI_API_KEY in the environment that launches Cursor. For manual setup, merge this server entry into .cursor/mcp.json under mcpServers without replacing other servers.
If your desktop client cannot read that environment variable, use the personal Remote MCP URL from Access in its MCP settings instead. Keep that credential-bearing URL private. The server uses Streamable HTTP; OAuth login is not required for this Key connection.
{
"mcpServers": {
"socialtoai": {
"url": "https://mcp.socialtoai.com/mcp",
"headers": {
"Authorization": "Bearer ${env:SOCIALTOAI_API_KEY}"
}
}
}
}3. Or use HTTP
Export SOCIALTOAI_API_KEY locally. Replace the example idempotency value with a unique ID. These snippets make one request and have no automatic retry loop.
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}'Import into n8n
Download the workflow and use n8n's Import from File action. In Search Reddit once, create or select a Header Auth credential with name X-API-Key and your Key as its value. The workflow file contains no credential. It starts manually, makes one search and has no pagination or automatic retries. Search succeeded passes ok and empty results; other statuses stop the workflow. Connect your next step to its true output.
Before executing, check Balance and allow at least 0.2 credits for the current Reddit search price, including an empty result. Change the query, run once, and inspect status, applied_params, warnings and billing in the output. A fresh execution can incur another charge; do not rerun an ambiguous timeout blindly.
Build one bounded Agent tool
Download the Node.js module next to your script. It derives a narrow search tool schema from the public OpenAPI and exposes definition plus execute. Pass definition to your model's tool interface, then pass its parsed arguments to execute. The example allows one Reddit call, rejects model-selected endpoints/platforms and checks your quoted budget before dispatch.
Use the current price from Pricing and your actual Balance. This local quote is an estimate, not a server-side price lock. Your Connector's daily limit remains the server-enforced spending control. The module does not choose a model or run an automatic research loop.
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);Python
Uses the Python standard library.
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
Run in Node.js with the Key in your environment. Keep product credentials out of public browser code.
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. Read, then decide
Check status, applied_params, warnings, billing.cost and billing.balance. Follow returned source links. Only paginate with the returned cursor and a remaining task budget.
Use Usage to trace request_id and Balance to inspect charges. A checkout return does not prove settlement; wait for your wallet to update.