# Skills & MCP Server (/docs/skills-and-mcp) Connect any MCP client or agent skill to the SocialCrawl API, hosted or local 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. Hosted MCP endpoint: `https://mcp.socialcrawl.dev/mcp`. Your key travels as a request header, never as a query string. ## Prerequisites - An API key from [socialcrawl.dev](https://www.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](https://skills.sh)). ## Server URL Copy this into any client that accepts a remote MCP endpoint: ```text title="MCP URL" 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 ### Create an API key Sign in at [socialcrawl.dev](https://www.socialcrawl.dev) and open Dashboard → API Keys. Keys look like `sc_...` and are shown once, so store yours before you leave the page. See [Authentication](/docs/authentication.md). ### Register the server with your client Every client below reaches the same seven tools. The hosted server needs nothing installed; the local server runs `socialcrawl-mcp` through `npx` on your machine. **Claude Code** Hosted, one line: ```bash title="Terminal" claude mcp add --transport http socialcrawl https://mcp.socialcrawl.dev/mcp \ --header "Authorization: Bearer YOUR_API_KEY" ``` Local, if you would rather run the package yourself: ```bash title="Terminal" claude mcp add --scope user socialcrawl -e SOCIALCRAWL_API_KEY=YOUR_API_KEY -- npx -y socialcrawl-mcp ``` Flags go before the `--` separator; everything after it is the command Claude Code runs. **Claude Desktop** Edit `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, or `%APPDATA%\Claude\claude_desktop_config.json` on Windows. Hosted: ```json title="mcp.json" { "mcpServers": { "socialcrawl": { "type": "http", "url": "https://mcp.socialcrawl.dev/mcp", "headers": { "Authorization": "Bearer YOUR_API_KEY" } } } } ``` Local: ```json title="mcp.json" { "mcpServers": { "socialcrawl": { "command": "npx", "args": ["-y", "socialcrawl-mcp"], "env": { "SOCIALCRAWL_API_KEY": "YOUR_API_KEY" } } } } ``` **Cursor** Edit `.cursor/mcp.json` in your project (or the global equivalent). Cursor uses the same `mcpServers` shape as Claude Desktop. ```json title="mcp.json" { "mcpServers": { "socialcrawl": { "type": "http", "url": "https://mcp.socialcrawl.dev/mcp", "headers": { "Authorization": "Bearer YOUR_API_KEY" } } } } ``` For the local package, swap the three `type`/`url`/`headers` keys for `"command": "npx"`, `"args": ["-y", "socialcrawl-mcp"]`, and `"env": { "SOCIALCRAWL_API_KEY": "YOUR_API_KEY" }`. **VS Code** Edit `.vscode/mcp.json`. VS Code uses the `servers` key and an explicit transport type. ```json title="JSON" { "servers": { "socialcrawl": { "type": "stdio", "command": "npx", "args": ["-y", "socialcrawl-mcp"], "env": { "SOCIALCRAWL_API_KEY": "YOUR_API_KEY" } } } } ``` **Windsurf** Windsurf reads the same `mcpServers` block as Claude Desktop: ```json title="mcp.json" { "mcpServers": { "socialcrawl": { "command": "npx", "args": ["-y", "socialcrawl-mcp"], "env": { "SOCIALCRAWL_API_KEY": "YOUR_API_KEY" } } } } ``` **Other clients** Any client with stdio transport works with the same three values: command `npx`, args `["-y", "socialcrawl-mcp"]`, and `SOCIALCRAWL_API_KEY` in the environment. Any client that supports a remote Streamable HTTP server needs the URL plus a header: ```text title="MCP URL" https://mcp.socialcrawl.dev/mcp Authorization: Bearer YOUR_API_KEY ``` A client that cannot attach a custom header still connects, but only the three no-key discovery tools will work. ### Restart and verify Restart the client so it reads the new configuration, then ask the agent to list SocialCrawl platforms. That runs `socialcrawl_find` with no task, which costs nothing and proves the connection before you spend a credit. To check the hosted server itself: ```bash title="cURL" curl https://mcp.socialcrawl.dev/healthz ``` ## Available tools The MCP server exposes seven tools, in this order: | Tool | What it does | Needs API key? | | --- | --- | --- | | `socialcrawl_find` | Start here. A task in plain words becomes the best endpoints, each with the parameters the task already supplies, the ones still missing, the credit cost and the exact call. With no task it lists the platforms, or one platform's endpoints | No | | `socialcrawl_endpoint` | One endpoint's contract: purpose, parameters, where the rows are, up to 25 response fields, cost rule, paging, latency and timeout. A platform slug returns its endpoints; a topic such as `errors` or `pagination` returns that guide | No | | `socialcrawl_estimate` | The exact credits before you spend, for one call, a plan of several calls, or a walk of `items` rows. A platform slug returns its price table | No | | `socialcrawl_request` | Calls one endpoint, GET, or POST with a `body` for the [batch endpoints](/docs/batch.md). Refuses a call above `max_credits`, and cuts a large page at row boundaries | Yes | | `socialcrawl_collect` | Walks a paged endpoint until `items` unique rows, the last page or `max_credits`, supplying the cursors and dropping duplicates. `result_id` reads a stored result for free | Yes | | `socialcrawl_account` | Free checks: `balance` (with this session's spend), `transactions` (the receipts for one `request_id`), `status` (platform health) and `freshness` (whether the server's catalogue is behind the API) | Yes, except `status` | | `socialcrawl_manage` | Stateful work by `area` and `action`: [Monitors](/docs/webhooks.md), [cohorts](/docs/cohorts.md), [web](/docs/web.md) jobs, change monitors and browser sessions, and Prism background jobs. Managing is free; runs, scrapes and queries bill | Yes | 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](https://skills.sh). 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: ```bash title="Terminal" 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 `//SKILL.md`: ```bash title="Terminal" 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): ```bash title="Terminal" 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? | | Agent Skill | MCP server | | -------------------- | ----------------------------------------------------- | -------------------------------------- | | **Install via** | skills.sh, Git | npm, MCP Registry, hosted URL | | **Protocol** | Skill files read by the agent | MCP stdio or Streamable HTTP | | **Client support** | Claude Code, Cursor, Windsurf, Codex, Gemini CLI, 40+ | Any MCP-compatible client | | **Discovery tools** | No (the skill handles routing) | Yes (3 free tools, no key) | | **Local validation** | No | Yes (saves credits) | | **Offline docs** | Yes (reference files) | Yes (bundled data) | | **Paging** | Yes (reference file, calls the REST API) | Yes (`socialcrawl_collect`) | | **Monitors** | Yes (reference file, calls the REST API) | Yes (`socialcrawl_manage`, `monitors`) | | **Web and browser** | Yes (reference file, calls the REST API) | Yes (`socialcrawl_manage`, `web`) | ## 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](/docs/endpoint-pricing.md) for the exact figure per endpoint and [Credits](/docs/credits.md) for how the ledger works. ## Troubleshooting **The tools do not show up after I edit the config** MCP clients read their server list at startup. Save the file, fully quit the client, and reopen it. Then ask the agent to list SocialCrawl platforms: that call is free, so it confirms the connection without spending anything. **Only the discovery tools appear, and the others fail** That is the signature of a key that never reached the server. The local package reads `SOCIALCRAWL_API_KEY` from its own environment block, not from your shell. The hosted server reads `Authorization: Bearer` or `x-api-key` from the request. It never falls back to a key of its own, so a client that cannot send a custom header is limited to the three no-key tools by design. The claude.ai web connector is the common case: it takes a name and a URL only. **Where are web scraping, crawls and browser sessions?** In `socialcrawl_manage` with `area: "web"`. The `web` surface mixes GET, POST, PATCH and DELETE and runs asynchronous jobs, so it lives with the other stateful work (Monitors, cohorts and Prism jobs) rather than in `socialcrawl_request`. **An endpoint exists in the REST API but the server does not list it** Each package ships the catalogue as it was when the package was built, while the REST API serves 69 platforms and 679 endpoints today, so the newest endpoints land in the packages a release behind. Ask the agent to run `socialcrawl_account` with `view: "freshness"`: it says whether the server's catalogue is behind the API. Data calls always reach the current API, so you can call a new endpoint by its path through `socialcrawl_request`, or call the REST endpoint directly. **My agent still calls the 1.x tool names** Version 2 of the MCP server replaced eleven tools with the seven above. The local package registers the retired names as thin wrappers when you set `SOCIALCRAWL_LEGACY_TOOLS=1` in its environment. Update your prompts with this mapping: | 1.x tool | Now | | --- | --- | | `socialcrawl_list_platforms` | `socialcrawl_find` with no arguments | | `socialcrawl_list_endpoints` | `socialcrawl_find` with a `task` or a `platform`, or `socialcrawl_endpoint` for one endpoint | | `socialcrawl_get_docs` | `socialcrawl_endpoint` with the topic as `id` | | `socialcrawl_pricing` | `socialcrawl_estimate` | | `socialcrawl_check_balance` | `socialcrawl_account` | | `socialcrawl_monitors`, `socialcrawl_web`, `socialcrawl_cohorts` | `socialcrawl_manage` with `area: "monitors"`, `"web"` or `"cohorts"` | **Is the hosted server up?** `curl https://mcp.socialcrawl.dev/healthz` returns the server name and version. A connection error there means the problem is not your client config. **A call returned an error envelope** Every failure uses the same JSON envelope with `success: false` and a machine-readable `error.type`. Branch on `success` first and follow `error.doc_url`. See [Errors](/docs/errors.md) and [Rate limits](/docs/rate-limits.md). ## Next steps - [Claude Code](/docs/claude-code.md): The one-line install and what the agent can do with it. - [AI agent integration](/docs/ai-agents.md): Machine-readable llms.txt, OpenAPI, and per-platform reference files. - [Monitor webhooks](/docs/webhooks.md): Schedule a recipe and receive a signed payload on every run. - [Quickstart](/docs/quickstart.md): Your first authenticated request, start to finish.