Skip to main content

MCP Server

PostBoost exposes an MCP (Model Context Protocol) server, so AI assistants can plan, draft, schedule and review your social media posts and read their analytics — no custom integration required.

There are two servers:

Connector (recommended)Advanced (API mirror)
URLhttps://postboost.co/mcphttps://postboost.co/mcp/postboost
Sign-inOAuth 2.1 in the client (or a dashboard access token)Dashboard access token (Authorization: Bearer)
Tools46 curated workflow tools with titles and safety annotationsOne tool per REST operation (82 tools, including admin, billing and AI image tools)
Best forClaude.ai, ChatGPT, Claude Code, Cursor, VS Code, WindsurfScripts and agents that already use the REST API and want every operation

Connector endpoint:

https://postboost.co/mcp

A third, public server needs no account at all: the free tools server at https://postboost.co/mcp/tools.


Connect your assistant​

The connector uses OAuth 2.1 with PKCE and dynamic client registration, so most clients only need the URL: they discover the sign-in flow themselves, open the PostBoost login page in your browser and ask you to approve the connection. No tokens to copy.

Claude.ai (web and desktop)​

  1. Go to Settings → Connectors → Add custom connector
  2. Name: PostBoost, URL: https://postboost.co/mcp
  3. Click Add, then Connect and approve the connection on the PostBoost consent screen

ChatGPT​

  1. Open Plugins in ChatGPT, click + and choose Add custom MCP server
  2. Name: PostBoost, server URL: https://postboost.co/mcp
  3. Authentication: OAuth, then confirm the risk warning (I understand and want to continue)
  4. Select Create as a plugin, install it, and sign in and approve on the PostBoost consent screen
  5. In a chat, type @ and pick PostBoost

ChatGPT asks you to confirm before write actions. On a company workspace an admin may need to allow custom MCP servers first.

Claude Code​

claude mcp add --transport http --scope user postboost https://postboost.co/mcp

Then run /mcp inside Claude Code and choose Authenticate next to postboost. Headless (CI) use: add --header "Authorization: Bearer YOUR_API_TOKEN" instead and skip the sign-in. Full guide: Use PostBoost with Claude Code.

Cursor​

Add to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{
"mcpServers": {
"postboost": {
"url": "https://postboost.co/mcp"
}
}
}

Or install in one click: Add PostBoost to Cursor.

Cursor opens the sign-in when you first enable the server. Full guide: Use PostBoost with Cursor.

VS Code (GitHub Copilot)​

Add to .vscode/mcp.json:

{
"servers": {
"postboost": {
"type": "http",
"url": "https://postboost.co/mcp"
}
}
}

Windsurf, Cline, Continue, Zed and others​

Any client that supports remote Streamable HTTP servers with OAuth can use https://postboost.co/mcp. If your client cannot run an OAuth flow, pass a dashboard access token instead: add the header Authorization: Bearer YOUR_API_TOKEN to the same URL (see Authentication).


Connector tools​

The connector has 46 tools: 24 read, 21 write and 1 destructive. Every tool except list-workspaces, count-characters and check-post takes a workspace uuid; call list-workspaces first. Each tool carries MCP annotations so your client can ask for confirmation before changes: readOnlyHint, destructiveHint, idempotentHint and openWorldHint (true when the tool can reach a social network or a public URL).

Read (24)​

ToolWhat it does
list-workspacesWorkspaces you can access, with your role
get-workspaceOne workspace: name, your role, counts
list-accountsConnected social accounts and their numeric ids
get-accountOne account: provider, authorization status, profile
list-postsPosts filtered by account, status, tags, keyword or dates
get-postOne post: status, schedule, versions, live URLs, errors
list-tagsTags with ids and colours
list-mediaMedia library files with ids and URLs
get-media-upload-statusProgress of a background upload started by upload-media-by-url
get-analytics-summaryWorkspace-wide followers, growth and post counts for a period
get-account-analyticsOne account's analytics by type (overview, audience, posts, ...)
get-post-analyticsViews, likes, comments and shares of a published post
get-best-posting-timesBest weekday/hour slots per account and the next concrete slot to use
validate-postDry run of create-post (same arguments): content errors, guardrail issues (duplicate, daily cap, unauthorized account, X allowance once enforced) and account health, nothing created
get-account-healthPer account: authorized, token present, daily cap used today; plus this month's X usage against the allowance
get-ai-creditsAI text credits used, limit and remaining this billing cycle, and image credits this month; check before repurpose-content
get-brand-voiceThe workspace brand voice (tone, audience, topics, words to avoid, example posts)
list-automationsRecycling rules and RSS feed auto-posts set up in the workspace
list-agentsBackground agents switched on (type, schedule, last run)
list-agent-proposalsThe approval queue: what agents propose (hold_post, edit_caption, retry_account, reconnect_account) and why; pending by default
list-inbox-draftsReply drafts waiting for a person in the social inbox
get-repurpose-runStatus of a repurpose-content run that took longer than the wait; the draft and captions once it is done
count-charactersHow long a text is on each network as that network counts it, its limit and whether it is over; no workspace needed
check-postA text and its media checked against each network's publishing rules (length, hashtags, media count and type, video length) without an account; no workspace needed

Write (21)​

ToolWhat it doesAnnotations
create-postCreate a post; saved as a draft unless you pass schedule. Optional idempotency_key makes a retry safeopen-world
update-postChange content, accounts or tags; schedule untouchedidempotent
schedule-postSchedule for a date/time, or publish now with post_nowopen-world
add-post-to-queueSchedule at the next slot of the posting scheduleopen-world
unschedule-postBack to draft, keeps everything elseidempotent
duplicate-postNew draft copy of a post
attach-tags-to-postAdd tags, keeping the existing onesidempotent
create-tagNew tag
upload-media-by-urlDownload an image, GIF or video from a public URL into the libraryopen-world
restore-postRecover a post from the trash as a draftidempotent
create-connect-linkA single-use 15-minute link that connects a new account on an OAuth network (X, Facebook, Instagram, Threads, LinkedIn, TikTok, YouTube, Pinterest, Google Business Profile). Ask the user to open it in their browser while logged in to PostBoost, wait until they confirm, then call list-accounts for the new account id. Workspace admins only
retry-failed-postPublish a post again to one account whose publishing failed (account id from get-post, or its uuid); accounts that already published are refusedopen-world
update-brand-voiceChange any brand voice fields; the rest are keptidempotent
upload-mediaAdd a small file (base64, up to 20 MB) to the media library
create-recycling-ruleRe-publish one post, or rotate a tag's posts, every N days (queue, same time or draft)open-world
add-rss-feedTurn new items of an RSS/Atom feed into drafts or queued postsopen-world
create-reportCSV or branded PDF analytics report with a 7-day download link
repurpose-contentArticle URL, YouTube video, PDF or text into one draft post with a caption per account and a carousel; a long run answers with a run_id for get-repurpose-runopen-world
approve-agent-proposalApply a pending agent proposal after the user agreedidempotent
reject-agent-proposalRecord a rejection; nothing changes on the postidempotent
create-inbox-draftPropose a reply to a comment or message; a person approves it in the app

create-post, update-post, schedule-post and add-post-to-queue apply the agent guardrails like the API: a duplicate, a full daily cap, an account that needs reconnecting or (once enforced) an exhausted X allowance comes back as a tool error that names the code (for example duplicate_post). Pass allow_duplicate: true only when the user really wants to repeat a post. update-post checks a scheduled post at its scheduled time, so editing it is refused while one of its accounts needs reconnecting; add-post-to-queue checks the day of the queue slot the post will get.

create-post takes an optional idempotency_key (1 to 255 printable ASCII characters, for example a fresh UUID). Reuse the key when you retry the same call, for example after a timeout: within 24 hours the same key and arguments return the first result and create no second post, the same key with other arguments is refused, and a call while the first is still running is told to wait. Refusals and errors are not stored, so a retry after one runs again. It works like the API's Idempotency-Key header.

Deliberately absent: approving inbox replies (a person does that in the app), API-key management, user and billing administration, bulk deletes and AI image generation. The advanced server has all of those.

Destructive (1)​

ToolWhat it does
delete-postMove a post to the trash (restorable) or delete it permanently with permanent: true

Not in the connector on purpose: user and workspace administration, subscriptions, receipts, bulk deletes and AI image generation. They remain available on the advanced server.

Example​

User: Draft a LinkedIn post about our new OAuth connector and schedule it at the best time this week
→ list-workspaces() → [{ uuid: "ws-abc123", name: "Acme Co", role: "admin" }]
→ list-accounts({ workspace: "ws-abc123" }) → [{ id: 7, name: "Acme", provider: "linkedin_page" }]
→ create-post({ workspace: "ws-abc123", account_ids: [7], content: "PostBoost now connects to Claude and ChatGPT ..." })
→ draft post "p-9f1e"
→ get-best-posting-times({ workspace: "ws-abc123", account_ids: [7] }) → next_slots: [{ account_id: 7, scheduled_at: "2026-10-14 09:00", timezone: "Europe/Istanbul" }]
→ schedule-post({ workspace: "ws-abc123", post: "p-9f1e", scheduled_at: "2026-10-14 09:00", timezone: "Europe/Istanbul" })

Authentication​

OAuth 2.1 (default)​

Clients discover everything from the connector URL:

DocumentURL
Protected resource metadata (RFC 9728)https://postboost.co/.well-known/oauth-protected-resource/mcp
Authorization server metadata (RFC 8414)https://postboost.co/.well-known/oauth-authorization-server
Dynamic client registration (RFC 7591)POST https://postboost.co/oauth/register
Authorization endpointhttps://postboost.co/oauth/authorize (PKCE S256 required)
Token endpointhttps://postboost.co/oauth/token (authorization_code, refresh_token)

Scope: mcp:use. Access tokens last one hour and are refreshed silently; refresh tokens last 60 days. The consent screen shows which account you are signed in with; the assistant then acts on every workspace that account can access, with the same role you have there. Revoke access by removing the connector in your client.

Registration accepts https:// redirect URIs on claude.ai, claude.com, chatgpt.com, chat.openai.com, platform.openai.com, localhost / 127.0.0.1 for local development, and the claude://, cursor://, vscode://, vscode-insiders:// and windsurf:// schemes. Need another client? Contact support with the redirect URI and we will register it by hand.

Manual registration (no DCR in your client):

curl -X POST https://postboost.co/oauth/register \
-H "Content-Type: application/json" \
-d '{"client_name": "My agent", "redirect_uris": ["http://localhost:8000/callback"]}'

The response contains a public client_id (no secret; PKCE is mandatory). Use it with any OAuth 2.1 library against the endpoints above.

Dashboard access token (headless)​

The connector also accepts the tokens used by the REST API, which suits CI jobs and agents that cannot open a browser:

Scoped API keys (created with abilities or an account restriction) are refused with 403 insufficient_scope: the connector's tools run outside the API's scope enforcement. Use OAuth, an unscoped dashboard token, or the advanced server below.

  1. Log in to your PostBoost dashboard
  2. Go to your avatar → Access Tokens
  3. Click Create Token, enter a name, and copy the token
warning

Tokens are shown only once. Store them securely.

Send it as Authorization: Bearer YOUR_API_TOKEN on https://postboost.co/mcp. The same token works on the advanced server below.


Advanced server (API mirror)​

https://postboost.co/mcp/postboost

This server exposes one tool per operation in the PostBoost API spec (camelCase names such as listPosts), including user and workspace administration, subscriptions, receipts, mentions and AI image generation. It requires a dashboard access token in the Authorization: Bearer header; it does not support OAuth. Your client's tool list is always the authoritative source.

Client configuration with a token

Claude Code

claude mcp add --transport http --scope user postboost-api https://postboost.co/mcp/postboost \
--header "Authorization: Bearer YOUR_API_TOKEN"

Or a project-level .mcp.json that reads the token from the environment:

{
"mcpServers": {
"postboost-api": {
"type": "http",
"url": "https://postboost.co/mcp/postboost",
"headers": {
"Authorization": "Bearer ${POSTBOOST_API_TOKEN}"
}
}
}
}

Cursor (.cursor/mcp.json), Claude Desktop (claude_desktop_config.json), Windsurf (mcp_config.json, use serverUrl) and Cline share the same shape:

{
"mcpServers": {
"postboost-api": {
"url": "https://postboost.co/mcp/postboost",
"headers": {
"Authorization": "Bearer YOUR_API_TOKEN"
}
}
}
}

VS Code (.vscode/mcp.json):

{
"servers": {
"postboost-api": {
"type": "http",
"url": "https://postboost.co/mcp/postboost",
"headers": {
"Authorization": "Bearer YOUR_API_TOKEN"
}
}
}
}

Continue.dev (~/.continue/config.yaml):

mcpServers:
- name: postboost-api
type: streamable-http
url: https://postboost.co/mcp/postboost
requestOptions:
headers:
Authorization: Bearer YOUR_API_TOKEN

Zed (~/.config/zed/settings.json):

{
"context_servers": {
"postboost-api": {
"settings": {
"url": "https://postboost.co/mcp/postboost",
"headers": {
"Authorization": "Bearer YOUR_API_TOKEN"
}
}
}
}
}

Advanced server tools​

Most workspace-scoped tools require a workspaceUuid. Call listWorkspaces first to get yours.

Accounts (4)​

ToolDescription
listAccountsList all connected social media accounts in a workspace
getAccountGet a single account by UUID
getAccountHealthPre-flight health of every account: authorized, token validity, daily cap left
createConnectLinkSingle-use 15-minute link the signed-in user opens to connect a new OAuth account

Posts (10)​

ToolDescription
listPostsList posts with optional status/tag filters and pagination
getPostGet a single post by UUID
createPostCreate a new post (draft, scheduled, or publish now)
updatePostUpdate an existing post's content or schedule
deletePostDelete a post
deletePostsBulkDelete multiple posts at once
approvePostApprove a post that is pending review
addPostToQueueAdd a post to the publishing queue
schedulePostSchedule a post for a specific date and time
validatePostRun every create-post check (validation, guardrails, per-network rules) without creating anything

Media (9)​

ToolDescription
listMediaList media files in a workspace
getMediaGet a single media file by UUID
updateMediaUpdate media metadata (name, alt text)
deleteMediaBulkDelete multiple media files
initiateRemoteUploadStart a remote URL upload job
getRemoteUploadStatusPoll the status of a remote upload job
initiateChunkedUploadStart a chunked file upload session
completeChunkedUploadFinalize a chunked upload
abortChunkedUploadCancel an in-progress chunked upload

Tags (5)​

ToolDescription
listTagsList all tags in a workspace
getTagGet a single tag by UUID
createTagCreate a new color-coded tag
updateTagUpdate a tag's name or color
deleteTagDelete a tag

Workspaces (7)​

ToolDescription
listWorkspacesList all workspaces (admin only)
getWorkspaceGet a single workspace by UUID
createWorkspaceCreate a new workspace
updateWorkspaceUpdate a workspace's name or settings
deleteWorkspaceDelete a workspace
deleteWorkspacesBulkDelete multiple workspaces
listApiActivityEvery write request made through the API in a workspace, newest first

Users (9)​

ToolDescription
listUsersList all users (admin only)
getUserGet a single user by ID
createUserCreate a new user account
updateUserUpdate a user's profile
deleteUserDelete a user
deleteUsersBulkDelete multiple users
addUserToWorkspaceAdd a user to a workspace with a role
removeUserFromWorkspaceRemove a user from a workspace
updateWorkspaceUserChange a user's role in a workspace

Subscriptions (10)​

ToolDescription
getSubscriptionGet the subscription for a workspace
createSubscriptionCreate a new subscription
updateSubscriptionUpdate subscription details
deleteSubscriptionDelete a subscription record
cancelSubscriptionCancel a subscription at period end
resumeSubscriptionResume a cancelled subscription
changeSubscriptionPlanUpgrade or downgrade a subscription plan
checkoutSubscriptionGenerate a checkout URL for a new subscription
addGenericSubscriptionManually grant a subscription (e.g., lifetime deals)
removeGenericSubscriptionRemove a manually granted subscription

Receipts (6)​

ToolDescription
listReceiptsList billing receipts
getReceiptGet a single receipt
createReceiptCreate a receipt record
updateReceiptUpdate a receipt
deleteReceiptDelete a receipt
deleteReceiptsBulkDelete multiple receipts

AI (6)​

ToolDescription
blogToSocialGenerate platform-specific social media captions from a blog post URL or title and excerpt. Consumes one AI credit per platform.
imagePromptBuild a professional image generation prompt from a caption and platform. Use to preview the prompt before calling imageGenerate. Costs 1 AI credit.
imageGenerateGenerate one or more social media images from a caption (standard mode) or raw prompt (developer mode). Images are saved to the workspace media library. Credits: 1 image credit per image (429 image_credits_exhausted when the monthly pool is empty); count × credit_weight text credits only if the image pool is switched off.
imageEditEdit an existing workspace media image using a text prompt and optional mask. Results are saved to the media library. Credits: 1 image credit per image (429 image_credits_exhausted when the monthly pool is empty); count × credit_weight text credits only if the image pool is switched off.
imageVariationsGenerate one or more variations of an existing workspace media image. Results are saved to the media library. Credits: 1 image credit per image (429 image_credits_exhausted when the monthly pool is empty); count × credit_weight text credits only if the image pool is switched off.
imageAltTextAnalyze a workspace media image and generate accessible alt text, saved back to the media record. Costs 1 AI credit.

Platform MCP server (additional option)​

PostBoost also exposes a platform-level MCP server with 30 tools (kebab-case names, such as list-posts) at https://postboost.co/app/mcp. It takes the same dashboard access tokens. The connector above is built on the same tools, adds titles and annotations, and drops the ones an assistant should not have.


Public free-tools server (/mcp/tools, no account)​

https://postboost.co/mcp/tools

This server gives your assistant PostBoost's free tools (character counter, post checker, X thread maker, LinkedIn formatter, UTM builder and more) with no account and no sign-in. It has one tool per free tool, named after its API operation in kebab case (split-thread, count-characters); the Free Tools API overview lists them all.

Calls without a token have the per-IP free tools limits. To raise them, add Authorization: Bearer YOUR_API_TOKEN with any PostBoost access token; an invalid token is refused, never treated as a guest.

Claude Desktop​

Go to Settings → Connectors → Add custom connector, name it PostBoost Free Tools, enter https://postboost.co/mcp/tools and click Add. There is nothing to sign in to.

Or add it to claude_desktop_config.json through the mcp-remote bridge (needs Node.js), then restart Claude Desktop:

{
"mcpServers": {
"postboost-tools": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://postboost.co/mcp/tools"]
}
}
}

Claude Code​

claude mcp add --transport http --scope user postboost-tools https://postboost.co/mcp/tools

No /mcp sign-in step. With a token: append --header "Authorization: Bearer YOUR_API_TOKEN".

Cursor​

Add to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{
"mcpServers": {
"postboost-tools": {
"url": "https://postboost.co/mcp/tools"
}
}
}

With a token, add "headers": { "Authorization": "Bearer YOUR_API_TOKEN" } next to url.

Then ask, for example: Split this into an X thread with the PostBoost split-thread tool. Other clients use the same URL as any remote Streamable HTTP server.


Troubleshooting​

ProblemSolution
The client never opens a sign-in pageMake sure the URL is exactly https://postboost.co/mcp and that your client supports OAuth for remote MCP servers. Otherwise use a dashboard access token header
invalid_redirect_uri during registrationYour client's callback domain is not on the allow-list; contact support with the redirect URI
Unauthenticated with a tokenVerify the token is valid; regenerate it in your avatar → Access Tokens if needed
Workspace not found or you do not have accessThe uuid is wrong or the signed-in user is not a member. Call list-workspaces
The MCP is not available for this workspaceThe workspace's plan has MCP access disabled
Access forbidden on the advanced serverAdmin-only tools (workspaces, users, subscriptions) need a token that belongs to an admin user
Tools not showingCheck your client's MCP panel to confirm the connection is active and authenticated

Next steps​