> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sociavault.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Use SociaVault from Claude, Cursor, VS Code, ChatGPT, and any AI agent with the official MCP server

## Give your AI assistant live social data

The **SociaVault MCP server** connects your AI assistant directly to the SociaVault API using the [Model Context Protocol](https://modelcontextprotocol.io) — an open standard for plugging tools into AI clients. Claude, Cursor, VS Code, Cline, ChatGPT, and any other MCP-compatible client can pull real-time data from **11 platforms** and reason over it, in plain English.

It exposes **107 tools** covering profiles, posts, comments, transcripts, search, trends, and ad libraries — every one mapped to a documented SociaVault endpoint.

There are two ways to connect, and they expose the exact same tools:

* **Local** — runs on your machine via `npx`. Best for Claude Desktop, Cursor, VS Code, and Cline.
* **Remote (hosted)** — our hosted server at `https://mcp.sociavault.net/mcp`. Nothing to install. Required for **ChatGPT** and handy for any client that connects to a remote MCP URL.

<CardGroup cols={2}>
  <Card title="npm package" icon="npm" href="https://www.npmjs.com/package/sociavault-mcp">
    sociavault-mcp on npm
  </Card>

  <Card title="MCP Registry" icon="server" href="https://registry.modelcontextprotocol.io">
    Listed on the official registry
  </Card>

  <Card title="Smithery" icon="package" href="https://smithery.ai/server/olaniyanolamide42/sociavault-mcp">
    Install via Smithery
  </Card>

  <Card title="Full guide" icon="book" href="https://sociavault.com/blog/social-media-mcp-server">
    Read the complete walkthrough
  </Card>
</CardGroup>

## Local install (Claude, Cursor, VS Code, Cline)

The server runs through `npx`, so there's nothing to install globally — your client fetches the latest version automatically.

<Steps>
  <Step title="Get your API key">
    Sign up at [sociavault.com](https://sociavault.com/signup) and copy your API key (format `sk_live_...`) from the [Dashboard](https://sociavault.com/dashboard).
  </Step>

  <Step title="Add the server to your client">
    Pick your client below and add the configuration with your API key.

    <CodeGroup>
      ```json Claude Desktop theme={null}
      {
        "mcpServers": {
          "sociavault": {
            "command": "npx",
            "args": ["-y", "sociavault-mcp"],
            "env": {
              "SOCIAVAULT_API_KEY": "sk_live_your_key_here"
            }
          }
        }
      }
      ```

      ```json Cursor theme={null}
      {
        "mcpServers": {
          "sociavault": {
            "command": "npx",
            "args": ["-y", "sociavault-mcp"],
            "env": { "SOCIAVAULT_API_KEY": "sk_live_your_key_here" }
          }
        }
      }
      ```

      ```json VS Code theme={null}
      {
        "servers": {
          "sociavault": {
            "command": "npx",
            "args": ["-y", "sociavault-mcp"],
            "env": { "SOCIAVAULT_API_KEY": "sk_live_your_key_here" }
          }
        }
      }
      ```
    </CodeGroup>

    <Info>
      **Claude Desktop config location** — macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` · Windows: `%APPDATA%\Claude\claude_desktop_config.json`. **Cursor**: `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per-project). **VS Code**: `.vscode/mcp.json`.
    </Info>
  </Step>

  <Step title="Restart and ask a question">
    Restart your client and try: *"Get the TikTok profile for @nike."* If you get back follower counts and bio details, you're live.

    <Check>
      Your AI assistant now has live access to social media data across 11 platforms.
    </Check>
  </Step>
</Steps>

## Remote server (ChatGPT & other hosted clients)

Prefer not to install anything, or connecting from ChatGPT? Use our hosted server. It runs the same 107 tools and requires no local setup — you just point your client at a URL and supply your API key.

```
https://mcp.sociavault.net/mcp
```

### Authentication

The hosted server bills usage to **your** account, so every request must carry your SociaVault API key. Provide it either way:

* **URL query** — append `?apiKey=sk_live_your_key_here` to the endpoint. Works with every client, including ones that can't set custom headers.
* **Header** — send `x-api-key: sk_live_your_key_here` (or `Authorization: Bearer sk_live_...`).

<Warning>
  A key placed in the URL can show up in server logs and browser history. If
  your client supports custom headers, prefer the `x-api-key` header. Treat the
  URL as a secret either way, and rotate the key from your
  [Dashboard](https://sociavault.com/dashboard) if it leaks.
</Warning>

### Connect from ChatGPT

<Info>
  ChatGPT's custom MCP connectors require **Developer Mode**, available on paid
  ChatGPT plans (Pro, Business, Enterprise, Edu). This is an OpenAI setting, not
  a SociaVault one.
</Info>

<Steps>
  <Step title="Enable Developer Mode">
    In ChatGPT, open **Settings → Connectors → Advanced** and turn on
    **Developer mode**.
  </Step>

  <Step title="Add a custom connector">
    Go to **Settings → Connectors → Create**, and enter:

    * **Name:** `SociaVault`
    * **MCP Server URL:** `https://mcp.sociavault.net/mcp?apiKey=sk_live_your_key_here`
    * **Authentication:** No authentication (your key is already in the URL)
  </Step>

  <Step title="Use it in a chat">
    Enable the SociaVault connector for your conversation, then ask something
    like *"Get the TikTok profile for @nike."*

    <Check>
      ChatGPT now pulls live social data through the hosted SociaVault server.
    </Check>
  </Step>
</Steps>

### Connect from other clients

Any client that supports remote MCP servers (Claude, Cursor, and others) can use the hosted URL instead of the local `npx` setup — point it at `https://mcp.sociavault.net/mcp?apiKey=sk_live_your_key_here`.

## Configuration

<ParamField path="SOCIAVAULT_API_KEY" type="string" required>
  Your SociaVault API key (`sk_live_...`). Get one at the
  [Dashboard](https://sociavault.com/dashboard).
</ParamField>

<ParamField path="SOCIAVAULT_BASE_URL" type="string">
  Optional override for the API base URL. Defaults to
  `https://api.sociavault.com`.
</ParamField>

## Example prompts

The model picks the right tool automatically — you just describe what you want:

<AccordionGroup>
  <Accordion title="Creator research" icon="user">
    "Compare the follower counts and engagement of @cristiano on Instagram vs.
    his YouTube channel."
  </Accordion>

  <Accordion title="Competitor ad intelligence" icon="rectangle-ad">
    "Search the Meta Ad Library for active Nike ads in the US and summarize
    their angles."
  </Accordion>

  <Accordion title="Content repurposing" icon="closed-captioning">
    "Get the transcript of this YouTube video and turn it into a LinkedIn post:
    \<url>"
  </Accordion>

  <Accordion title="Social listening" icon="magnifying-glass">
    "Pull the last 30 posts from r/webscraping and tell me the recurring pain
    points."
  </Accordion>

  <Accordion title="Trend monitoring" icon="arrow-trend-up">
    "What's trending on TikTok in the US right now, and which sounds are
    surging?"
  </Accordion>
</AccordionGroup>

## What's included

All tools are read-only. Most accept a `trim` option (on by default) that returns a smaller, AI-friendly payload to conserve context-window tokens. List endpoints support cursor pagination.

<CardGroup cols={3}>
  <Card title="TikTok" icon="tiktok">
    Profiles, videos, comments, transcripts, search, music, trending
  </Card>

  <Card title="Instagram" icon="instagram">
    Profiles, posts, reels, comments, transcripts, highlights
  </Card>

  <Card title="YouTube" icon="youtube">
    Channels, videos, shorts, transcripts, search, comments
  </Card>

  <Card title="Twitter / X" icon="x-twitter">
    Profiles, tweets, replies, quotes, retweets, search
  </Card>

  <Card title="LinkedIn" icon="linkedin">
    Profiles, companies, posts
  </Card>

  <Card title="Facebook" icon="facebook">
    Profiles, posts, reels, groups, comments, transcripts
  </Card>

  <Card title="Reddit" icon="reddit">
    Subreddits, posts, comments, transcripts, search
  </Card>

  <Card title="Threads, Pinterest, Twitch" icon="layer-group">
    Profiles, posts, pins, boards, clips, schedules
  </Card>

  <Card title="Ad libraries" icon="rectangle-ad">
    TikTok, Meta, Google, and LinkedIn ad libraries
  </Card>
</CardGroup>

## Pricing

The MCP server is free and open source. You only pay for the SociaVault API usage it makes, billed in **credits** — the same [credit-based pricing](https://sociavault.com/pricing) as the REST API. New accounts start with free credits, and you can check your balance any time by asking your assistant to run the `check_credits` tool.

## FAQ

<AccordionGroup>
  <Accordion title="Which clients are supported?">
    Any MCP-compatible client. For local install (Claude Desktop, Cursor, VS
    Code Copilot, Cline), run `npx -y sociavault-mcp` with your API key in the
    environment. For ChatGPT — and any client that connects to a remote MCP URL
    — use the hosted server at `https://mcp.sociavault.net/mcp` instead.
  </Accordion>

  <Accordion title="Is my API key safe?">
    With the local install, your key stays in your own client's config and is
    sent only to the SociaVault API. With the hosted server, your key is passed
    through our server to the API to authenticate the request — it isn't stored.
    Either way the server is read-only: it never posts or changes anything. If
    you use the URL query method, prefer the `x-api-key` header where your
    client supports it, and rotate the key from your Dashboard if it leaks.
  </Accordion>

  <Accordion title="Do I need Node.js?">
    Only for the local install — Node.js 18 or newer, since it runs via `npx`.
    Most developer machines already have it. The hosted server
    (`https://mcp.sociavault.net/mcp`) needs nothing installed.
  </Accordion>

  <Accordion title="How do I update it?">
    Because it runs with `npx -y sociavault-mcp`, your client always fetches the
    latest published version. There's nothing to update manually.
  </Accordion>
</AccordionGroup>

## Need help?

<CardGroup cols={2}>
  <Card title="Email Support" icon="envelope" href="mailto:support@sociavault.com">
    Get help from our team
  </Card>

  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Prefer raw REST? Start here
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.