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/mcp

Connect 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.

  1. Open Connect with AI in the Social Fetch app.
  2. Pick your AI. Claude, ChatGPT and Cursor are at the top; the others are under Also works with.
The Social Fetch app's Which AI do you use? page, with the Claude, ChatGPT and Cursor cards boxed and labelled Pick yours to see its steps, and VS Code, Perplexity, Grok, Le Chat, Gemini, Windsurf, Claude Code, Codex, Zed and Gemini CLI listed below under Also works with
One link works in every app. Pick yours to see its steps.
  1. 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.
The Claude setup steps in the Social Fetch app: step 1, Add it in Claude, with the Add in Claude button boxed and labelled Opens Claude with the link filled in, and step 2, Sign in, below it
Each app has its own steps. Claude's start with one button.
  1. In Claude, check the link is https://api.socialfetch.dev/mcp, leave Advanced settings empty, and click Add.
Claude's Add custom connector window, filled in by the button.
  1. A Social Fetch tab opens. Sign in if you're asked to, then click Allow access.
The Social Fetch Authorize access screen: your AI can look up public profiles, posts and transcripts using your credits, and can't post or see private accounts. The four permissions (Read your profile, Read your email address, Stay connected, Call Social Fetch tools) are bracketed and labelled What your AI can do, the signed-in email address is covered, and the Allow access button is labelled Click to connect
Your AI can look up public data with your credits. It can't post or see private accounts.

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.

  1. 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.
Your AI picks the right tool and answers from live data.

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.

Cursor lists Social Fetch once you've signed in.

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/mcp

Add --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/mcp

For 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.

  1. Open API Keys in the Social Fetch app.
  2. 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.
The API keys page with Cursor MCP typed in the Name field of New API key and the Create key button labelled Name it, then Create key; the keys list below is dimmed
The full key is shown only once, so copy it before you leave the page.
  1. 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:

  1. 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 socialfetch

If you originally used --scope user or --scope project, use that scope instead of local. Skip this step for a new connection.

  1. 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/mcp

You can also write the URL yourself:

  • ?platforms=twitter,tiktok lists every tool for those platforms.
  • ?tools=twitter_profile_get lists only the tools you name.
  • ?preset=starter lists 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:

ToolWhat it doesCredits
docs_search, docs_readSearch and read the Social Fetch docs, including response fieldsFree
auth_whoami, billing_balance_getWhich account is connected, and its credit balanceFree
nl_ask_postAsk in plain words; it picks a lookup and runs itOnly the lookup it runs
monitors_create, monitors_list, webhookEndpoints_create, webhookEndpoints_listExamples of tools that create and manage monitors and webhooksMonitors 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 socialfetch

Troubleshooting

What you seeWhat to do
401 with missing_bearer_tokenYour app hasn't signed in yet. Finish the OAuth sign-in, or add an x-api-key header.
401 with invalid_api_keyThe 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_tokenThe 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_unavailableYou'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_suspendedThe 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_roleThe 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_requiredThe workspace needs single sign-on. Sign in to Social Fetch through your company's single sign-on, then try again.
A tool returns insufficient_creditsThe workspace has too few credits for this lookup. Top up in Billing. See Credits and billing.
503, or a tool returns temporarily_unavailableA 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 loopingSign 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 appearCheck 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.

On this page