SocialScrape
Get early access
Docs menu

Get started

Guides

API reference

Resources

MCP for AI agents

Draft

Written from the ws/mcp-cli branch (server.json and README); the package is not published and the hosted URL is not live yet. Confirm both after the merge.

The SocialScrape MCP server gives an AI agent the whole API as tools, so it can look up a profile, read comments or fetch a transcript without you writing glue code. Credits are the same as the REST API: failures and cached repeats are free.

Tools#

The server groups the endpoints so an agent sees a usable number of tools instead of one per endpoint. The tools are generated from the same registry as the API reference, and only built endpoints appear.

ToolsWhat they do
get_transcript, search, get_profile, get_post, get_commentsThe jobs agents do most, across platforms. The platform is an argument.
One per platform, such as github or facebookresource picks the data (user, profile.posts, and so on); the parameters follow.
describeExact parameters, allowed values, price and example arguments for any endpoint. Free, makes no API call.
call_endpoint, batch, get_job, monitors, get_creditsAny endpoint by id, up to 100 requests in one call, long jobs, webhooks and the balance.

Every result starts with a line such as ok | credits charged: 1 | credits remaining: 4999. A failure comes back as an error result with the API's error code, a retryable flag and what to do next. Tool parameters use the API's own names, including max_age_days and cursor.

Connect#

Use your normal API key. Create a key per agent in the dashboard so you can see its usage and revoke it alone.

Remote server (no install; the key is yours and is sent with each request):

{
  "mcpServers": {
    "socialscrape": {
      "url": "https://mcp.socialscrape.io/mcp",
      "headers": { "x-api-key": "YOUR_KEY" }
    }
  }
}

Local (stdio), for clients that start the server as a subprocess:

{
  "mcpServers": {
    "socialscrape": {
      "command": "uvx",
      "args": ["socialscrape-mcp"],
      "env": { "SOCIALSCRAPE_API_KEY": "YOUR_KEY" }
    }
  }
}

Some clients limit how many tools they accept. To narrow the list, add ?platforms=github,threads or ?toolsets=core to the remote URL, or set SOCIALSCRAPE_PLATFORMS or SOCIALSCRAPE_TOOLSETS for the local server. With core alone an agent still reaches every endpoint through describe and call_endpoint.

Running out of credits#

An agent that runs out gets a 402 insufficient_credits result with payment details. An agent that can pay can buy a pack on its own; see Credits and pricing. To keep spending bounded, give each agent its own key on a team with a small balance.

Tips for agents#

  • Tell the agent to pass max_age_days when freshness is not critical; repeats then cost nothing.
  • The server asks for trim=true by default to keep results short and save context.
  • For many lookups, prefer batch over many single calls.
  • llms.txt and llms-full.txt hold these docs in a form models read well.