Brainy SocialBY IS&S

Developers and AI assistants

Brainy Social developer docs

Let Claude, ChatGPT and your own code read your Brand Brain and create, schedule and track posts on Instagram, Facebook, TikTok, YouTube, LinkedIn and X.

Last updated: November 19, 2026

Connect Claude or ChatGPT (MCP)

Brainy Social is an MCP server with its own OAuth 2.1 sign-in. Claude and ChatGPT only need the server URL: you sign in with your Brainy account, choose one workspace and the access, and no token is copied anywhere.

MCP server URL

https://brainy-social.com/api/mcp

In Claude (claude.ai or Claude Desktop)

  1. Open Settings → Connectors → Add custom connector.
  2. Paste the MCP server URL and click Add, then Connect.
  3. Brainy Social opens: sign in if asked, choose the workspace and the access (read, or read and publish), then click Allow.
  4. You're back in Claude with the Brainy tools turned on.

In ChatGPT

  1. Open Settings → Apps & Connectors → Create (developer mode).
  2. Paste the MCP server URL and choose OAuth as the authentication.
  3. Click Connect, sign in to Brainy Social, choose the workspace and the access, then click Allow.

What a connection can do

  • Read: the Brand Brain tools. Any member of the workspace can connect with read access.
  • Read and publish: the publishing tools too. Only owners, admins and editors can choose it.
  • A connection uses one workspace and acts as the person who allowed it, with their current role. If they leave the workspace or their account is suspended, it stops working.
  • Editors' posts still wait for approval when the workspace requires approval.
  • Every connection is listed in AI & MCP → Connected apps, where it can be disconnected at any time.
  • MCP access is included from the Growth plan.

Claude Code, Cursor and other MCP clients

Clients without one-click sign-in, and headless agents, use an agent API key: in the app open the gear menu → AI & MCP → MCP server → Agent API keys, choose Read or Read and publish and an expiry, and create the key (it is shown once). Then add the server with that key, for example in Claude Code:

claude mcp add --transport http brainy https://brainy-social.com/api/mcp \
  --header "Authorization: Bearer bsk_EXAMPLE_not_a_real_token"

Setup for every client

Copy-paste configs for Claude, ChatGPT, Claude Code, Cursor, VS Code, Codex, Windsurf and the mcp-remote bridge, with sign-in or an API key. The AI in those clients is billed by their own account, not by Brainy.

Open the connect guide

MCP tools

Arguments are the same as the REST fields below. The assistant runs on its own account (Claude, ChatGPT…): it doesn't use your workspace's AI key.

Brand Brain (every connection)

get_brand_prompt
The complete brand guide as a ready-to-use prompt: voice and tone, products, audiences, competitors, goals and seasons.
get_brand_brain
The Brand Brain as structured JSON, with each field's source and whether it is verified.
search_brand_brain
Finds Brand Brain entries (products, audiences, competitors…) that contain the query words, in Arabic or English.
list_products
Products and services with price, currency, offers and whether they are featured.

Publishing (read and publish only)

list_social_accounts
The workspace's connected social accounts with their ids, platform, handle, status and followers.
upload_media_from_url
Imports a public https image (JPEG, PNG, WebP up to 10 MB) or video (MP4, MOV up to 50 MB) and returns a media id.
create_post
Creates a post for one or more platforms: publish now, schedule it, or save it as a draft. Carousels take 2–10 files.
list_posts
Lists recent posts, or drafts, filtered by status.
get_post
One post with its status, schedule, permalink and last error.
cancel_post
Cancels a post that is waiting for approval, scheduled or failed.
get_post_metrics
A published post's views, reach, likes, comments, shares, saves and engagement rate, with history.
get_account_metrics
An account's followers over time and post totals for a date range.
list_webhooks
The workspace's outgoing webhooks (owners and admins).
create_webhook
Subscribes an https URL to events (post published, new message, new comment, new lead). Returns the signing secret once.
delete_webhook
Removes a webhook.
list_events
Recent events with the same payloads webhooks receive, newest first, for polling.

REST publishing API

The same operations as the MCP publishing tools, for your own code and automations. JSON in, JSON out.

Authentication

  • Send an agent API key with every request: Authorization: Bearer bsk_…
  • Create it in the app: gear menu → AI & MCP → MCP server → Agent API keys → Read and publish → Create key. It is shown once, can expire, and can be revoked on the same page.
  • A publish token acts as the person who created it, with their current role. Read tokens get 403 on this API.
  • OAuth connections (Claude, ChatGPT) only work on the MCP server, not on the REST API.
  • Call the API from a server: browser origins are refused.

Conventions

  • Success: { "data": … }. Errors: { "error": { "code", "message" } } with codes such as invalid, unauthorized, plan_limit, forbidden, not_found, conflict, media and rate_limited.
  • Request fields are snake_case; responses use camelCase.
  • Times are ISO 8601, and scheduled_at must include an offset (for example +02:00 or Z). Posts can be scheduled up to a year ahead.
  • Request bodies are limited to 64 KB: media is imported from a link, not uploaded in the body.
  • Captions you send are published as written: no AI rewrites them, and posts created through the API never use the plan's AI posts.
  • Publishing is asynchronous: poll the post until it is published. Failures retry automatically before they are marked failed.

Endpoints

EndpointMCP toolWhat it does
GET /api/v1/accountslist_social_accountsConnected social accounts.
POST /api/v1/mediaupload_media_from_urlImport an image or video from a public https link.
POST /api/v1/postscreate_postCreate, schedule or publish a post on one or more platforms.
GET /api/v1/postslist_postsRecent posts (?status=&limit=), or drafts with status=draft.
GET /api/v1/posts/{id}get_postOne post or draft.
POST /api/v1/posts/{id}/cancelcancel_postCancel a post that hasn't been published (DELETE on the post also works).
GET /api/v1/posts/{id}/metricsget_post_metricsMetrics of a published post.
GET /api/v1/accounts/{id}/metricsget_account_metricsFollowers and totals for an account (?from=&to=, default the last 30 days).
GET /api/v1/webhookslist_webhooksOutgoing webhooks (owners and admins).
POST /api/v1/webhookscreate_webhookSubscribe a URL to events (REST hooks for Zapier, Make, n8n). The secret is in the answer, once.
DELETE /api/v1/webhooks/{id}delete_webhookUnsubscribe a webhook.
GET /api/v1/eventslist_eventsRecent events (?type=&since=&limit=), for polling triggers.

Example

The token below is a placeholder, not a real token.

TOKEN=bsk_EXAMPLE_not_a_real_token
API=https://brainy-social.com/api/v1

curl -s "$API/accounts" -H "Authorization: Bearer $TOKEN"

curl -s -X POST "$API/posts" -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{
  "platforms": ["instagram", "facebook"],
  "caption": "Our new roast is here",
  "hashtags": ["coffee", "cairo"],
  "mode": "schedule",
  "scheduled_at": "2026-12-20T18:30:00+02:00"
}'

Rate limits (per token)

  • Read: 120 requests a minute.
  • Write (create, cancel): 20 a minute, 300 a day.
  • Media imports: 10 a minute, 100 a day.

Zapier, Make and n8n

Get signed webhooks when a post goes out, a message or comment arrives, or a link-in-bio lead comes in — with setup steps for each tool and signature checks.

Open the automations guide

Your own AI key (BYOK)

Brainy Social's AI features run on your workspace's own API key, and MCP clients run on their own account. Your AI usage is never billed on ours.

  • Add a key from Anthropic (Claude), OpenAI (ChatGPT) or Google (Gemini) in AI & MCP. Keys are verified, stored encrypted, and only their last four characters are ever shown.
  • The provider bills you directly for what it uses, and you choose the model for each task.
  • A ChatGPT Plus or Claude Pro subscription isn't an API key: those are for the chat apps and billed separately.
  • Without a key, Brainy uses simple offline templates. Posts you write yourself, and posts created through the API, never need AI.
  • Assistants connected over MCP use their own account, so they don't spend your key either: Brainy runs no model for MCP calls.
  • One exception, when enabled: while a new workspace without a key is set up, the onboarding assistant and the website / file import may use a small, capped amount of Brainy's own AI for free. It ends when onboarding is complete.

Plans

MCP and API access are included from the Growth plan. Publishing through them follows the same plan limits and approval rules as the app.

See pricing