MCP Server

MCP Server

The SocialKit MCP server exposes selected REST operations as Model Context Protocol tools, so an AI agent — Claude Desktop, Claude Code, Cursor, or any custom client that speaks MCP — can call SocialKit directly from a chat or coding session.

The server is hosted at https://mcp.socialkit.dev and ships 46 tools across YouTube, TikTok, Instagram, Facebook, X, LinkedIn, direct video URLs, and shared download jobs. REST also provides Reddit, bulk, account-credit, and service-status operations that are not MCP tools.

Working in a coding agent like Claude Code, Cursor, or Codex? You may prefer Agent Skills instead — they call the REST API directly with one command and need no MCP server.

Connection URL

https://mcp.socialkit.dev/mcp

The transport is HTTP-streamable (the standard for remote MCP servers — Claude Desktop, Cursor, Claude Code, and the MCP Inspector all support it natively). No CLI install, no binary download.

Authentication

Codex and Claude Code can connect through browser login and project consent at https://mcp.socialkit.dev/oauth/mcp. Follow Connect with OAuth below. You do not need to copy your project key into those clients.

The /mcp endpoint uses your project access key. It forwards that key to https://api.socialkit.dev, which handles auth, credit accounting, and rate limiting. The same access key you’d use for a direct API call works here too.

Manage your access key on your project’s Access Keys page. Treat it like a password — never paste it into a public repo or share it in client-side code.

The MCP server accepts the access key three ways, in this priority order:

  • Authorization: Bearer <your-access-key> header — the standard for HTTP-streamable MCP clients (Claude Desktop, Cursor, Claude Code).
  • x-access-key: <your-access-key> header — same header the REST API accepts directly.
  • ?access_key=<your-access-key> query string — for clients that don’t support custom headers.

Tools are listed even without a key — calls only fail (with an authentication error surfaced back to the model, commonly HTTP 403 for an invalid key) once the agent actually tries to invoke one.

Connect with OAuth

Use a current Codex or Claude Code release. Sign in to SocialKit in the browser, check the client name, select a project where you are an approved Developer, Admin, or Owner, and select Allow access. The connection uses that project’s credits. You can revoke it from Access keys → Connected agents.

Codex CLI and IDE

Add this server entry to your Codex ~/.codex/config.toml. If a socialkit entry already exists, replace that entry rather than adding a duplicate:

[mcp_servers.socialkit]
url = "https://mcp.socialkit.dev/oauth/mcp"
oauth_resource = "https://mcp.socialkit.dev/oauth/mcp"
scopes = ["socialkit:tools", "offline_access"]
 
[mcp_servers.socialkit.oauth]
client_id = "socialkit-codex"
callback_url = "http://127.0.0.1:3137/callback"
callback_port = 3137

Then sign in:

codex mcp login socialkit --scopes socialkit:tools,offline_access

The CLI and IDE extension share this configuration. Start a new agent session after connecting. See Codex MCP configuration.

Claude Code

Run this from your project directory. If a socialkit MCP entry already exists in this scope, remove that entry with claude mcp remove socialkit before adding the OAuth connection:

claude mcp add-json --scope local socialkit '{"type":"http","url":"https://mcp.socialkit.dev/oauth/mcp","oauth":{"clientId":"socialkit-claude-code","callbackPort":3138,"scopes":"socialkit:tools offline_access"}}'
claude mcp login socialkit

Claude Code uses http://localhost:3138/callback. Keep the registered client ID and callback port unchanged. See Claude Code MCP authentication.

Verify and manage the connection

Ask your agent: “List the available SocialKit tools without making a data request.” Discovery is free. To verify data access, provide a public video URL and ask it to make one youtube_stats call; that uses the normal endpoint credits.

Access tokens last 15 minutes and refresh automatically for up to 30 days after approval. After expiry or revocation, run the login command again. Both clients support mcp login socialkit --no-browser for a headless session; follow the client’s instructions to paste the callback URL into your own terminal. Never share the callback URL in chat or commit it.

The registered callbacks use fixed ports, so close another process using port 3137 or 3138 before login. Cursor, Claude Desktop, and other clients can continue using the access-key instructions below. OAuth clients require an explicit registration; dynamic registration and marketplace installation are separate from these CLI connections.

Add to Claude Desktop

The fastest way is Claude’s built-in custom connector — no config file, no restart.

  1. In Claude Desktop (or Claude on the web), open Customize → Connectors (on some versions it’s Settings → Connectors).
  2. Click Add custom connector.
  3. Give it a name — e.g. SocialKit — and, under Remote MCP server URL, paste the URL below with your own access key swapped in for YOUR_ACCESS_KEY:
https://mcp.socialkit.dev/mcp?access_key=YOUR_ACCESS_KEY
  1. Click Add. The tools appear right away. Try asking: “Summarize this YouTube video: https://www.youtube.com/watch?v=…”

Your access key lives on your project’s Access Keys page. It’s carried in the URL here because the connector UI doesn’t take custom headers — keep that connector config private (it grants full API access and spends credits).

Add to Claude Code

Set SOCIALKIT_API_KEY in your private terminal as described in Agent Skills, then run from your project directory. This command saves the expanded key in local client configuration; keep that configuration private:

claude mcp add --transport http --scope local socialkit https://mcp.socialkit.dev/mcp \
  --header "Authorization: Bearer $SOCIALKIT_API_KEY"

Claude Code picks the tools up immediately on the next session.

Add to Codex CLI or IDE

Set SOCIALKIT_API_KEY in the environment that launches Codex, then register:

codex mcp add socialkit --url https://mcp.socialkit.dev/mcp \
  --bearer-token-env-var SOCIALKIT_API_KEY

Codex CLI and its IDE extension share MCP configuration. The key is read from the named environment variable; follow the IDE environment instructions when using the extension. Run codex mcp list to check registration, then start a new session. Tool discovery alone does not verify the key. Use the free REST /test check before a bounded data request.

Add to Cursor

Set SOCIALKIT_API_KEY in the environment that launches Cursor, then add this to .cursor/mcp.json:

{
  "mcpServers": {
    "socialkit": {
      "url": "https://mcp.socialkit.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${env:SOCIALKIT_API_KEY}"
      }
    }
  }
}

Cursor resolves the named environment variable at runtime. Remote MCP entries do not load an envFile; use the IDE environment setup. See Cursor’s MCP configuration reference for project/global settings.

Use it from any MCP client

Any client that speaks the JSON-RPC 2.0 MCP protocol over HTTP-streamable transport works. Minimum viable call:

curl -X POST https://mcp.socialkit.dev/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer YOUR_ACCESS_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

Returns the list of all 46 tools with their input schemas.

Available tools

Tools are grouped by platform. Each one is a thin wrapper over the corresponding REST endpoint — same inputs, same response shapes.

YouTube (8) — youtube_transcript, youtube_summarize, youtube_stats, youtube_comments, youtube_channel_stats, youtube_videos, youtube_search, youtube_download

TikTok (9) — tiktok_transcript, tiktok_summarize, tiktok_stats, tiktok_comments, tiktok_channel_stats, tiktok_search, tiktok_hashtag_search, tiktok_channel_videos, tiktok_download

Instagram (9) — instagram_transcript, instagram_summarize, instagram_stats, instagram_comments, instagram_channel_stats, instagram_channel_posts, instagram_channel_reels, instagram_reels_search, instagram_download

Facebook (5) — facebook_transcript, facebook_summarize, facebook_stats, facebook_comments, facebook_channel_stats

Twitter / X (6) — twitter_profile, twitter_tweets, twitter_tweet, twitter_thread, twitter_article, twitter_transcript

LinkedIn (5) — linkedin_profile, linkedin_company, linkedin_company_posts, linkedin_post, linkedin_transcript

Direct video (2) — video_transcript, video_summarize (for any direct video file URL — S3, CDN, etc.)

Shared downloads (2) — download_async, download_status

The tools/list response is the authoritative MCP input schema. The REST playground documents the underlying HTTP operations. For example, ask “Get the comments for this Instagram Reel” with a public Reel URL; ask for a request limit before collecting multiple pages.

Example: call a tool directly

curl -X POST https://mcp.socialkit.dev/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer YOUR_ACCESS_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "instagram_stats",
      "arguments": {
        "url": "https://www.instagram.com/reel/DHeBXm5tBLu/"
      }
    }
  }'

The response (streamed as Server-Sent Events) contains a content array with a JSON-stringified payload — the same shape returned by POST /instagram/stats on the REST API.

Read an X Article

Ask your agent: “Read this X Article with twitter_article and return its full Markdown with the author and source link: https://x.com/DimitrisPapail/article/2026531440414925307”.

The tool accepts { "url": "https://x.com/DimitrisPapail/article/2026531440414925307" } and calls POST /twitter/article. It returns the full text, Markdown, metadata, and media references in the REST response shape. A current /i/article/POST_ID share link or the associated post URL works too. The returned article entity ID differs from the source post ID used in these links.

Only content available while signed out can be extracted; no X account is required. A complete extraction costs 1 credit, and failures cost 0 credits. A regular post, an external website link, or an incomplete article preview does not produce a successful article extraction. Use twitter_thread for a sequence of posts.

Credits and rate limiting

Every tool call costs the same as the REST call it wraps. Costs depend on the operation, result count, video duration, and download quality; see the endpoint-specific tiers in the API Reference. Failed calls are free. Free tier users get 20 credits, and per-tier rate limits (40/120/360/600 requests per minute by plan) still apply.

Troubleshooting

  • Tools list shows up but every call returns success: false with _httpStatus: 401 — your access key isn’t being forwarded. Re-check the Authorization: Bearer … header in your client config.
  • A specific tool call returns success: false with a 4xx — that’s the upstream API rejecting the request (invalid URL, video not found, etc.). The error message is the same as you’d get hitting the REST endpoint directly.
  • 429 Rate limit exceeded — you’ve hit the per-minute cap for your plan tier. Wait the duration in the Retry-After response header or upgrade your plan.
  • Tool doesn’t appear in your client’s tools panel — your client may need to be restarted, or it may not yet support HTTP-streamable transport. Try the curl smoke test above first to confirm the server itself is reachable.

Security reminders

  • Treat your access key like a password — it grants full API privileges and consumes credits.
  • Never paste your access key into a shared MCP config that gets committed to a public repo. Use your client’s secret/env-var support instead.
  • Rotate the key from your dashboard if you suspect it’s been exposed.

Scope and errors

Use public content. Posting, private-account access, and unrelated website scraping are unsupported. Pagination varies by tool; follow its input schema and returned cursors. A missing metric is unknown, not zero. Preserve partial-result and error fields, set a request budget, and avoid unbounded retries. A tool response is not a guarantee that every requested item or transcript was available.

Use project keys on /mcp and OAuth tokens on /oauth/mcp. Do not use an OAuth access token as a project key.

TroubleshootingAgent Skills