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/mcpIn Claude (claude.ai or Claude Desktop)
- Open Settings → Connectors → Add custom connector.
- Paste the MCP server URL and click Add, then Connect.
- Brainy Social opens: sign in if asked, choose the workspace and the access (read, or read and publish), then click Allow.
- You're back in Claude with the Brainy tools turned on.
In ChatGPT
- Open Settings → Apps & Connectors → Create (developer mode).
- Paste the MCP server URL and choose OAuth as the authentication.
- 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 guideMCP 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
403on 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 asinvalid,unauthorized,plan_limit,forbidden,not_found,conflict,mediaandrate_limited. - Request fields are
snake_case; responses usecamelCase. - Times are
ISO 8601, andscheduled_atmust include an offset (for example+02:00orZ). 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
| Endpoint | MCP tool | What it does |
|---|---|---|
GET /api/v1/accounts | list_social_accounts | Connected social accounts. |
POST /api/v1/media | upload_media_from_url | Import an image or video from a public https link. |
POST /api/v1/posts | create_post | Create, schedule or publish a post on one or more platforms. |
GET /api/v1/posts | list_posts | Recent posts (?status=&limit=), or drafts with status=draft. |
GET /api/v1/posts/{id} | get_post | One post or draft. |
POST /api/v1/posts/{id}/cancel | cancel_post | Cancel a post that hasn't been published (DELETE on the post also works). |
GET /api/v1/posts/{id}/metrics | get_post_metrics | Metrics of a published post. |
GET /api/v1/accounts/{id}/metrics | get_account_metrics | Followers and totals for an account (?from=&to=, default the last 30 days). |
GET /api/v1/webhooks | list_webhooks | Outgoing webhooks (owners and admins). |
POST /api/v1/webhooks | create_webhook | Subscribe a URL to events (REST hooks for Zapier, Make, n8n). The secret is in the answer, once. |
DELETE /api/v1/webhooks/{id} | delete_webhook | Unsubscribe a webhook. |
GET /api/v1/events | list_events | Recent 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 guideYour 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