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) | |
|---|---|---|
| URL | https://postboost.co/mcp | https://postboost.co/mcp/postboost |
| Sign-in | OAuth 2.1 in the client (or a dashboard access token) | Dashboard access token (Authorization: Bearer) |
| Tools | 46 curated workflow tools with titles and safety annotations | One tool per REST operation (82 tools, including admin, billing and AI image tools) |
| Best for | Claude.ai, ChatGPT, Claude Code, Cursor, VS Code, Windsurf | Scripts 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)
- Go to Settings → Connectors → Add custom connector
- Name:
PostBoost, URL:https://postboost.co/mcp - Click Add, then Connect and approve the connection on the PostBoost consent screen
ChatGPT
- Open Plugins in ChatGPT, click + and choose Add custom MCP server
- Name:
PostBoost, server URL:https://postboost.co/mcp - Authentication: OAuth, then confirm the risk warning (I understand and want to continue)
- Select Create as a plugin, install it, and sign in and approve on the PostBoost consent screen
- 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)
| Tool | What it does |
|---|---|
list-workspaces | Workspaces you can access, with your role |
get-workspace | One workspace: name, your role, counts |
list-accounts | Connected social accounts and their numeric ids |
get-account | One account: provider, authorization status, profile |
list-posts | Posts filtered by account, status, tags, keyword or dates |
get-post | One post: status, schedule, versions, live URLs, errors |
list-tags | Tags with ids and colours |
list-media | Media library files with ids and URLs |
get-media-upload-status | Progress of a background upload started by upload-media-by-url |
get-analytics-summary | Workspace-wide followers, growth and post counts for a period |
get-account-analytics | One account's analytics by type (overview, audience, posts, ...) |
get-post-analytics | Views, likes, comments and shares of a published post |
get-best-posting-times | Best weekday/hour slots per account and the next concrete slot to use |
validate-post | Dry 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-health | Per account: authorized, token present, daily cap used today; plus this month's X usage against the allowance |
get-ai-credits | AI text credits used, limit and remaining this billing cycle, and image credits this month; check before repurpose-content |
get-brand-voice | The workspace brand voice (tone, audience, topics, words to avoid, example posts) |
list-automations | Recycling rules and RSS feed auto-posts set up in the workspace |
list-agents | Background agents switched on (type, schedule, last run) |
list-agent-proposals | The approval queue: what agents propose (hold_post, edit_caption, retry_account, reconnect_account) and why; pending by default |
list-inbox-drafts | Reply drafts waiting for a person in the social inbox |
get-repurpose-run | Status of a repurpose-content run that took longer than the wait; the draft and captions once it is done |
count-characters | How long a text is on each network as that network counts it, its limit and whether it is over; no workspace needed |
check-post | A 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)
| Tool | What it does | Annotations |
|---|---|---|
create-post | Create a post; saved as a draft unless you pass schedule. Optional idempotency_key makes a retry safe | open-world |
update-post | Change content, accounts or tags; schedule untouched | idempotent |
schedule-post | Schedule for a date/time, or publish now with post_now | open-world |
add-post-to-queue | Schedule at the next slot of the posting schedule | open-world |
unschedule-post | Back to draft, keeps everything else | idempotent |
duplicate-post | New draft copy of a post | |
attach-tags-to-post | Add tags, keeping the existing ones | idempotent |
create-tag | New tag | |
upload-media-by-url | Download an image, GIF or video from a public URL into the library | open-world |
restore-post | Recover a post from the trash as a draft | idempotent |
create-connect-link | A 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-post | Publish a post again to one account whose publishing failed (account id from get-post, or its uuid); accounts that already published are refused | open-world |
update-brand-voice | Change any brand voice fields; the rest are kept | idempotent |
upload-media | Add a small file (base64, up to 20 MB) to the media library | |
create-recycling-rule | Re-publish one post, or rotate a tag's posts, every N days (queue, same time or draft) | open-world |
add-rss-feed | Turn new items of an RSS/Atom feed into drafts or queued posts | open-world |
create-report | CSV or branded PDF analytics report with a 7-day download link | |
repurpose-content | Article 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-run | open-world |
approve-agent-proposal | Apply a pending agent proposal after the user agreed | idempotent |
reject-agent-proposal | Record a rejection; nothing changes on the post | idempotent |
create-inbox-draft | Propose 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)
| Tool | What it does |
|---|---|
delete-post | Move 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:
| Document | URL |
|---|---|
| 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 endpoint | https://postboost.co/oauth/authorize (PKCE S256 required) |
| Token endpoint | https://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.
- Log in to your PostBoost dashboard
- Go to your avatar → Access Tokens
- Click Create Token, enter a name, and copy the token
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)
| Tool | Description |
|---|---|
listAccounts | List all connected social media accounts in a workspace |
getAccount | Get a single account by UUID |
getAccountHealth | Pre-flight health of every account: authorized, token validity, daily cap left |
createConnectLink | Single-use 15-minute link the signed-in user opens to connect a new OAuth account |
Posts (10)
| Tool | Description |
|---|---|
listPosts | List posts with optional status/tag filters and pagination |
getPost | Get a single post by UUID |
createPost | Create a new post (draft, scheduled, or publish now) |
updatePost | Update an existing post's content or schedule |
deletePost | Delete a post |
deletePostsBulk | Delete multiple posts at once |
approvePost | Approve a post that is pending review |
addPostToQueue | Add a post to the publishing queue |
schedulePost | Schedule a post for a specific date and time |
validatePost | Run every create-post check (validation, guardrails, per-network rules) without creating anything |
Media (9)
| Tool | Description |
|---|---|
listMedia | List media files in a workspace |
getMedia | Get a single media file by UUID |
updateMedia | Update media metadata (name, alt text) |
deleteMediaBulk | Delete multiple media files |
initiateRemoteUpload | Start a remote URL upload job |
getRemoteUploadStatus | Poll the status of a remote upload job |
initiateChunkedUpload | Start a chunked file upload session |
completeChunkedUpload | Finalize a chunked upload |
abortChunkedUpload | Cancel an in-progress chunked upload |
Tags (5)
| Tool | Description |
|---|---|
listTags | List all tags in a workspace |
getTag | Get a single tag by UUID |
createTag | Create a new color-coded tag |
updateTag | Update a tag's name or color |
deleteTag | Delete a tag |
Workspaces (7)
| Tool | Description |
|---|---|
listWorkspaces | List all workspaces (admin only) |
getWorkspace | Get a single workspace by UUID |
createWorkspace | Create a new workspace |
updateWorkspace | Update a workspace's name or settings |
deleteWorkspace | Delete a workspace |
deleteWorkspacesBulk | Delete multiple workspaces |
listApiActivity | Every write request made through the API in a workspace, newest first |
Users (9)
| Tool | Description |
|---|---|
listUsers | List all users (admin only) |
getUser | Get a single user by ID |
createUser | Create a new user account |
updateUser | Update a user's profile |
deleteUser | Delete a user |
deleteUsersBulk | Delete multiple users |
addUserToWorkspace | Add a user to a workspace with a role |
removeUserFromWorkspace | Remove a user from a workspace |
updateWorkspaceUser | Change a user's role in a workspace |
Subscriptions (10)
| Tool | Description |
|---|---|
getSubscription | Get the subscription for a workspace |
createSubscription | Create a new subscription |
updateSubscription | Update subscription details |
deleteSubscription | Delete a subscription record |
cancelSubscription | Cancel a subscription at period end |
resumeSubscription | Resume a cancelled subscription |
changeSubscriptionPlan | Upgrade or downgrade a subscription plan |
checkoutSubscription | Generate a checkout URL for a new subscription |
addGenericSubscription | Manually grant a subscription (e.g., lifetime deals) |
removeGenericSubscription | Remove a manually granted subscription |
Receipts (6)
| Tool | Description |
|---|---|
listReceipts | List billing receipts |
getReceipt | Get a single receipt |
createReceipt | Create a receipt record |
updateReceipt | Update a receipt |
deleteReceipt | Delete a receipt |
deleteReceiptsBulk | Delete multiple receipts |
AI (6)
| Tool | Description |
|---|---|
blogToSocial | Generate platform-specific social media captions from a blog post URL or title and excerpt. Consumes one AI credit per platform. |
imagePrompt | Build a professional image generation prompt from a caption and platform. Use to preview the prompt before calling imageGenerate. Costs 1 AI credit. |
imageGenerate | Generate 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. |
imageEdit | Edit 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. |
imageVariations | Generate 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. |
imageAltText | Analyze 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
| Problem | Solution |
|---|---|
| The client never opens a sign-in page | Make 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 registration | Your client's callback domain is not on the allow-list; contact support with the redirect URI |
Unauthenticated with a token | Verify the token is valid; regenerate it in your avatar → Access Tokens if needed |
Workspace not found or you do not have access | The uuid is wrong or the signed-in user is not a member. Call list-workspaces |
The MCP is not available for this workspace | The workspace's plan has MCP access disabled |
Access forbidden on the advanced server | Admin-only tools (workspaces, users, subscriptions) need a token that belongs to an admin user |
| Tools not showing | Check your client's MCP panel to confirm the connection is active and authenticated |
Next steps
- Connect your AI agent — per-client setup guides
- Agent guardrails — duplicate, daily-cap and reconnect checks on every write
- Network permissions status — what each social network allows today