The social media MCP server and API

One API key runs the whole product. An AI agent — Claude, Claude Code, Codex, anything that speaks JSON over HTTP — can read the unified inbox and reply to comments and DMs, create, caption, schedule and publish posts, manage comment-keyword automations and calendar notes, read analytics, and do full video edits in the free AI video editor. These are the same routes the app itself calls, so every validation, credit meter and guard applies to an agent exactly as it applies to a person clicking.

Two things stay human on purpose: video Export (rendering runs in the browser, so a person presses the button after checking the work), and anything that touches money, account settings or channel connections — those never accept a key at all.

If you just want your AI assistant to run your BetterSocials, you can skip the rest of this page. There is no key to copy and nothing to install: paste one address into the app you already use, then sign in when it asks.

https://bettersocials.ai/api/mcp

Claude (claude.ai, desktop or mobile): Settings → Connectors → Add custom connector. Name it BetterSocials, paste the address above, then Add and Connect. Claude opens a BetterSocials sign-in, you approve, and the tools show up in your next chat. Custom connectors need a paid Claude plan. Step by step: connect Claude to BetterSocials.

ChatGPT: Settings → Developer mode (under Plugins) to turn it on, then close Settings and open Plugins in the left sidebar. The plugin is made there, not on the settings screen. Hit the plus button, name it BetterSocials, leave Connection on Server URL and paste the address above, leave Authentication on OAuth, tick “I understand and want to continue” (Create stays disabled until you do), and Create. ChatGPT walks you through the same sign-in and approval, and you switch it on per chat from the composer’s plus menu under Developer mode. Developer mode needs a paid ChatGPT plan on the web, and write actions ask you to confirm each time. Step by step: connect ChatGPT to BetterSocials.

Both doors ask for a name and neither enforces one. Use BetterSocials in both anyway: the name is how you aim a prompt at these tools, and every example here says “use the BetterSocials tools”.

The connection acts with your workspace’s normal limits, and Settings → Connected apps in BetterSocials disconnects it in one click.

The hosted MCP server wraps the same contract as tools, over Streamable HTTP. One command in Claude Code:

claude mcp add --transport http bettersocials https://bettersocials.ai/api/mcp \
  --header "Authorization: Bearer br_YOUR_KEY"

Tools cover the same surface: get_inbox, get_thread, send_reply, draft_reply, create_post, generate_captions, list_queues, list_keywords, create_keyword, get_analytics, list_connections, the Studio project tools, create_upload_url, and more — get_capabilities always lists the current set.

Every key is scoped to one workspace, stored as a SHA-256 hash, revocable in one click, and rate-limited in three tiers: reads (600 per 5 minutes), writes (120), and sends — anything that leaves the app onto a real social account — at 30. Tripped limits page our security channel. Key management, billing, account settings and channel connect/disconnect stay session-only, so a leaked key can never mint more keys, spend money, or deprovision an account. Sends run through the same claim locks and failure ledger the app uses — an agent cannot send around a guard. Repeated invalid keys get throttled per network and page us too.

Every response from the agent surface carries a docs object linking to https://bettersocials.ai/api/meta — the live manifest of every endpoint, rule and limit. Point your agent at it once and it always knows what it can do, including things we shipped after you wrote your integration. The MCP server exposes the same thing as the get_capabilities tool, and /llms.txt maps the whole site for assistants.

Mint an API key in Settings → API keys. Keys are shown once, stored as a SHA-256 hash, capped at five active per workspace, and scoped to that workspace — an id in a URL never reaches across. Key management itself stays in the app, so a leaked key can never mint or revoke keys.

curl -s https://bettersocials.ai/api/studio/editor/projects \
  -H "Authorization: Bearer br_YOUR_KEY"

1. Read. GET the project. The whole edit is one JSON document — clips, cuts, captions, overlays, effects, sounds. Keep the updatedAt you read.
2. Modify. Change the document in memory. Cuts are kept source ranges; overlay, effect and sound times are output seconds.
3. Write. PATCH the whole document back with baseUpdatedAt. A stale base is a 409 — re-read, re-apply, retry. Identical content is a free no-op.
4. Watch. Any open editor tab applies your patch live within about a second, and the creator can undo it with ⌘Z like their own edit.

Media bytes never ride the document. Ask POST /api/studio/editor/media/upload for a signed URL, PUT the file straight to storage, then reference the returned publicUrl as a clip or overlay sourceUrl. The open editor fetches it once into its local vault. Supply analysis (word timings plus measured speech bounds) with a clip and the editor never re-charges transcription.

• Auth: `Authorization: Bearer br_…` — mint keys in Settings → API keys (shown once, 5 active per workspace, SHA-256 at rest). Every workspace has API access. A presented key is judged alone; key management stays in-session.
• MCP without a key: claude.ai and ChatGPT connect through OAuth. Paste the MCP endpoint into their connector settings and sign in when asked. The granted token has the same authority and limits as an API key, and Settings → Connected apps disconnects it instantly.
• The workspace is resolved from the key. Ids in URLs never cross workspaces.
• Every bearer call is rate limited per workspace in three tiers: reads 600/5min, writes 120/5min, sends 30/5min — MCP tools included. A 429 carries Retry-After — back off and retry; tripped limits alert our security channel. Repeated invalid keys are throttled per network.
• Sends are sacred: send_reply / publishNow / publishDraft / retry act on the creator’s REAL social accounts. Do them only on explicit instruction or standing rules the creator set. Every send passes the same claim locks, account resolution and failure ledger the app itself uses.
• Session-only forever: key management (BetterSocials API keys AND stored vendor keys in Settings → AI keys), billing, account/profile, workspace management, and connecting/disconnecting channels. A leaked key can never mint keys, spend money, or deprovision an account.
• Bring your own vendor key: a workspace can store its own ElevenLabs or kie.ai API key in Settings → AI keys. When present, generate_voiceover / generate_image run on that key with NO credit debit — the free editor plan included. Stored keys are encrypted at rest, never readable back, and never manageable over this API.
• AI generation (drafts, captions) spends the workspace’s credits exactly like the in-app buttons — an agent can never generate more cheaply than a human.
• Credit transparency: the FIRST time in a conversation you are about to call a credit-spending tool (generate_voiceover, generate_image, transcribe_clip, draft_reply, generate_captions), tell the creator the cost in credits before running it. Once they have okayed a spend in that conversation, do not re-ask on every call — but DO surface every creditsSpent (and creditsRemaining when returned) in your reply, so nothing drains credits invisibly.
• PATCH replaces the whole document. A partial doc is a valid doc with everything else missing — always GET → modify → PATCH. For a small change (captions, title card, speed, a cut) use /projects/:id/edits (MCP: edit_project) instead: no round-trip, and every op answers applied-or-why-not.
• Optimistic concurrency: send `baseUpdatedAt` (the `updatedAt` you read). Stale = 409 → re-GET, re-apply, re-PATCH.
• Identical-content PATCHes are no-ops — retries are free and never fight an open editor tab.
• Docs are sanitized both directions: unknown fields drop, numbers clamp. Diff the response against what you sent.
• Media bytes never ride the doc. Upload via /media/upload (or host them yourself) and reference the URL as `sourceUrl` on clips, overlays, sounds and green-screen backgrounds; any open editor ingests it once into its local vault.
• Sandboxed and cannot PUT to storage? Never a dead end: POST /media/import fetches a public URL server-side into the bucket (MCP: import_media), or the creator drops the file into the composer and GET /media/uploads (MCP: list_media) finds it.
• Supply `analysis` (ASR words + measured speech bounds) with a clip and the editor never re-charges transcription.
• Every successful write pings open editor tabs live (≈1s). Agent edits land as undo steps — ⌘Z works on them.
• Export stays human: rendering is client-side by design, so a person presses Export in the tab. Everything up to that button is yours.
• Uploaded media not referenced by any project document within 48 hours is swept.
• Trial Reels is available to every workspace. The `trial_reels` flag is the per-workspace revoke rail, not a beta gate: where it has been revoked every /api/trials/* route answers 404 — including for a key that works everywhere else on this API. A 404 there still means "not enabled", not "wrong id".
• Reading trial numbers honestly: an ig_trial reel is shown to NON-FOLLOWERS only, so its reach and views ARE non-follower reach — there is no separate field for that and none is needed. The stored metrics are views, impressions, reach, likes, comments, shares and saves. Watch time is not among them and never will be: our provider does not report it, so never quote it or imply it.

Every BetterSocials workspace has API access — sign up, mint a key in Settings → API keys, and go. Something missing that your agent needs? Tell us through the in-app support chat — gaps in this surface get closed fast, and the manifest at /api/metais how you’ll see them land.

What is an MCP server?

MCP, the Model Context Protocol, is the open standard that lets AI assistants operate other software. An MCP server turns a product into tools an assistant can call. BetterSocials hosts one at https://bettersocials.ai/api/mcp. Connect it once and Claude or ChatGPT can post, reply, and edit video in your account from a normal chat.

How do I connect Claude to BetterSocials?

In Claude (claude.ai, desktop or mobile): Settings, then Connectors, then Add custom connector. Name it BetterSocials, paste https://bettersocials.ai/api/mcp, then Add and Connect. Claude opens a BetterSocials sign-in, you approve, and the tools show up in your next chat. Custom connectors need a paid Claude plan.

How do I connect ChatGPT to BetterSocials?

Turn on Developer mode in ChatGPT Settings (under Plugins), then create the plugin from the Plugins page in the left sidebar, not the settings screen. Name it BetterSocials, paste https://bettersocials.ai/api/mcp as the Server URL, leave Authentication on OAuth, tick the confirmation box, and Create. Developer mode needs a paid ChatGPT plan on the web.

Do I need to be a developer to use this?

No. The Claude and ChatGPT doors are paste-one-address setups with a normal sign-in, and there is no key to manage. Keys and the REST API exist for people building scripts and agents; most people never touch them.

Is the BetterSocials API free?

Every workspace has API access, including the free video editor plan, and there is no separate API price. Agent actions that generate things, like AI drafts, captions, and voiceovers, spend the same credits the in-app buttons do.

Can an agent post or send DMs without me knowing?

Not quietly. Anything that reaches a real social account is a send: Claude and ChatGPT ask before each one unless you tell them to stop asking, sends are rate-limited to 30 per 5 minutes, and every send passes the same locks and failure ledger the app itself uses. You can disconnect any agent in one click from Settings → Connected apps.