> **For coding agents and LLMs:** This is one page from the Social Fetch docs (markdown export). The sections below mirror the orientation block in [`/llms.txt`](https://www.socialfetch.dev/llms.txt); use [`/llms.json`](https://www.socialfetch.dev/llms.json) when you need a structured operation inventory. The catalog covers documented operations with on-site reference pages.

## This page

- **On-site (HTML):** [https://www.socialfetch.dev/docs/integrations/mcp](https://www.socialfetch.dev/docs/integrations/mcp)
- **Markdown (.mdx) URL:** [https://www.socialfetch.dev/docs/integrations/mcp.mdx](https://www.socialfetch.dev/docs/integrations/mcp.mdx)

## API base URL and authentication

- **API origin (from OpenAPI `servers`):** `https://api.socialfetch.dev`
- **Authentication:** send `x-api-key: sfk_...` on `/v1/**` routes unless the operation is explicitly anonymous (check OpenAPI `security`, the [API reference hub](https://www.socialfetch.dev/docs/api.mdx), [`/llms.txt`](https://www.socialfetch.dev/llms.txt), or [`/llms.json`](https://www.socialfetch.dev/llms.json) for each route).
- **OpenAPI JSON:** [https://www.socialfetch.dev/openapi.json](https://www.socialfetch.dev/openapi.json)

## Recommended docs entrypoints (this site)

- [Documentation overview](https://www.socialfetch.dev/docs.mdx) — top-level orientation (markdown).
- [Quickstart](https://www.socialfetch.dev/docs/quickstart.mdx) — authenticate with `x-api-key`, validate auth with `whoami`, and understand the JSON envelope.
- [SDK](https://www.socialfetch.dev/docs/sdk.mdx) — official TypeScript SDK guide, including `SocialFetchClient`, `Result`, and `unwrap()`.
- [SDK reference](https://www.socialfetch.dev/docs/sdk-reference.mdx) — exhaustive SDK method inventory and route mapping for agents, tooling, and power users.
- [Choose the right endpoint](https://www.socialfetch.dev/docs/choose-endpoint.mdx) — task-oriented route selection for smoke tests, profiles, list endpoints, and single-item lookups.
- [Capability matrix](https://www.socialfetch.dev/docs/capability-matrix.mdx) — fast comparison of identifiers, pagination, outcomes, media download, and SDK coverage.
- [Integrations](https://www.socialfetch.dev/docs/integrations.mdx) — MCP for AI clients, n8n community node, SDK, and REST API connection paths.
- [MCP integration](https://www.socialfetch.dev/docs/integrations/mcp.mdx) — hosted `/mcp` server, OAuth, Cursor/VS Code/Claude install snippets, 87 endpoint tools, plus docs_search/docs_read for implementation help.
- [n8n integration](https://www.socialfetch.dev/docs/integrations/n8n.mdx) — install `n8n-nodes-socialfetch`, credentials, and workflow examples.
- [`/llms.json`](https://www.socialfetch.dev/llms.json) — structured machine-readable operation inventory with parameter names, pagination, outcomes, credits, and SDK mapping.
- [API reference hub](https://www.socialfetch.dev/docs/api.mdx) — human-friendly index of operations with links into generated pages.
- [Errors](https://www.socialfetch.dev/docs/errors.mdx) — shared error envelope and HTTP status guidance.
- [Credits](https://www.socialfetch.dev/docs/credits.mdx) — metering, `402`, and planning batch jobs.
- Outcome semantics such as `found`, `not_found`, and `private` are documented in [Errors](https://www.socialfetch.dev/docs/errors.mdx) and on operation pages when present in the OpenAPI contract.

## Markdown docs convention

- Every docs page has a markdown twin: append **`.mdx`** to the docs pathname (for example `/docs/quickstart` → `/docs/quickstart.mdx`).
- Agents that send `Accept: text/markdown` on `/docs/**` HTML URLs may receive markdown directly (same URL, `Vary: Accept`).

---
# MCP (https://www.socialfetch.dev/docs/integrations/mcp)

**Model Context Protocol (MCP)** turns Social Fetch into tools your AI assistant can call directly — TikTok profiles, Instagram posts, YouTube search, web markdown, account balance, and every other [public API endpoint](/docs/api). Endpoint tools are billed exactly like the REST API; docs tools help you implement the API in your project without consuming credits.

The hosted server lives at **`https://api.socialfetch.dev/mcp`**. You sign in once with **OAuth** in your browser — there's no API key to paste into your config.

What you'll need

* A **Social Fetch account** with credits for metered routes — see [Credits & billing](/docs/credits).
* An **MCP client** that supports remote (Streamable HTTP) servers with OAuth — Cursor, VS Code, Claude Code, Claude Desktop, or the MCP Inspector.

One-click install

Manual setup

If a one-click link does nothing — your editor isn't installed, blocks custom URL schemes, or has no button — add the server by hand.

Cursor

Add to `~/.cursor/mcp.json` (or project `.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "socialfetch": {
      "url": "https://api.socialfetch.dev/mcp"
    }
  }
}
```

Restart Cursor, open MCP settings, and complete the **OAuth** browser flow when prompted.

VS Code

Add to `settings.json`:

```json
{
  "mcp": {
    "servers": {
      "socialfetch": {
        "url": "https://api.socialfetch.dev/mcp"
      }
    }
  }
}
```

Claude Code

```bash
claude mcp add --transport http socialfetch https://api.socialfetch.dev/mcp
```

Then run `/mcp` and authenticate Social Fetch to finish the OAuth flow.

Claude Desktop

Add a **custom connector** (remote MCP) with URL `https://api.socialfetch.dev/mcp` and authorize when asked.

stdio-only clients

If your client only speaks stdio, bridge to the hosted server with `mcp-remote`:

```bash
npx mcp-remote https://api.socialfetch.dev/mcp
```

Point your client at the stdio process it spawns.

Authentication

Social Fetch uses **OAuth 2.1** — your client handles the whole flow:

1. The client opens the Social Fetch sign-in page in your browser.
2. You sign in (or create an account) and approve access.
3. The client receives an access token and sends it on every request.

Credits are charged to your **signed-in account**, just like the REST API. There's no API key in your MCP config.

Tools

`tools/list` exposes **endpoint tools** (one per public API route) plus **docs tools** for implementation help.

Endpoint tools

Tool names match API operation IDs with dots replaced by underscores:

| Tool name               | API operation           |
| ----------------------- | ----------------------- |
| `tiktok_profile_get`    | `tiktok.profile.get`    |
| `instagram_post_get`    | `instagram.post.get`    |
| `web_markdown_generate` | `web.markdown.generate` |
| `auth_whoami`           | `auth.whoami`           |
| `billing_balance_get`   | `billing.balance.get`   |

Each endpoint tool's arguments mirror the matching route's parameters. Credits are metered the same way as REST — most calls cost 1 credit, while some search and media-download options cost more. See each operation's [API reference](/docs/api) page for exact pricing.

Docs tools

Two extra tools let your coding agent read the live Social Fetch docs while it builds — picking the right endpoint, following SDK examples, and checking auth, errors, and credits. Both are **read-only** and **don't consume credits**.

| Tool name     | Purpose                                                         |
| ------------- | --------------------------------------------------------------- |
| `docs_search` | Search the docs (API, SDK, auth, errors, credits, integrations) |
| `docs_read`   | Read a full docs page as markdown by pathname, e.g. `/docs/sdk` |

Try a prompt like:

> Use the Social Fetch MCP docs to add TikTok profile lookup to this app with the TypeScript SDK.

Example: TikTok profile

In Cursor or the MCP Inspector, call `tiktok_profile_get` with:

```json
{ "handle": "nike" }
```

The result contains the same `data` and `meta` payload you'd get from the REST endpoint.

Troubleshooting

| Symptom             | What to check                                                                             |
| ------------------- | ----------------------------------------------------------------------------------------- |
| `401` on every call | Your token is missing or expired — reconnect and complete OAuth again.                    |
| OAuth redirect loop | Finish signing in at the Social Fetch app, then approve access to return to your client.  |
| `402` responses     | You're out of credits for a metered route — top up in [Credits & billing](/docs/credits). |
| No tools listed     | Reconnect the server; if it persists, restart your client.                                |

Related

- [API reference](/docs/api) — Every operation, parameter, and response shape the MCP tools wrap.

- [Credits & billing](/docs/credits) — How credits are metered across MCP and REST.

- [n8n](/docs/integrations/n8n) — No-code workflows with an API key instead of OAuth.