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.

Connect Cursor
- In Social Fetch's Connect page, choose Cursor.
- Click Install in Cursor, review the server in Cursor, and accept the installation.
- Complete the Social Fetch browser sign-in when Cursor asks for authentication.
- 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.
Save the file, reload Cursor if the server hasn't appeared, and finish authentication. Cursor documents these configuration locations in its MCP guide.

Connect Claude
Claude Code
In your project terminal, run:
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:
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:
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.

Check the connection
Ask your connected agent:
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:
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):
For Claude Code:
In PowerShell, use:
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:
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.
- Open API Keys in Social Fetch.
- Enter a name that identifies your server or project, then click Create key.
- Copy the new key into your server's secret store or local environment. Keep it out of browser code and source control.

Use Node.js 22 or later. Save the following as socialfetch-profile.mjs; the .mjs extension allows top-level await.
Set SOCIALFETCH_API_KEY privately in your shell or secret manager, then run:
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.

Billing and loop guardrails
docs_search,docs_read,auth_whoamiandbilling_balance_gethave 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_postroutes for free and bills the nested lookup. Include that lookup in your budget.- Count completed
not_foundandprivateresults towards the budget, and stop retrying those targets. - Stop on
402and 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, honourRetry-Afterwhen supplied and use bounded retries. Set a maximum number of calls and pages before starting a loop. - Keep
meta.requestIdon success anderror.requestIdon 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.