Skills & MCP Server

SocialCrawl ships two packages that put the API inside an AI agent: an MCP server for any MCP-compatible client, and an Agent Skill for agents that read skill files. Both call the same API, return the same envelope, and bill the same credits, so pick whichever your client supports.

Prerequisites

• An API key from socialcrawl.dev, under Dashboard → API Keys. New accounts start with 100 free credits and no card.
• Hosted server: an MCP client that can send an Authorization header.
• Local server: Node.js with npx available on your machine.
• Agent Skill: an agent that reads skill files (Claude Code, Cursor, Windsurf, Codex, Gemini CLI, and 40+ others).

Server URL

Copy this into any client that accepts a remote MCP endpoint:

https://mcp.socialcrawl.dev/mcp

It speaks the Streamable HTTP transport. Send your key as Authorization: Bearer YOUR_API_KEY, or as x-api-key. A request with no key still reaches the three discovery tools (socialcrawl_find, socialcrawl_endpoint and socialcrawl_estimate), which cost nothing.

How to connect

claude mcp add --transport http socialcrawl https://mcp.socialcrawl.dev/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

claude mcp add --scope user socialcrawl -e SOCIALCRAWL_API_KEY=YOUR_API_KEY -- npx -y socialcrawl-mcp

{
  "mcpServers": {
    "socialcrawl": {
      "type": "http",
      "url": "https://mcp.socialcrawl.dev/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

{
  "mcpServers": {
    "socialcrawl": {
      "command": "npx",
      "args": ["-y", "socialcrawl-mcp"],
      "env": {
        "SOCIALCRAWL_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

{
  "mcpServers": {
    "socialcrawl": {
      "type": "http",
      "url": "https://mcp.socialcrawl.dev/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

{
  "servers": {
    "socialcrawl": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "socialcrawl-mcp"],
      "env": {
        "SOCIALCRAWL_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

{
  "mcpServers": {
    "socialcrawl": {
      "command": "npx",
      "args": ["-y", "socialcrawl-mcp"],
      "env": {
        "SOCIALCRAWL_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

https://mcp.socialcrawl.dev/mcp
Authorization: Bearer YOUR_API_KEY

curl https://mcp.socialcrawl.dev/healthz

Available tools

The MCP server exposes seven tools, in this order:

The three discovery tools need no key and cost nothing, so an agent can find the endpoint for a task, read its parameters and price the call before it spends anything. With a key set they ask the API's free /v1/utility/* routes first, and answer from the catalogue bundled with the server when a route cannot be reached. socialcrawl_request and socialcrawl_collect spend credits at each endpoint's own price.

Local validation before every call

Before it sends anything, socialcrawl_request checks locally that the platform exists, the endpoint exists, and all required parameters are present. A bad call comes back as a fix-it message instead of a wasted credit.

Agent Skill

The socialcrawl skill works with Claude Code, Cursor, Windsurf, Codex, Gemini CLI, and 40+ other agents. It lets your agent fetch current public data (subject to documented endpoint caches), generate code snippets, and answer API questions in natural language.

Install it from skills.sh:

npx skills add socialcrawl/skills

Add -g to install globally instead of per project. To install from Git, copy the socialcrawl subdirectory rather than the whole repository, because agents discover a skill at <skills-dir>/<name>/SKILL.md:

git clone --depth 1 https://github.com/socialcrawl/skills /tmp/socialcrawl-skills
mkdir -p .claude/skills
cp -r /tmp/socialcrawl-skills/skills/socialcrawl .claude/skills/socialcrawl

Then export your key so it persists across sessions (add the line to ~/.bashrc, ~/.zshrc, or your shell's equivalent):

export SOCIALCRAWL_API_KEY="YOUR_API_KEY"

The skill resolves your key from three sources in order: $SOCIALCRAWL_API_KEY, then ~/.config/socialcrawl/api_key, then a prompt. If it has to prompt, it saves the answer to ~/.config/socialcrawl/api_key so you paste it once. The literal placeholder YOUR_API_KEY is treated as unset.

Invoke it directly with /socialcrawl, or ask in natural language: "Get the TikTok profile for @charlidamelio", or "Search YouTube for machine learning videos". The skill picks the platform and endpoint, makes the call, and returns structured JSON.

Skills or MCP?

What does it cost?

Credits are billed exactly as the REST API bills them: most endpoints are 1 credit, heavier ones 5 or 10, and composite or bundle endpoints carry their own price (search/everywhere is a flat 20). Cache hits cost 0. The three discovery tools and socialcrawl_account cost 0 too. See Endpoint pricing for the exact figure per endpoint and Credits for how the ledger works.

Troubleshooting

Next steps