General

Social Fetch with Cursor and Claude

Connect Cursor or Claude with MCP, test a public profile lookup, install the public skill file, and move the request into server code.

Social FetchUpdated

Connect your agent to Social Fetch, check its access without spending lookup credits, then make one TikTok profile lookup. You can use the response to write server code with the right field names.

MCP gives the agent tools it can call. The optional skill gives it instructions about using those tools. Public docs files such as llms.txt help it find routes and schemas. The hosted MCP connection is separate from Ask AI inside the Social Fetch app.

What you need

  • A Social Fetch account and workspace credits for the lookup. See credits for billing.
  • Cursor, Claude Code, or Claude with custom connector access. An organisation administrator may need to enable custom connectors.

Open Connect in Social Fetch and choose your agent. Cursor and Claude have separate setup paths; Claude Code is listed separately from Claude's web and desktop connector.

The real Social Fetch Connect page with the Cursor card boxed and labelled Pick the agent you use; Claude and Claude Code are also visible
Choose the client you actually use. Claude's connector and Claude Code have different setup steps.

Connect Cursor

  1. In Social Fetch's Connect page, choose Cursor.
  2. Click Install in Cursor, review the server in Cursor, and accept the installation.
  3. Complete the Social Fetch browser sign-in when Cursor asks for authentication.
  4. Return to Cursor and check that the server is enabled in its MCP settings.

For manual setup, merge this entry into .cursor/mcp.json in your project. For access across projects, use ~/.cursor/mcp.json instead. Keep any other servers already in that file.

Request
json

Save the file, reload Cursor if the server hasn't appeared, and finish authentication. Cursor documents these configuration locations in its MCP guide.

Cursor's Customize page with MCPs searched for socialfetch after signing in: the socialfetch server shows a green dot and 923 tools, 12 resources enabled. The row is boxed and labelled Connected: tools are ready
In Cursor, check that Social Fetch is enabled and authenticated before asking for data.

Connect Claude

Claude Code

In your project terminal, run:

Request
bash

This uses Claude Code's default local scope for the current project. To share the server configuration through the project's .mcp.json, add --scope project before the URL. Each teammate still signs in separately. See Claude Code's MCP documentation.

In a Claude Code session, enter:

Request
text

Select socialfetch and follow the authentication instructions in your browser. Return to the session when sign-in is complete.

Claude web and desktop

Open Claude's connectors settings and add a custom remote connector named Social Fetch with this server URL:

Request
text

Follow the detected OAuth sign-in flow, then enable the connector in the conversation where you want to use it: click + under the message box, open Connectors and switch Social Fetch on. On a managed account, ask your organisation owner to add or enable it if the option is missing. Follow Claude's current custom connector instructions for the controls available to your account.

A new Claude conversation with the + menu open at Connectors: the Social Fetch row with its switch on is boxed and labelled Social Fetch is on, and Tool access at the bottom of the connector list is boxed and labelled Tool access sets how tools load. The sidebar's conversations and the account name are hidden
Enable the Social Fetch connector in the conversation before sending the test prompt.

Check the connection

Ask your connected agent:

Request
text

These tools have no lookup charge. The connection uses the workspace resolved by your OAuth sign-in, or the workspace that owns your API key. Check the reported workspace before a batch of paid requests.

OAuth is the usual browser sign-in path. Clients that support request headers can instead send x-api-key; use the client's environment-variable or secret setting, and see the MCP authentication guide. Never paste a key into an agent conversation or put it in a URL.

Use https://api.socialfetch.dev/mcp for this account-based connection. Valid OAuth or API-key credentials also give account-tool access at /x402/mcp; anonymous wallet callers cannot use auth_whoami, billing_balance_get or nl_ask_post. See x402 if you need that separate payment flow.

Make one lookup

The TikTok profile tool takes a handle. Ask:

Request
text

This is a paid step: a completed TikTok profile lookup costs 1 credit, including not_found or private. Read data.lookupStatus before using the profile, and check for null fields.

MCP returns a protocol result containing JSON in content text. Successful lookup results also expose structuredContent.data and structuredContent.meta. Inside that lookup JSON, data and meta sit beside each other. Use the representation your client provides; errors carry error.requestId.

Seeing HTTP 200 does not mean a profile was found. A completed not_found or private lookup is still billed. Repeating it spends more credits.

Once that works, ask the agent to write a server function using the same route and fields. For another task, start with docs_search and docs_read rather than guessing a tool name or assuming other platforms use the same field paths.

Install the optional skill

The public skill file contains instructions for working with Social Fetch. Review it before saving it. It points to public MCP and REST documentation; it doesn't create an MCP connection or grant API access.

For Cursor, run this in your project using Bash (macOS, Linux or Git Bash):

Request
bash

For Claude Code:

Request
bash

In PowerShell, use:

Request
powershell

For Claude Code, replace .agents/skills/socialfetch with .claude/skills/socialfetch in both PowerShell commands. These commands download Markdown, not an executable. The GitHub source repository is private; use this public single-file download rather than a repository installer that needs access.

Start a new agent session and ask it to use the socialfetch skill. To update a manual installation, review the current download and repeat the same command. To remove it, delete the socialfetch folder you created in your project's skills directory. The MCP connection and API keys remain until you remove or revoke them separately. See Agent Skills for details.

Explore with nl_ask_post

When you don't know which lookup fits a question, nl_ask_post can choose and run one. It is the MCP version of POST /v1/ask. This is a one-shot data request, separate from Ask AI in the app.

For example, send this input to nl_ask_post:

Request
json

Routing has no credit charge, but the lookup it runs is billed. Read data.routedOperation for the chosen method, path and parameters, and data.lookup for the nested result. The outer meta.creditsCharged reports the nested lookup's charge. Use the typed tool on later calls once you know the route.

Move the request into server code

For an application or scheduled script, REST or the TypeScript SDK gives you explicit requests. Headless MCP is also supported with an API key; it doesn't require a browser OAuth prompt on every run.

  1. Open API Keys in Social Fetch.
  2. Enter a name that identifies your server or project, then click Create key.
  3. Copy the new key into your server's secret store or local environment. Keep it out of browser code and source control.
The real Social Fetch API Keys page with Cursor and Claude server entered as a key name; Create key is labelled Create a separate key for your server. No new key has been created or revealed.
Use a named key for the server. OAuth access in your agent doesn't configure your application.

Use Node.js 22 or later. Save the following as socialfetch-profile.mjs; the .mjs extension allows top-level await.

Request
javascript

Set SOCIALFETCH_API_KEY privately in your shell or secret manager, then run:

Request
bash

Each execution makes another paid lookup. This example sends once and leaves retry decisions to you. The result is a new snapshot; its counts can differ from the earlier MCP lookup.

To find this REST request, open Usage, then Request history, and paste the successful meta.requestId or failed error.requestId into Request ID.

The real Social Fetch Request history page filtered to existing TikTok profile REST calls, with Request ID labelled Find the REST call by its request ID
Use the REST request's own ID to inspect its status and charge. The rows shown are existing docs-account requests.

Billing and loop guardrails

  • docs_search, docs_read, auth_whoami and billing_balance_get have no lookup charge.
  • Metered tools spend the authenticated workspace's credits. Read the selected route's pricing before a batch; costs and pagination rules vary by route.
  • nl_ask_post routes for free and bills the nested lookup. Include that lookup in your budget.
  • Count completed not_found and private results towards the budget, and stop retrying those targets.
  • Stop on 402 and inspect the refusal. It can mean the workspace lacks credits or an API key has reached its budget. A key budget refusal needs a key budget change, not a purchase.
  • For 503 temporarily_unavailable, honour Retry-After when supplied and use bounded retries. Set a maximum number of calls and pages before starting a loop.
  • Keep meta.requestId on success and error.requestId on failure so support can trace a call.

Troubleshooting

401 or the client keeps asking you to sign in

Reconnect the MCP server and complete the Social Fetch browser flow. If using a key, check that the client sends x-api-key, that the key is active and that its owner still has workspace access. Invalid credentials return 401; switching to /x402/mcp doesn't bypass invalid credentials.

The tool list is empty

Check the server URL, enable Social Fetch in the conversation, and reconnect. In Claude Code, use /mcp to inspect the server. If you added platform or tool filters to the URL, remove them while diagnosing the connection. See MCP for client setup.

402 insufficient_credits

Stop the loop and read the full error. Check workspace credits and the API key's budget in the app. Don't repeatedly call the same tool or initiate purchases from the agent loop.

The response says not_found or private

Record data.lookupStatus and any null data. Check that you supplied a handle from the intended platform. Don't retry a completed lookup just because it didn't return a public profile.

The agent invents a route or reads the wrong fields

Ask it to read llms.txt, then call docs_search and docs_read for the specific route. TikTok profile followers are at data.metrics.followers; other routes can have different shapes. The optional skill keeps this docs-first guidance in your project.

If a request still needs investigation, contact support with its request ID.

Share this article