MCP
Connect Claude, ChatGPT, Cursor, VS Code and other MCP clients to Social Fetch. Sign in with OAuth, or send an API key if the client never opens a sign-in window.
MCP (Model Context Protocol) is how AI assistants such as Claude, ChatGPT and Cursor use outside tools. Social Fetch runs a hosted MCP server, so you add one link to your AI and it can look up public profiles, posts, comments, transcripts and search results for you. The available public API operations become tools, and lookups use credits the same way as the REST API.
Not a developer? Try a live lookup and connect Claude or ChatGPT on For AI. You don't need an API key.
What you'll need
- A Social Fetch account. Sign up if you don't have one.
- Credits on that account. Each tool call that looks something up uses credits, the same as the API. See Credits and billing.
- An AI app that supports MCP, such as Claude, ChatGPT, Cursor, VS Code, Claude Code, Codex, Gemini CLI, Windsurf or Zed.
The server address is:
https://api.socialfetch.dev/mcpConnect your AI
The quickest route is the Connect page in the Social Fetch app. It has the steps for each AI app and, for Claude, Cursor and VS Code, a button that adds Social Fetch for you.
- Open Connect with AI in the Social Fetch app.
- Pick your AI. Claude, ChatGPT and Cursor are at the top; the others are under Also works with.

- Follow the steps for your app. For Claude, click Add in Claude. It opens Claude's Add custom connector window with the name and link filled in.

- In Claude, check the link is
https://api.socialfetch.dev/mcp, leave Advanced settings empty, and click Add.
- A Social Fetch tab opens. Sign in if you're asked to, then click Allow access.

If you belong to more than one workspace, pick one on the same screen. Lookups through this connection spend that workspace's credits. To change it later, disconnect and connect again.
- Back in your AI app, ask a question that needs live data, for example "How many TikTok followers does MrBeast have?". The first time, the app may ask you to allow the Social Fetch tool.
Add it by hand
If you'd rather edit your app's settings yourself, use one of the buttons or snippets below. Every snippet uses the same server address.
Cursor: add this to ~/.cursor/mcp.json, or to .cursor/mcp.json in a project.
{
"mcpServers": {
"socialfetch": {
"url": "https://api.socialfetch.dev/mcp"
}
}
}Open Cursor Settings, then the MCP section, and click the sign-in prompt next to socialfetch. A browser tab opens for the same Allow access step as above.
VS Code: add this to .vscode/mcp.json in your project (or run MCP: Add Server from the Command Palette).
{
"servers": {
"socialfetch": {
"type": "http",
"url": "https://api.socialfetch.dev/mcp"
}
}
}Claude Code: run this, then type /mcp in Claude Code and sign in to Social Fetch.
claude mcp add --transport http socialfetch https://api.socialfetch.dev/mcpAdd --scope user to use it in every project.
Claude (web, Desktop and mobile): add a custom connector under Settings, Connectors, with the server address above. Connectors you add on claude.ai also appear in Claude Desktop and the mobile apps.
Apps that only run local (stdio) servers: use mcp-remote as a bridge.
npx mcp-remote https://api.socialfetch.dev/mcpFor ChatGPT, Codex, Gemini, Windsurf, Zed and the rest, follow the steps on the Connect page.
Use an API key instead
Most apps sign in with OAuth, as above. If yours never opens a sign-in window, send a Social Fetch API key in the x-api-key header, the same header the REST API uses.
- Open API Keys in the Social Fetch app.
- Name the key after where you'll use it, then click Create key. Copy the key straight away: it starts with
sfk_and is shown only once.

- Store the key in an environment variable such as
SOCIALFETCH_API_KEY, and read it from there in your app's config. This example uses Cursor's environment-variable syntax; check your client's syntax before copying it. Keep real keys out of shared config files, source control, chats and screenshots:
{
"mcpServers": {
"socialfetch": {
"url": "https://api.socialfetch.dev/mcp",
"headers": {
"x-api-key": "${env:SOCIALFETCH_API_KEY}"
}
}
}
}In Claude Code:
- If you already added
socialfetch, remove that entry at its original scope before adding it with a key. For the default local scope, run:
claude mcp remove --scope local socialfetchIf you originally used --scope user or --scope project, use that scope instead of local. Skip this step for a new connection.
- Add the connection with the key:
claude mcp add --transport http socialfetch https://api.socialfetch.dev/mcp --header "x-api-key: $SOCIALFETCH_API_KEY"This uses the default local scope. To keep a user- or project-scoped connection, add the matching --scope user or --scope project. Claude Code stores the expanded header value in its config, so keep that config private and out of source control.
Don't put the key in the URL or in an Authorization: Bearer header. Bearer is only for OAuth tokens, so a key there is rejected, and a key in the URL ends up in logs.
Lookups made with a key spend the credits of the workspace the key belongs to.
Scope the tool list
The full server lists the available API tools, plus a few helpers. Hidden operations are excluded; retired operations may return an error directing you to their replacement. Apps that handle long tool lists cope fine, but each tool's description takes up room in your AI's context. If you only need some platforms, give your app a smaller list.
Pick platforms in the builder, then copy the URL or config snippet. Leave everything clear for the full list. If your platform is missing from the builder, use its tool-name prefix in ?platforms= or name specific tools with ?tools=.
Full catalog
Every tool listed — best when you need the full API
https://api.socialfetch.dev/mcpYou can also write the URL yourself:
?platforms=twitter,tiktoklists every tool for those platforms.?tools=twitter_profile_getlists only the tools you name.?preset=starterlists TikTok, Instagram, YouTube, X, Reddit and LinkedIn tools. It's a good start for Claude or ChatGPT.
You can combine them; the list is everything they match. Every authenticated scoped list still includes auth_whoami, billing_balance_get, docs_search, docs_read and nl_ask_post.
Scoping only changes which tools your app sees listed. A tool that isn't listed still works if it's called by name. One-click installs and the OAuth sign-in use the plain address: connect with that first, then switch your app to the scoped URL if you want a shorter list.
Tools
API tool names usually follow {platform}_{resource}_{action}; some operations add a version suffix. Use the names your client lists, or find the operation with docs_search and docs_read. For example, tiktok_profile_get gets a TikTok profile. Each tool's arguments and price match the API reference.
A few tools aren't platform lookups:
| Tool | What it does | Credits |
|---|---|---|
docs_search, docs_read | Search and read the Social Fetch docs, including response fields | Free |
auth_whoami, billing_balance_get | Which account is connected, and its credit balance | Free |
nl_ask_post | Ask in plain words; it picks a lookup and runs it | Only the lookup it runs |
monitors_create, monitors_list, webhookEndpoints_create, webhookEndpoints_list | Examples of tools that create and manage monitors and webhooks | Monitors use credits when they check |
When your app connects, the server sends it short instructions: use the most specific tool, check the docs tools when unsure, and read lookupStatus and meta.creditsCharged in each response. Social-platform tools read public data. They can't publish posts, send messages or see private accounts. Account tools can create, change and delete monitors and webhooks, including rotating webhook secrets. Check the requested action and destination before allowing a write, and keep returned secrets private.
Example
Ask your AI to call tiktok_profile_get with { "handle": "nike" }, or to explore with nl_ask_post and { "query": "TikTok profile for @nike" }.
For a typed lookup, the MCP result contains the REST API's { data, meta } envelope as JSON text and in structuredContent. Clients may also show a result card. The shortened example below omits other profile and metrics fields. Check data.lookupStatus before using the profile, and keep meta.requestId in case you need support:
{
"data": {
"lookupStatus": "found",
"profile": { "handle": "nike" }
},
"meta": {
"requestId": "req_…",
"creditsCharged": 1,
"version": "v1"
}
}A completed lookup with lookupStatus: "not_found" or "private" is still a successful result and uses the normal lookup credits. A failed tool call sets isError: true and returns JSON text containing { error: { code, message, requestId } }; an HTTP success alone doesn't mean the tool succeeded. See Errors and outcomes.
For nl_ask_post, routing is free, but the lookup it chooses is paid at that operation's normal rate. The response puts the chosen operation in data.routedOperation and the lookup envelope in data.lookup. Read the outcome at data.lookup.data.lookupStatus where that operation returns one. The outer meta.creditsCharged reports the lookup charge; it isn't a second charge on top of data.lookup.meta.creditsCharged.
Pay per call without an account
https://api.socialfetch.dev/mcp always needs OAuth or an API key. A separate server, https://api.socialfetch.dev/x402/mcp, needs no account: each paid tool call is paid in USDC on Base with x402. The account tools (auth_whoami, billing_balance_get, nl_ask_post, monitors and webhooks) require OAuth or an API key and can't be called anonymously.
Agent skills
For coding agents, the Agent Skills pack teaches the agent to read the docs, use MCP or POST /v1/ask, and call only routes that exist:
npx skills add social-freak-ltd/socialfetch -s socialfetchTroubleshooting
| What you see | What to do |
|---|---|
401 with missing_bearer_token | Your app hasn't signed in yet. Finish the OAuth sign-in, or add an x-api-key header. |
401 with invalid_api_key | The key is wrong, revoked or expired. Create a new one in API Keys, and send it as x-api-key, not Authorization. |
401 with invalid_bearer_token | The sign-in has expired or was revoked. Disconnect and connect again. Don't put an sfk_ key in a Bearer header. |
401 with oauth_workspace_access_removed or oauth_workspace_unavailable | You've left the workspace this connection uses, or it can't be used. Connect again and choose another workspace. |
403 with account_suspended or workspace_suspended | The account or workspace has been suspended. Signing in again won't help. Ask a workspace owner, or contact support. |
403 with workspace_deleted, workspace_unavailable, key_owner_removed or key_owner_role | The API key's workspace, or the person who created the key, can no longer use the API. These are the same reasons the REST API gives. Create a new key in API Keys. |
401 with oauth_workspace_sso_required | The workspace needs single sign-on. Sign in to Social Fetch through your company's single sign-on, then try again. |
A tool returns insufficient_credits | The workspace has too few credits for this lookup. Top up in Billing. See Credits and billing. |
503, or a tool returns temporarily_unavailable | A temporary problem. Try again after the Retry-After time, if there is one. It doesn't mean your key or sign-in is wrong. |
| The sign-in keeps looping | Sign in to the Social Fetch app in the same browser first, then connect again. |
| "This link is invalid or has expired" | The sign-in link is out of date. Start the connection again from your AI app. |
| No tools appear | Check the address is exactly https://api.socialfetch.dev/mcp, with no extra path, then reconnect and restart the app. |
Still stuck? Contact support with the requestId from the response.
Related
Agent Skills
Teach coding agents to use the docs, MCP and real endpoints.
API reference
Every operation the MCP tools wrap.
Credits and billing
How credits are used across MCP and the API.
x402
Pay per tool call in USDC, without an account.
n8n
No-code workflows with an API key.
Apify
Social Fetch Actors with Apify billing.